@m0saic/knowledge 0.2.0

package/docs/skills/more-atoms-not-bigger-atoms.md

@@ -0,0 +1,77 @@
+# More atoms, never bigger atoms — the scaling contract with ffmpeg
+
+> The measured cliffs behind atom 1 (and the "graph-size OOM" debunk) live in
+> [`../runtime/ffmpeg-expression-limits.md`](../runtime/ffmpeg-expression-limits.md).
+> This is the general principle; that is the case study.
+
+m0saic renders arbitrarily complex templates by splitting work into pieces.
+That works because ffmpeg capacity scales with the NUMBER of things it is
+given (commands, inputs, filters, files). It breaks when a feature grows a
+single UNPARTITIONABLE ATOM with content. Chunking cannot rescue a bigger
+atom — the atom is smaller than a command.
+
+## The four atoms (with measured walls)
+
+1. **One expression string.** `av_expr_parse` has a ~100 recursion budget:
+   ~98 flat `+` terms or ~100 nesting levels, independent of char length.
+   Failure is a phantom `Cannot allocate memory` (−12) or `Invalid
+   argument` (−22) at graph init, in <80 ms. Applies to EVERY expression:
+   `enable`, `geq`, crop/scale/drawtext params, `%{eif}`.
+2. **One filter's per-frame work.** `geq` interprets its expression per
+   pixel per plane per frame (nodes × W × H × fps). No crash — render time
+   explodes. Chunking does not reduce it: same pixels either way.
+3. **One frame's memory.** frames-in-flight × W × H × 4 B. Buffering
+   filters (`loop=size=N`, `split`, framesync queues, `tpad`) and
+   resolution multiply it; filter COUNT does not (12,000 chained filters /
+   1.19 MB single graph verified fine).
+4. **One process's argv.** Windows caps ~32 K → `ENAMETOOLONG`.
+
+## The classification test (apply to any content-scaled feature)
+
+When something scales with content (N tiles, steps, keyframes, data
+points), ask: **which quantity grows?**
+
+- Count of commands / inputs / filters / workspace files grows → MORE
+  ATOMS → fine; capacity, chunkable.
+- A single expression, a single filter's per-pixel cost, a single frame's
+  resident bytes, or argv grows → BIGGER ATOM → redesign before shipping.
+
+## Bigger-atom anti-patterns → more-atoms replacements
+
+| anti-pattern (bigger atom) | replacement (more atoms / bounded atom) |
+|---|---|
+| nested `if(cond,…,else)` per keyframe (`expr = if(...,${expr})` builders) | flat gated sum: `lt(t,t0)*(v0)+(gte·lt)*seg+…+gte(t,tN)*(vN)` |
+| `.join("+")` on a content-scaled window list, emitted raw | route through the funnels (below) or `rebalanceAdditiveChains` |
+| `geq` on a canvas/panel-sized stream | static SVG/PNG mask + `alphamerge`; keep geq on small intermediates |
+| animated values as ever-larger exprs | pre-render to a small intermediate (value `.mov`s, text renders) |
+| content-scaled string inline in argv (`-i lavfi`, drawtext text) | workspace file (`-filter_complex_script`, `-graph_file`, `textfile=`) |
+| full-res lossless-alpha (qtrle/argb) intermediates on opaque nodes | alpha intermediates only where alpha flows |
+
+## Existing enforcement (route new work through these; do not bypass)
+
+- `rebalanceAdditiveChains` (`@m0saic/platform` ffexpr) auto-applied at the
+  funnels: `quoteEnableArg` (all `:enable=`), `buildOverlayAlphaFilter`
+  (enable→geq alpha fold), `buildCameraFilters` (zoom/focus). >32 flat
+  terms → balanced tree (O(log n) depth, verified past 1024 terms); ≤32
+  passes byte-identical. It CANNOT fix nesting — builders must emit flat
+  shapes.
+- Input-count split (`maxInputsPerCommand`) — more commands per node.
+- Graph/text file lowering — argv atom stays constant.
+- SVG rounding rasterizer (default) — rounding is a mask input, not geq.
+
+Known bypasses to watch: hand-rolled lavfi `enable=` strings (dsl-string
+caret track, dsl-canvas drawbox — currently ≤3 terms) and nested-if
+builders in other templates (e.g. line-chart anim) that will hit atom 1 if
+their datasets grow.
+
+## Review greps
+
+`join("+")` on generated arrays; recursive expr accumulation
+(`= \`if(…,${expr})\``); `geq` fed by canvas-sized labels; content
+interpolation into `-i`/argv rather than a workspace file.
+
+---
+
+*Per-pixel eval cost (atom 2) is the next practical wall at denser grids — a
+perf ceiling, not a crash; fix it representationally (masks, pre-rendered
+intermediates), not by chunking.*

