figdown 0.3.2 → 0.4.1

package/integrations/mcp-server/README.md

@@ -87,7 +87,7 @@ particular there is no layout-lint tool and no "render to PNG".
 |---|---|
 | `figdown_build` | Turn one `.fd` into the deterministic, self-carrying SVG. The artifact embeds its own source, that source's SHA-256 and the engine version (core §7), so it round-trips back to text. |
 | `figdown_check` | Parse one document *or walk a whole tree*, render nothing, write nothing. This is the write → validate → fix loop and the corpus sweep; it exists separately from `build` so that iterating on a broken file costs no render and puts no SVG in the agent's context. |
-| `figdown_read` | The semantic model — participants, relationships and direction, containment, and the **stated meaning** of every class — shipped with the reading contract. Accepts a `.svg` too, recovering the source from its metadata and reporting the artifact stale if the `.fd` has moved on. |
+| `figdown_read` | The semantic model — participants, relationships and direction, containment, and the **stated meaning** of every class — shipped with the reading contract. Accepts a `.svg` too, recovering the source from its metadata and reporting the artifact stale if the `.fd` has moved on. A `sequence` section reports its own collections (lifelines, messages, states, fragments, operands) and gets one extra contract line, because in that genre a message is **not** an edge and array order **is** the meaning. |
 | `figdown_reference` | The per-genre reference, so an agent knows what a genre may and may not say. The grammar is **closed** and the parser **never warns about portability**, so this is the only place the frozen / EXPERIMENTAL split is visible. |
 
 ### `figdown_build`
@@ -118,8 +118,11 @@ than guessing at the picture.
 ### `figdown_reference`
 
 `name` — a genre (`block`, `bitfield`, `table`, `topology`, `flowchart`,
-`statechart`, `timing`), a task (`reading`, `transcribe`), or `skill`. Omit it
-for the index. `experimental: true` adds the genre's EXPERIMENTAL files, which sit
+`statechart`, `timing`, `sequence`), a task (`reading`, `transcribe`), or
+`skill`. Omit it for the index. The list is not restated here or in the tool's
+schema as the authority — it is **parsed out of `SKILL.md`'s router at call
+time**, so a genre that lands without a router row is invisible to this tool
+and `gate:mcp` fails rather than an agent receiving nothing. `experimental: true` adds the genre's EXPERIMENTAL files, which sit
 outside the v0.1 conformance surface and its compatibility promise.
 
 ## A parse error is a result, not an exception
@@ -168,7 +171,10 @@ node integrations/mcp-server/test.js     # npm run gate:mcp
 It speaks real JSON-RPC to a spawned subprocess (framing is the half that was
 hand-rolled, and an in-process test cannot catch a framing bug), then exercises
 every tool against real figures from `examples/` — a multi-section topology, an
-experimental `figdown 0.2 statechart`, a published artifact read back through
+experimental `figdown 0.2 statechart`, a `figdown 0.4 sequence` ladder whose
+model has no nodes and no edges at all, a published artifact read back through
 its own metadata, and a deliberately broken document. Two of its assertions are
 drift guards rather than feature tests: every genre in SKILL.md's router must
-still resolve to files that exist, and this server must contain no engine copy.
+still resolve to files that exist — `sequence` by name, since a genre that
+lands without a router row is the failure this guard exists for — and this
+server must contain no engine copy.

package/integrations/mcp-server/server.js

@@ -307,7 +307,12 @@ function toolRead(args) {
   const shape = docs.map((d, i) =>
     '  section ' + (i + 1) + ': figdown ' + d.version + ' ' + d.genre
     + (d.title ? '  title ' + JSON.stringify(d.title) : '')
-    + '  [' + ['nodes', 'edges', 'groups', 'classes', 'blocks', 'boundaries']
+    // The collection list is per-genre, not scene-only: a `sequence` document
+    // carries no nodes and no edges (a message is NOT an edge — SEQUENCE-ORDER-MODEL), so a
+    // scene-only list reported a ladder of seventeen messages as "[3 classes]"
+    // and the shape line said nothing about the figure at all.
+    + '  [' + ['nodes', 'edges', 'groups', 'classes', 'blocks', 'boundaries',
+      'lifelines', 'messages', 'states', 'fragments', 'operands']
       .filter(k => Array.isArray(d[k]) && d[k].length)
       .map(k => d[k].length + ' ' + k).join(', ') + ']').join('\n');
 
@@ -327,7 +332,18 @@ function toolRead(args) {
     '    parsable — infer no participant, edge or category from them.',
     '  * Array order is not ranking or priority (§12.7).',
     '  * Everything below `layout` is geometry with no meaning. Skip it.',
-  ].join('\n');
+    // One conditional line. `sequence` is the single genre where two of the
+    // rules above read as false: it has no nodes and no edges, and its array
+    // order IS the figure's meaning. Adding it unconditionally would charge
+    // every other reader for a genre they are not holding.
+    docs.some(d => d.genre === 'sequence')
+      ? '  * THIS DOCUMENT HAS A `sequence` SECTION, where two of the rules above invert:\n'
+        + '    participants are `lifelines`, a `message` is an occurrence in time and NOT an\n'
+        + '    edge (which is why `edges` is empty), and `messages` ∪ `states` array order IS\n'
+        + '    the order of the exchange. A `state` names the condition its lifeline is in\n'
+        + '    from that point on. Nothing in the layout zone draws here.'
+      : null,
+  ].filter(Boolean).join('\n');
 
   const head = [
     'ok: true  ' + docs.length + ' section(s) in ' + s.label,
@@ -483,7 +499,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        name: { type: 'string', description: 'A genre (block, bitfield, table, topology, flowchart, statechart, timing), a task (reading, transcribe), or "skill". Omit for the index.' },
+        name: { type: 'string', description: 'A genre (block, bitfield, table, topology, flowchart, statechart, timing, sequence), a task (reading, transcribe), or "skill". Omit for the index.' },
         experimental: { type: 'boolean', description: 'Include the genre\'s EXPERIMENTAL (experimental) files — outside the v0.1 conformance surface and its compatibility promise.' },
       },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figdown",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "A missing edge still looks fine. Text doesn't. A closed, deterministic figure language for Markdown whose source states the meaning, so the next reader can check the figure instead of only looking at it.",
   "license": "MIT",
   "author": "FigDown <hello@figdown.org>",
