# Research Sub-Report: Cluster 8 — Self-Describing Data + Tag Dispatch (Metadesk)

**Sub-agent dispatch:** Tier 3 Worker (2026-06-12). Read-only research task.
**Sources read:**
- https://web.archive.org/web/20231126220529/https://dion.systems/metadesk (homepage)
- https://web.archive.org/web/20211205200037/https://dion.systems/metadesk_reference (reference page)
- https://github.com/Ed94/metadesk/blob/master/docs/metadesk_reference.mdesk (canonical .mdesk reference)

---

## Entry: Metadesk (Ryan Fleury + Allen Webster, Dion Systems, 2020–2021)

**What it is.** Metadesk is a generic plaintext data-description language paired with a C parser library. The language defines a uniform AST shape — every node has a string, an optional list of children, and an optional list of tags (decorations prefixed with `@`) — and the host application supplies all semantic meaning. The .mdesk reference file itself is the canonical example: it uses Metadesk syntax to describe the Metadesk C library, and Dion Systems' own website was generated from it. The two authors are Ryan Fleury (Handmade Hero / Handmade Network) and Allen Webster (Dion Systems); the project page is at `https://github.com/Ed94/metadesk` (the user's maintained mirror of the original Dion Systems repo, now offline).

**What we take from it.** The tag-as-dispatch-key pattern is the philosophical anchor for the DSL's "verb is a host-defined operation" stance. The `MD_Node` uniform-AST design (every node has the same shape: string, children, tags) maps to the DSL's "every pipeline stage is the same shape" (input → verb → output) design. The "host supplies all semantics" stance is the DSL's own stance toward AI-agent tool calls: the DSL is the format; the host (MCP client, bridge script) supplies the execution semantics. Multiple-delimiter tolerance (`{ }` / `( )` / `[ ]` / mixed) maps to the Tier 4 `fuzzy` verb's parse-tolerance property. The .mdesk self-documentation pattern is a target property for the DSL's spec format.

### 5 Distinctive Design Properties (per sub-agent)

1. **Uniform "lego-brick" AST.** Every `MD_Node` is the same C struct: `(next, prev, parent, first_child, last_child, first_tag, last_tag, kind, flags, string, raw_string, prev_comment, next_comment, offset, ref_target)`. From the .mdesk: *"The `MD_Node` is the main 'lego-brick' for modeling the result of a Metadesk parse."* No enum of node kinds — there is only the tree + tags, and the user defines which tags are meaningful. The library is a generic tree; the host language assigns all types, all enums, all operations. (Source: `metadesk_reference.mdesk` §`MD_Node` struct docstring.)

2. **Tags as dispatch keys.** `@struct`, `@enum`, `@func`, `@macro`, `@doc`, `@code`, `@see`, `@prefix`, `@base_type`, `@flags`, `@opaque`, `@send`, `@paste`, `@title`, `@def` are all tags, and the host code dispatches on `MD_NodeHasTag(node, "...")` or by iterating `first_tag`. There is no enum of node kinds in the language — there is only the tag list, and the user defines which tags are meaningful. Structurally identical to the nagent tag protocol (Cluster 3) and OpenAI/Anthropic tool-use schemas (Cluster 4). (Source: `metadesk_reference.mdesk` §`@tags` description; the example interpreter `md_dev.c` in the repo.)

3. **Multiple interchangeable child delimiters + optional separators.** `Foo: { A, B, C }`, `Foo: { A; B; C; }`, `Foo: ( A B C )`, `Foo: [ A B C ]`, `Foo: [ A B C )`, even `Foo: A B C` (implicit close) — all legal. The host reads the children identically regardless of which delimiter was used. This is a deliberate parse-tolerance design: the same language can be configured to look like JSON, like S-expressions, like C struct initializers, or like YAML, just by choosing the delimiter style at the file level. (Source: `metadesk_reference.mdesk` §`Delimiters` and §`Operators`.)

4. **Comment and source-location preservation per node.** `prev_comment`, `next_comment`, `offset` (byte position in source), and a derived `MD_CodeLoc {filename, line, column}` are stored on every node. Round-tripping (parse → modify → emit) preserves comments and locations so the language can be used for source-code tooling that doesn't lose fidelity. This is a property most parsers lack (e.g., GCC's AST, Clang's AST) and it is what makes Metadesk usable for code generators and refactoring tools. (Source: `metadesk_reference.mdesk` §`MD_Node` struct docstring + §`Comments`.)