package/docs/skills/overlay-semantics.md

@@ -0,0 +1,194 @@
+## Overlay Semantics & Paint Order
+
+Overlays are recursive layout subtrees rendered inside an owner's rect — a first-class
+compositional primitive, not just "layers". This doc covers attachment, paint order,
+deferred zero-overlay paint, the overlay-body validity rule, and composition at scale.
+
+> **Source of truth:** overlay parsing in [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts);
+> overlay-body validation in [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts)
+> (relaxation comment at lines 479–486); error codes in [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/errors/errors.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/errors/errors.ts).
+> Every accept/reject example below was runtime-verified against https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/dist
+> via `validateM0String` on 2026-07-27.
+
+## Attachment: any node can own an overlay
+
+Form:
+
+    node{ overlay_body }
+
+`node` may be ANY node kind — not just `1`:
+
+- `1` (tile), `0` (passthrough), `-` (null — child position only; see Logical Owner)
+- `N(...)` / `N[...]` (splits)
+- a node that is itself an overlay owner (chains)
+
+No base `1` is required for an overlay to exist. A chain of full layouts is legal:
+
+    2(1,1){3(1,1,1){2(1,1)}}    — base 2-col, overlay 3-col, overlay-on-overlay 2-col
+
+Rules:
+
+- At most ONE immediate overlay object per node — `1{1}{1}` rejects
+  (`OVERLAY_CHAIN`). Stack by nesting instead: `1{1{1}}`.
+- The overlay body must validate independently as a full m0 string, recursively.
+- Nesting depth is structurally unbounded — but see the render-cost caveat below.
+
+Valid: `1{1}` · `2(1,1){1}` · `1{1{1}}` · `2(1,1){3(1,1,1){2(1,1)}}`
+
+## Overlay rect = owner rect
+
+The overlay subtree is parsed against owner.x / owner.y / owner.width / owner.height.
+
+- It does NOT inherit sibling geometry.
+- It does NOT escape its parent rect.
+
+Applies to tile, group, null, and zero overlays alike.
+
+## Overlays never mutate geometry
+
+Overlay stacking, at any depth:
+
+- does NOT change splitEven results or sibling sizes
+- does NOT change structuralDepth
+- does NOT alter stableKeys of the base structure
+
+It only increments `overlayDepth` and adds paint layers. The base layout defines
+geometry; overlay chains define drawing.
+
+## Paint order
+
+Deterministic, defined by engine traversal.
+
+### Tile overlay
+
+    1{1}
+
+1. Base tile
+2. Overlay subtree (immediately after owner)
+
+### Group overlay
+
+    2(1,1){1}
+
+1. Child 0
+2. Child 1
+3. Group overlay — group overlays paint AFTER all base children.
+
+### Zero overlay (deferred paint)
+
+    3(0{1},1,1)
+
+Zero overlays do NOT paint immediately; they defer until the claimant renders:
+
+1. Claimant tile
+2. Deferred zero overlay
+
+Multiple zero overlays in one run:
+
+    3(0{1},0{1},1)
+
+1. Claimant
+2. Larger-area zero overlay
+3. Smaller-area zero overlay (top-most)
+
+Deferred zero overlays are sorted by area DESCENDING → smaller overlays paint on top.
+
+### Claimant with its own overlay
+
+    3(0{1},1{1},1)
+
+1. Claimant tile
+2. Claimant's own overlay
+3. Deferred zero overlay — always after the claimant AND the claimant's overlay.
+
+### Nested overlays
+
+    1{1{1}}
+
+1. Base tile
+2. First overlay
+3. Nested overlay
+
+## Logical owner `-`
+
+`-{X}` marks `isLogicalOwner = true`: the base does not render, but the overlay rect
+exists and carry is still absorbed if it is a claimant. Use for editor semantics and
+labeling containers.
+
+Position matters: `-{...}` is valid in a child slot or inside an overlay body, NOT as
+the whole-string root — `2(-{1},1)` and `1{-{1}}` accept; bare `-{1}` rejects
+(`TOKEN_RULE`), as does a bare `-` root (`INVALID_EMPTY`).
+
+## Overlay depth vs structural depth
+
+Two independent counters:
+
+- `structuralDepth` — increases entering numeric containers; root = 0.
+- `overlayDepth` — increases entering `{...}`; base layout = 0, first overlay = 1.
+
+Overlay frames inherit the structuralDepth of their context and use a separate frame
+namespace.
+
+## Overlay body node rule (`INVALID_EMPTY`)
+
+An overlay body `{...}` must contribute at least ONE node to the graph, but does not
+have to paint. Logical-owner anchors (`-{X}`) are the common shape.
+
+Rejected — zero nodes, or a single root with nothing to act on:
+
+    1{}        — empty body; no nodes at all
+    1{0}       — bare passthrough at the overlay root; nothing to donate to
+    1{-{}}     — recursive: the inner `{}` is rejected (deepest offender reported)
+
+Accepted — at least one node, even if nothing paints:
+
+    1{-}              — single null node; logical-owner anchor
+    1{2(-,-)}         — all-null split; structural nodes, no paint
+    1{2(0,-)}         — passthrough with a sibling to donate space to
+    1{-{-}}           — nested logical owners
+    1{-{2(0,-)}}      — nested with structural content
+    1{2(-,1)}         — overlay body has a source (always valid)
+    1{2[1,1]{1}}      — nested overlay body has a source
+
+The legacy `ZERO_SOURCE_OVERLAY` rule (body must contain at least one leaf `1`) was
+relaxed 2026-06-03 — overlay bodies no longer have to paint, only exist as nodes
+([`m0StringValidator.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts):479–486).
+The whole-string `NO_SOURCES` check still requires the OUTER (root) layout to produce
+at least one source tile, so the renderer is never asked to draw a fully empty canvas.
+
+Error code when rejected: `INVALID_EMPTY` (kind `SYNTAX`).
+
+## Composition at scale: deep overlay stacks
+
+Overlay chains are how large rect sets are composed: each `{}` wraps a full valid
+subtree, and each layer paints inside the owner's rect. A 109-overlay brand mark —
+each overlay an independently calculated m0saic drawing one precise rectangle — is a
+measured working example; its serialized string ran to tens of thousands of
+characters, which parse/validate/walk handle without issue.
+
+Deep stacks are editor-clean: each overlay is its own layer, filterable by
+`overlayDepth`, structurally independent, with no geometry coupling.
+
+Use deep overlays for programmatic rect emission — dictionary-based layouts, glyphs,
+masks, strict layering control. Prefer a single split when it expresses intent more
+clearly or raw-string readability matters.
+
+> ⚠️ **Render-cost caveat** (measured 2026-07-02): depth is free structurally, NOT at
+> render time. Each overlay level is one sequential blend pass on ffmpeg's single
+> graph thread, and past ~25 nested overlay layers inline-masks silently degrade
+> (circles→squares, text→tofu) — engine wall W3. Deep stacks are cheap to WRITE
+> and inspect, not cheap to RENDER — collapse time-disjoint line geometry into
+> lavfi tracks first. Author-facing rules:
+> [`../templates/patterns/perf-authoring-rules.md`](../templates/patterns/perf-authoring-rules.md)
+> (R6). Deep dives are engine-internal: `.ai/moat/runtime/ffmpeg-limitations.md`,
+> `.ai/moat/runtime/render-cost-model.md` — absent in the shipped copy.
+
+## Invalid constructions (verified, with codes)
+
+    1{}          — INVALID_EMPTY (empty body)
+    1{0}         — INVALID_EMPTY (bare passthrough body)
+    1{-{}}       — INVALID_EMPTY (recursive)
+    1{1}{1}      — OVERLAY_CHAIN (two immediate overlays; nest instead)
+    1{{1}}       — TOKEN_RULE (no owner token for the inner overlay)
+    1{2(1,0)}    — PASSTHROUGH_TO_NOTHING (trailing `0` inside overlay body)
+    -{1}         — TOKEN_RULE (`-{...}` cannot be the whole-string root)

package/docs/skills/parse-apis.md

@@ -0,0 +1,79 @@
+# Choosing the right parse API (and mapping frames → sources)
+
+> **Source of truth:** [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts).
+> All four parse exports re-exported from `@m0saic/dsl`. (A fifth,
+> `parseM0StringToFullGraphWithTraversal`, was removed in the public-API prune —
+> use `parseM0StringComplete` with `opts.trace`.)
+
+## The canonical entry point: `parseM0StringComplete`
+
+`parseM0StringComplete(input, width, height, opts?)` returns (on success):
+
+- `ok: true`
+- `ir.renderFrames` — RenderFrame[] in **paint order**
+- `ir.editorFrames` — EditorFrame[] (full structural graph, always present)
+- `ir.traversal` — optional DFS event stream if `opts.trace`
+- `precision`, `resolutionDiagnostics`, `warnings`
+
+Frames are one level deep under **`ir`**, not top-level. On failure:
+`{ ok: false, error, precision, warnings }`. Other options:
+`opts.materialize: "renderOnly"` (the cheap mode `parseM0StringToLogicalFrames`
+rides on) and `opts.precisionNorm` (default 100; gates `PRECISION_EXCEEDS_NORM`
+warnings). Prefer Complete for tooling, editor logic, anything non-trivial.
+
+## The three cheaper tiers
+
+| Tier | API | Returns | Use for |
+|---|---|---|---|
+| 1 | `parseM0StringToLogicalFrames(s, w, h)` | rendered leaves only, **logical order**; each has `rect`, `logicalIndex` (array index === logicalIndex), `meta` | template tile mapping — `cell-<logicalIndex>`, labels indexing, "Nth tile" logic |
+| 2 | `parseM0StringToRenderFrames(s, w, h)` | renderable frames in **paint order**; each has `rect`, `paintOrder`, `logicalIndex` | engine paint plan / ffmpeg stacking |
+| 3 | `parseM0StringToFullGraph(s, w, h)` | EVERYTHING as EditorFrame[] — roots, groups, leaves, passthroughs, nulls, overlay subtrees | editor UIs, structural analysis |
+
+Key invariant (Tier 2): `paintOrder` is the compositing order; `logicalIndex` is
+the logical tile index. There is **no `sourceIndex` field** — build sources by
+`logicalIndex`, paint by `paintOrder`.
+
+Common mistakes the wrong tier causes: confusing paint order with logical order,
+attaching sources to the wrong index, losing overlays/group nodes in a UI.
+
+## Identity on every frame
+
+All frame views carry `meta` identity: deterministic StableKey, structuralDepth,
+overlayDepth (separate axes; overlay keys live in the `/ov{depth}c{k}` namespace and
+never shift structural keys). The full contract: [`identity.md`](identity.md).
+
+## Frames → sources → children (the template bridge)
+
+The standard pattern for turning geometry into a `MosaicDocument`:
+
+1. Parse the layout — `parseM0StringToLogicalFrames` for leaf mapping. The public
+   frames APIs already exclude null-render nodes (the parser filters
+   `nullRender` internally — you do NOT hand-filter holes/containers).
+2. For each frame: create a child renderable (often
+   `renderNestedTemplate(cellTemplateId, props, ctx)` —
+   https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/render/renderNestedTemplate.ts#L35), attach it under
+   `children[id]`, push a `sources[]` entry referencing it.
+3. Return `{ m0: <same layout>, config.sources, children }` (the document's layout
+   field is `m0` — https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/document/document.ts#L132).
+
+Rules that keep the bridge deterministic:
+
+- **Child IDs come from `frame.logicalIndex`** (e.g. `cell-${logicalIndex}`) — or
+  `frame.stableKey` when identity must survive structural edits. Never bare loop
+  order. ([`identity.md`](identity.md) owns the when-to-use-which.)
+- **Size and time from `ctx.target`, never `ctx.output`** — `ctx.output` is
+  format/codec/alpha only ([`../templates/rendering-model-contract.md`](../templates/rendering-model-contract.md) Rule 5b).
+- **Internal cell templates** (`internal: true`, id `…/cell/v1`) are the reusable
+  building block for per-tile content — wireframe-style label/debug tiles are the
+  canonical example.
+- Props schemas: use `definePropsSchema` with typed defaults. (There is no
+  `constraints.isM0saicLayout` — an older revision of this guidance invented it;
+  the real constraint set is `MosaicPropConstraints`,
+  https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/template/template.ts#L108-146`.)
+
+## Quick decision table
+
+- Engine paint plan / ffmpeg stacking → `parseM0StringToRenderFrames`
+- Template tile mapping / "Nth tile" logic → `parseM0StringToLogicalFrames`
+- Full structural tree / editor UI → `parseM0StringToFullGraph`
+- Traversal events, or anything multi-view → `parseM0StringComplete` (+ `opts.trace`)

package/docs/skills/passthrough-semantics.md

@@ -0,0 +1,136 @@
+## Passthrough & Carry Semantics
+
+`0` (passthrough) is the zero-frame donation primitive. Misused, a layout is either
+invalid (`PASSTHROUGH_TO_NOTHING`) or geometrically wrong. This doc covers donation
+mechanics, claimant/carry scoping, overlay behavior on zero-runs, the trailing rule,
+and the weighted-split encoding.
+
+> **Source of truth:** passthrough handling in [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts)
+> and validator rules in [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts).
+> Trailing-passthrough error code `PASSTHROUGH_TO_NOTHING` in [`errors/errors.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/errors/errors.ts).
+> Validity examples below runtime-verified against https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/dist on 2026-07-27.
+
+## What `0` means
+
+`0`:
+
+- Consumes a split slot
+- Produces no rendered frame
+- Donates its space forward to the next claimant
+
+It does NOT render. It only contributes geometry.
+
+> Design intent: `0` exists primarily to encode weighted / percentage splits in a
+> deterministic integer-only way.
+
+## What is a claimant?
+
+A claimant is the first non-zero node after a run of `0`s:
+
+- `1` (tile)
+- `-` (null)
+- `N(...)` / `N[...]` (group)
+
+When a claimant appears:
+
+- It absorbs ALL donated space from the run
+- It absorbs its own slot
+- Its position snaps back to the start of the run
+
+## Donation run example
+
+    3(0,0,1)
+
+- First `0` → carry = 1 slot
+- Second `0` → carry = 2 slots
+- `1` appears → absorbs carry + own slot = 3 slots
+
+Result: the tile spans the entire width of the classifier.
+
+## Carry is scoped per classifier
+
+Carry does NOT leak outside the classifier body, and resets after each claimant:
+
+    7(0{1},1,0{1},1,1,1,1)
+
+Two separate runs:
+
+- Run 1: `0{1}` starts carry → first `1` absorbs the run
+- Run 2: new `0{1}` → fresh carry → next `1` absorbs it
+
+## Overlay behavior on `0`
+
+### `0{...}` targets the merged region so far
+
+    4(0,0{2(1,1)},0,1)
+
+1. First `0` — carry = 1 slot
+2. Second `0{2(1,1)}` — carry = 2 slots; overlay canvas = merged 2-slot region
+3. Third `0` — carry = 3 slots
+4. `1` — absorbs 4 slots total
+
+Overlay size is fixed at the moment it appears. Later carry growth does NOT resize
+earlier overlays.
+
+### Multiple zero overlays grow monotonically
+
+    5(0{1},0{1},0,0,1)
+
+- First `0{1}` → overlay spans 1 slot
+- Second `0{1}` → overlay spans 2 slots
+- Remaining `0`s → carry grows
+- `1` absorbs all 5
+
+Each overlay anchors to the region size at its creation time. Zero-overlay prefix
+geometry as a deliberate technique (progressive region staging, area-ordered
+layering) has its own doc: [`zero-overlay-analysis.md`](zero-overlay-analysis.md).
+
+## Trailing passthrough rule (`PASSTHROUGH_TO_NOTHING`)
+
+A trailing `0` inside a classifier is **always** invalid — even if it carries an
+overlay. No claimant absorbs the donation; an overlay on `0` does not change that.
+
+Invalid:
+
+    2(1,0)       — bare trailing passthrough
+    2(1,0{1})    — trailing passthrough with overlay (still invalid)
+    3(1,1,0{1})  — trailing passthrough with overlay
+    0{1}         — whole-string passthrough: no sibling exists to claim
+
+Valid:
+
+    2(0,1)       — passthrough donates to claimant
+    2(0{1},1)    — passthrough with overlay, not trailing
+    3(1,0,1)     — passthrough in middle position
+
+The rule applies recursively inside nested classifiers AND overlay bodies:
+`1{2(1,0)}` rejects with `PASSTHROUGH_TO_NOTHING`.
+
+## Weighted split encoding
+
+Zero-runs are how weighted splits are encoded. To encode a 60/40 split:
+
+    [60% region][40% region]
+
+DSL representation (conceptual pattern):
+
+    100( 59 zeros, 1, 39 zeros, 1 )
+
+The zero-run before each `1` encodes how much space that tile absorbs. Mechanical
+and deterministic.
+
+### The stdlib GCD-reduces this for you
+
+Never hand-roll the 100-slot form. `weightedSplit` (and the unified `split`
+transform's `weights` option) default to `mode: "optimized"`, which divides all
+weights by their GCD before emitting slots:
+
+    weightedSplit([60, 40], "col")     →  5(0,0,1,0,1)   — not 100(...)
+    weightedSplit([50, 25, 25], "col") →  4(0,1,1,1)
+
+Verified 2026-07-27: GCD reduction in
+[https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/builders/weightedSplit.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/builders/weightedSplit.ts):119–122;
+the `split` transform routes through the same reduction in
+[`buildSplitFragment.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/transforms/primitives/split/_internal/buildSplitFragment.ts)
+(default `mode = "optimized"`). `mode: "literal"` keeps raw weights (legacy);
+`precision` rescales weights to an exact slot budget first (largest-remainder).

package/docs/skills/structural-construction.md

@@ -0,0 +1,86 @@
+# Structural construction — emitting valid canonical m0
+
+Operational construction rules. The Handbook is canonical for grammar
+([`../handbook/dsl-rules.md`](../handbook/dsl-rules.md)) — this doc is the build-time
+checklist form of the same rules; on any conflict, the handbook wins.
+
+> **Source of truth:** [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts)
+> and [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/errors/errors.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/errors/errors.ts).
+
+## 1. Canonical output only
+
+Emit `1` not `F`, `0` not `>`, no whitespace; allowed characters: `0–9 ( ) [ ] { } , -`.
+Never emit pretty aliases.
+
+## 2. Numeric containers must match exactly
+
+`N(child1, …, childK)` requires `K === N`. No compression, no implicit slots, no
+empty classifiers (`2()`, `3[]` invalid). Build children first, count them, then
+prefix with N.
+
+Valid: `2(1,1)` · `3[1,0,1]`  Invalid: `2(1)` · `3(1,1)` · `2(1,1,1)` · `3()`
+
+## 3. First token rule
+
+A valid string starts with `1`, or a NUMBER > 1 followed immediately by `(` or `[`.
+`0`, `-`, `,1`, `{1}` are invalid openers. `1(...)` / `1[...]` is
+`ILLEGAL_ONE_SPLIT` — never wrap a single child in a pseudo-container.
+
+## 4. NUMBER must be followed by a classifier
+
+`2,1` and `2{1}` are invalid; `2(1,1)` and `2[1,1]` are valid.
+
+## 5. Overlay discipline — objects vs nesting
+
+- **At most one immediate overlay object per node**: `1{1}`, `2(1,1){1}`, `0{1}`,
+  `-{1}` valid; `1{1}{1}` invalid.
+- **Layer via nesting**: `1{1{1}}` — base tile, overlay subtree, overlay on the
+  overlay.
+- **Multiple overlay layers/regions via structure inside the body**:
+  `1{2(1,-){2(-,1)}}` — the overlay body is a container that owns its own overlay;
+  holes (`-`) isolate which regions show tiles. "One overlay object per node" does
+  not limit overlay depth.
+
+## 6. No trailing passthrough
+
+A trailing `0` inside a classifier is always invalid — **even with an overlay**
+(`PASSTHROUGH_TO_NOTHING`): `2(1,0)` and `2(1,0{1})` invalid; `2(0,1)` and
+`2(0{1},1)` valid. A passthrough must donate to a claimant; an overlay does not
+exempt it.
+
+## 7. Overlay bodies — valid, but sourceless is LEGAL
+
+Bodies validate recursively as full m0 sub-expressions. A body must contain at
+least one node, but it does NOT need a leaf `1` — the legacy `ZERO_SOURCE_OVERLAY`
+rule was **relaxed 2026-06-03** and is no longer raised
+(`m0StringValidator.ts:485`). Canonical overlay rules:
+[`overlay-semantics.md`](overlay-semantics.md).
+
+Invalid: `1{}` (INVALID_EMPTY) · `1{0}` (INVALID_EMPTY) · `1{2(1,0)}` (trailing
+passthrough in body)
+Valid: `1{1}` · `1{2(1,1)}` · `1{1{1}}` · `1{2(-,1)}` · `1{-}` · `1{2(-,-)}`
+
+## 8. No-sources rule
+
+The layout as a whole needs ≥1 leaf `1` (`NO_SOURCES`) — a source inside an
+overlay counts: `2(-,-)` invalid, `2(-,-){1}` valid.
+
+## Quick reference
+
+```
+VALID:    1 · 2(1,1) · 2(1{1},1) · 3[1,0{1},1] · 1{1{1}} · 1{2(1,-){2(-,1)}} · 1{-}
+INVALID:  0 · - · 2(1) · 2(1,1,1) · 1{{1}} · 1{1}{1} · 2(1,0) · 2(1,0{1}) · 1{} · 1{0} · 2(-,-)
+```
+
+## Construction procedure
+
+1. Decide the structure shape (tree of splits + leaves).
+2. Build child arrays per split; count them; prefix the exact numeric classifier.
+3. Attach at most one overlay object per node; get extra layers via nesting or
+   split/hole structure inside the body.
+4. Canonicalize.
+5. Validate with `isValidM0String` / `validateM0String` from `@m0saic/dsl`
+   (returns `{ok: true} | {ok: false, error}` — singular `error`).
+6. On failure: discard and rebuild. Never patch a broken string by hand — fix the
+   generator ([`m0saic-string-generation.md`](m0saic-string-generation.md) §3 has
+   the per-code repair moves).