@@ -45,6 +45,7 @@
     "gate:registry": "node tools/registry-check.js --strict",
     "gate:capability": "node tools/capability-coverage.js --strict",
     "gate:archive": "node tools/archive-check.js --strict",
+    "gate:standards": "node tools/standards-check.js --strict",
     "gate:plugin": "node tools/plugin-check.js --strict",
     "gate:mcp": "node integrations/mcp-server/test.js",
     "gates:list": "node -e \"const s=require(process.cwd()+'/package.json').scripts||{};const g=Object.keys(s).filter(k=>k.startsWith('gate:'));if(!g.length){console.error('gates:list — no gate:* scripts found');process.exit(2);}if(process.env.GATES_JSON)console.log(JSON.stringify(g));else g.forEach(k=>console.log(k+'  ->  '+s[k]));\"",

package/skill/figdown/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: figdown
-description: Draw a figure a human can read and an agent can read too — FigDown .fd text that states the meaning, with a deterministic SVG embedded in Markdown. Use when asked to create, edit, fix, or read diagrams/figures in docs — block and architecture diagrams, topologies, flowcharts, bit-level layouts (packet headers, hardware registers), tables, timing waveforms — or when a .md contains an SVG with a "source: *.fd" footer.
+description: Draw a figure a human can read and an agent can read too — FigDown .fd text that states the meaning, with a deterministic SVG embedded in Markdown. Use when asked to create, edit, fix, or read diagrams/figures in docs — block and architecture diagrams, topologies, flowcharts, state machines, message-sequence exchanges between parties, bit-level layouts (packet headers, hardware registers), tables, timing waveforms — or when a .md contains an SVG with a "source: *.fd" footer.
 ---
 
 # FigDown — figures as text, one source, two readers
@@ -67,7 +67,11 @@ everything it produces is a hypothesis until checked.
 is not a graph: it is a `table`. Conditions with one outcome per combination is
 a `table`, not a `flowchart` — drawn as a chart it buys crossing edges and
 nothing else. Two mirrored mechanisms are two figures. A run in which most of a
-page's figures become tables is a correct run.
+page's figures become tables is a correct run. **The SHAPES in the source
+drawing are the tempting signal and they carry nothing** — the original author
+picked them by habit, by stencil and by tool default, and no two drawings agree;
+what decides the genre is the ROLES and the QUESTIONS in it, which is what the
+extraction gives you and the picture does not.
 
 **3 — Separate what the source states from what you concluded.** Write the
 stated thing; for the rest, leave a `#` comment at the point of doubt and list
@@ -113,27 +117,51 @@ so you know which file you need before you need it.
 | `flowchart` | `reference/experimental/flowchart.md`, `reference/layout.md` | `reference/experimental/chart.md` |
 | `statechart` | `reference/experimental/statechart.md`, `reference/layout.md` | `reference/experimental/chart.md` |
 | `timing` | — | `reference/experimental/timing.md` |
+| `sequence` — message exchanges over time | — | `reference/experimental/sequence.md` |
+
+**`sequence` draws a ladder**, and you place nothing in it: participants are
+columns and time runs down the page, both in the order the source declares
+them, so no key in that genre moves a coordinate — not even a layout-zone one,
+which parses and changes nothing there. Its file is the whole of its
+vocabulary, and it is the one genre where the layout file buys you nothing.
+Three constructs an author arriving from another genre reaches for were
+argued and REFUSED there — a time-gap line, a band over participants, and a
+per-message "sent but never delivered" flag; each is a line error that names
+its ground and the spelling to write instead, so write the source and read
+the message rather than guessing. Its file says how.
 
 Two more files answer a **task** rather than a genre:
 
 - **Reading a `.fd` someone else wrote, to summarise or answer from it** →
   `reference/reading.md`. It is the contract for what you may conclude and
   what you must not infer, and it is all you need: a reader can skip every