5. **First-class C interop with copy-paste distribution and string-slicing strings.** The library ships as `md.h` + `md.c` to be `#include`d directly into the host (no link-time dependency), all strings are non-null-terminated `MD_String8 { str, size }` slices, and parsing allocates from an `MD_Arena` (also overridable). The "full meaning is not determined by Metadesk" stance (per the homepage) means the language is the *narrow waist* between arbitrary host semantics and a uniform parser front-end. (Source: dion.systems/metadesk homepage, "Library" section; `md.h` API documentation.)

### Anchor Quote

*"Metadesk is an ergonomic parser library for a simple—yet versatile—plaintext language. The language lets you create simple structures and define their meaning with your own code. The library provides the parser, and helpers for introspection and code generation."* — dion.systems/metadesk homepage (web.archive.org capture 20231126220529), "Language" + "Library" intro paragraphs.

*"the full meaning of your files is not determined by Metadesk"* — same source, "Language" section, "So what's going on here?" paragraph. This is the philosophical anchor for the "host-defined semantics" design.

*"`MD_Node` is the main 'lego-brick' for modeling the result of a Metadesk parse."* — `metadesk_reference.mdesk`, `MD_Node` struct docstring. This is the design-property #1 quote (uniform AST shape).

---

## Synthesis for the DSL

This section maps Metadesk's design properties to the DSL's verb tiers, enabling the Tier 1 Orchestrator to write §4 (Tier 3 and Tier 4 verb justifications) and §6 (AI-agent properties) of the report.

### Tier 3 (Shell) Verb Justification via Metadesk

| DSL Verb | Metadesk Analogue | Mapping | Source |
|----------|-------------------|---------|--------|
| `read` | `MD_Node` tree traversal | The DSL's `read` operation navigates the host's data tree (filesystem) using the same model: a uniform structure where each node has a name + children + tags. `read(path)` is `tree.root.first_child with matching string`. | `metadesk_reference.mdesk` §`Tree traversal` |
| `edit` | `MD_Node` modification + round-trip | The DSL's `edit(path, span, replacement)` preserves comments and source-locations by analogy to Metadesk's `prev_comment` / `next_comment` / `offset` fields. The DSL inherits round-trippability as a property. | `metadesk_reference.mdesk` §`Comments` |
| `discover` | `MD_NodeHasTag` | The DSL's `discover(scope)` returns the set of tags within a scope — directly analogous to `MD_NodeHasTag(node, "...")`. Tags are the discovery mechanism. | `metadesk_reference.mdesk` §`Tags` |
| `exec` | `md_dev.c` host interpreter | The DSL's `exec` is the escape hatch to arbitrary host code, exactly the role `md_dev.c` plays for Metadesk: a reference host that demonstrates the API. | `github.com/Ed94/metadesk/blob/master/src/md_dev/md_dev.c` |

### Tier 4 (AI-Fuzzing Tolerance) Verb Justification via Metadesk

| DSL Verb | Metadesk Analogue | Mapping | Source |
|----------|-------------------|---------|--------|
| `fuzzy` | Multiple-delimiter tolerance | The DSL's `fuzzy` region accepts near-matches in verb names + parse-tolerance in syntax. Metadesk's `{ }` / `( )` / `[ ]` / mixed delimiter acceptance is the same property at the syntax level. | `metadesk_reference.mdesk` §`Delimiters` |
| `audit` | `MD_NodeHasTag` enumeration | The DSL's `audit` enumerates all tags in a tree — the "self-describing" property. Metadesk's tag enumeration via `first_tag` iteration is the precedent. | `metadesk_reference.mdesk` §`Tags` |

### File:line References

| Source | Section | Note |
|--------|---------|------|
| `https://web.archive.org/web/20231126220529/https://dion.systems/metadesk` | "Language" + "Library" intro paragraphs | Anchor quote for "ergonomic parser library" |
| `https://web.archive.org/web/20231126220529/https://dion.systems/metadesk` | "So what's going on here?" | Anchor quote for "full meaning is not determined by Metadesk" |
| `https://raw.githubusercontent.com/Ed94/metadesk/master/docs/metadesk_reference.mdesk` | `MD_Node` struct docstring | Anchor quote for "lego-brick" AST |
| `https://raw.githubusercontent.com/Ed94/metadesk/master/docs/metadesk_reference.mdesk` | §`Delimiters` | Multiple-delimiter tolerance |
| `https://raw.githubusercontent.com/Ed94/metadesk/master/docs/metadesk_reference.mdesk` | §`Tags` | Tag dispatch keys |
| `https://raw.githubusercontent.com/Ed94/metadesk/master/docs/metadesk_reference.mdesk` | §`Comments` | Comment + location preservation |
| `https://github.com/Ed94/metadesk/blob/master/src/md_dev/md_dev.c` | Full file | Reference host interpreter |

---

**Sub-report complete.** This is the evidence base for §2 Cluster 8 in `report_v1.2.md`.