-  genre file above. **One correction applies to it.** `reference/reading.md` is
-  a byte-frozen copy of a released reading contract, and one sentence in it is
-  wrong: where it says *"Ignore the layout zone. Everything from the `layout`
-  keyword down is …"*, do not read it as a rule about **position**. Ignore the
-  layout **namespace** — its one member is `pin` — **wherever a member
-  appears**, because a `pin` may legally sit *before* the `layout` line, and
-  about half of them do. Membership decides, not position. The frozen file is
-  left as-is on purpose; apply this rule instead, the same one stated above
-  under "layout and pin".
+  genre file above. **The correction that used to be printed here is now in the
+  file itself**, so read `reference/reading.md` as it stands. If you ever meet
+  an OLDER copy of that contract — one that says *"Ignore the layout zone.
+  Everything from the `layout` keyword down is …"* — do not read that as a rule
+  about **position**. Ignore the layout **namespace** — its one member is `pin`
+  — **wherever a member appears**, because a `pin` may legally sit *before* the
+  `layout` line, and about half of them do. Membership decides, not position.
+  It is the same rule stated above under "layout and pin".
 - **Transcribing an existing figure** — a drawing, a screenshot, another
   format → `reference/transcribe.md`.
 
 Pick the genre by what the figure IS, not by its subject: the left-hand
-column above says what each is for. Prefer the first three — they are the
-portable ones.
+column above says what each is for.
+
+**Where portability and that answer disagree, the ANSWER decides.** `block`,
+`bitfield` and `table` are the portable three — inside the v0.1 conformance
+surface and its compatibility promise — and taking one of them *against* the
+answer is a trade you STATE, never a default. State it in a `#` comment that
+names the genre you did not write and what the reader must not conclude from
+the one you did. Two different prices hide under the word "portable" and they
+are charged by different rows: `topology` and `flowchart` are dispatchable at
+`figdown 0.1`, so choosing them moves no version and only carries the EXPERIMENTAL
+withdrawal risk; `statechart` and `sequence` move the declared version as well.
+"It must render on any released version" is therefore not an argument for
+leaving the first two. An approximation you do not state is indistinguishable
+from a judgement about what the figure is, so the reader inherits the wrong
+one.
 
 **Load the genre file BEFORE you write line 2, not only when something
 fails.** A scene genre may spell the thing and the line with **its own
@@ -175,11 +203,14 @@ figdown 0.1 block           # REQUIRED first significant line; comments and
                             # A later `figdown 0.1 <genre>` starts a new
                             # section with its own genre; one file still
                             # renders to one SVG.
-                            # The VERSION is `0.1` or `0.2`. Write the LOWEST
-                            # one that carries what the figure needs — `0.2`
-                            # only for `statechart`, which does not exist at
-                            # `0.1`. Sections may differ; each declares its
-                            # own.
+                            # The VERSION is `0.1`, `0.2` or `0.4`. Write the
+                            # LOWEST one that carries what the figure needs.
+                            # `0.1` carries every other genre. `0.2` is the
+                            # floor for `statechart` and `0.4` the floor for
+                            # `sequence`: neither exists at `0.1`, and a
+                            # version below a genre's floor is a line error
+                            # (`figdown 0.3 sequence` does not parse).
+                            # Sections may differ; each declares its own.
 title "Some Title"          # optional; the quotes are REQUIRED
 # comments start with '#'; inside quotes the only escapes are \n \" \\
 class hot "Congested path" stroke=#dc2626   # meaning + style, declared once

package/skill/figdown/build-svg.js

@@ -38,9 +38,23 @@ function buildOne(engine, fdPath) {
     for (const e of errs) console.error('  ' + e);
     return false;
   }
+  // GEOMETRY-TIME DIAGNOSTICS gate the artifact exactly as parse errors do.
+  // `parse` cannot see a coordinate, so a figure whose SOURCE is impeccable can
+  // still draw a false statement — a `group` band is the bounding box of its
+  // members, and a non-member sitting inside it tells the reader it is one.
+  // The engine reports those from `render`; writing the `.svg` anyway would
+  // publish the picture the engine has just said is wrong, which is the whole
+  // failure this gate exists to stop.
+  const rendered = docs.map(d => engine.render(d, RENDER_OPTS));
+  const gerrs = rendered.reduce((a, r) => a.concat(r.errs || []), []);
+  if (gerrs.length) {
+    console.error(fdPath + ':');
+    for (const e of gerrs) console.error('  ' + e);
+    return false;
+  }
   const svg = docs.length > 1
-    ? engine.stackSectionSvgs(docs.map(d => engine.render(d, RENDER_OPTS)))
-    : engine.render(docs[0], RENDER_OPTS).svg;
+    ? engine.stackSectionSvgs(rendered)
+    : rendered[0].svg;
   const hash = crypto.createHash('sha256').update(src, 'utf8').digest('hex');
   // The artifact records three things (spec core §7): the SHA-256 OF THE
   // SOURCE, the ENGINE VERSION that rendered it, and any non-default render