Skip to content

docs: Mermaid as the sanctioned diagram form, and the strand flow in it - #263

Merged
superposition merged 1 commit into
mainfrom
docs/mermaid-diagrams
Sep 12, 2026
Merged

superposition merged 1 commit into
mainfrom
docs/mermaid-diagrams

Conversation

@superposition

Copy link
Copy Markdown
Owner

The operator, on the hand-drawn docs/figures/the-agent-in-the-loop/strand-flow.svg:

ugly, make this into a mermaid diagram and it'll render nicely

Based on main (42e5a5f, the #260 merge); no ticket number — this PR body carries the operator's words.

What changed

  • New docs/figures/the-agent-in-the-loop/strand-flow.mmd — the strand flow as a Mermaid flowchart TD, in docs/architecture/braid.mmd's style: one subgraph, \n line breaks in the labels, no colour. 22 lines.
  • docs/figures/README.md, rule 1 amended — an entry's drawing may now be Mermaid: a <name>.mmd committed beside the figures, whose mermaid block the published entry carries (or a fenced block written into the entry, with the .mmd the source of record here). The reason is stated — GitHub renders the fenced block on the repository page and the diagram stays text, so it can be edited and reviewed like any other file — and so is the limit: Mermaid draws in the viewer's theme, not the house palette, so the hand-drawn schematic remains the form where the subject needs the box/arrow vocabulary or the house colours. The rule says what the machine check does with it: the .mmd row must carry a known kind (diagram) and the file must exist beside the README, but it is source, not an asset — not counted in the figures: OK total, not budget-checked, not rendered (the check does not run make_figures.py either); a diagram that lives only inside the published Markdown is invisible to the check, which is why the .mmd is committed here. The Layout sketch lists <name>.mmd.
  • docs/figures/the-agent-in-the-loop/README.md — the table now names strand-flow.mmd as the diagram going forward and marks the .svg row as the published raster; the Regenerating section says the .mmd is hand-edited and make_figures.py still rewrites the .svg/.png beside it.

Content trace (SVG -> .mmd)

Carried line by line from make_figures.py's strand_flow() labels: the three owners (mission broker — "opens and closes a mission by calling observe directly: it runs in this process"; evidence recorder and JEPA runtime — "another process", EvidenceSealed with the segment's digest, PromotionAccepted / PromotionRolledBack); observe(state, event) as "the sole mutator of BraidState"; the POST /braid box ("frozen BraidEvent in, the GET /braid view out; a failed dispatch is 503. Not deduplicated: the count is the events folded, so a re-delivered mission_opened counts twice."); the refused variant ("recovery's Quarantined is not a strand report: the edge refuses it with 400, and the dispatch (renaming *.partial files aside) stays in the crate's fold, over a local root — no strand, and no state moved."); BraidState's six fields and "the fold, rebuildable by replaying the stream"; the durable copies ("MCAP: quarantine_partials moves the partials aside; registry: route() writes a rollback's reason, a handle the fold does not hold; a sealed segment is its own record. The braid keeps none of them."); the GET /braid read row naming the console's Mission view, the TUI's Braid line and the operator page; the "the fold" arrow; and both arrow directions into BraidState and into the read row.

Deliberately dropped, and why:

  1. The figure's own title and subtitle ("Every strand reports into one place" / "Three owners report — one in this process, two across the edge; the braid stores nothing, and observe is the only mutator."). A Mermaid flowchart has no caption band; the same claims are carried by the subgraph label, "it runs in this process" / "another process", "the sole mutator of BraidState" and "the braid keeps none of them". The entry README's table row is the caption.
  2. The SVG's source-list footnote (crates/braid/src/lib.rs, …). The entry README's Data section names the same files and what each number comes from.
  3. The backticks around identifiers: Mermaid renders them literally, so observe, BraidEvent, quarantine_partials, route() appear bare.

Two labels are additions worth naming: the POST /braid -> observe edge and the dashed refused edge carry "the frozen BraidEvent" and "the crate's fold, over a local root" where the SVG's arrows are bare. Both phrases are the boxes' own text.

Validation

Mermaid. mermaid@11.17.2 (mermaid.esm.min.mjs bundled with esbuild 0.28.2 to an IIFE, injected into the headless Chromium the harness drives — cdn.jsdelivr.net does not resolve from this host's browser, so the check is offline): mermaid.parse OK, mermaid.render OK — 9 nodes, 8 edges, 22 <br> line breaks, 966x1616 px. A vision pass over the PNG reports every box title present, no cut-off or overlapping text, and the dashed arrow visible into the durable-copies box. Style compared against docs/architecture/braid.mmd; the only difference is that labels containing ( / ) are quoted, which braid.mmd's names do not need.

Gates (cargo run --quiet -p qualia-gates -- …, run on this branch):

BEFORE (branch at origin/main, .mmd moved aside)
  figures             figures: OK (11 entries, 55 figures, 400 KiB budget)   exit 0
  figures --self-test figures: self-test OK (17 mutations)                   exit 0

AFTER (this branch)
  figures             figures: OK (11 entries, 55 figures, 400 KiB budget)   exit 0
  figures --self-test figures: self-test OK (17 mutations)                   exit 0
  provenance          provenance: OK                                         exit 0

The figure count is unchanged (55) because .mmd is not in the checker's FIGURE_EXTS: the new row is accepted — known kind, file present — without being counted as an asset, exactly as rule 1 now says. crates/gates/src/figures.rs was not touched; there was nothing to fix.

The SVG: kept

strand-flow.svg and strand-flow.png stay committed. The published entry on superposition.github.io references the .svg by absolute URL and the publish gate resolves that URL, so removing it would 404 a live page; the file belongs to the published post until the entry itself is republished carrying the mermaid block. The entry README's table row now says both things: the .svg is the published raster, and the .mmd is the diagram going forward.

Discrepancy in the brief

The brief called the refused variant the "Quarantined/409" one; the SVG text, runners/agent/src/braid.rs:163 (StatusCode::BAD_REQUEST) and runners/agent/tests/braid.rs:208 all say 400. The .mmd says 400 and nothing in the code was changed.

The operator, on the hand-drawn strand-flow schematic: "ugly, make this into a
mermaid diagram and it'll render nicely".

docs/figures/README.md rule 1 now allows an entry's drawing to be **Mermaid** —
a `.mmd` committed beside the figures, whose `mermaid` block the published entry
carries — beside the `_house.py` schematic and the Blender render, with the
reason (GitHub renders the fenced block, and the diagram stays text so it can be
edited and reviewed) and with what the figures check does with it.

docs/figures/the-agent-in-the-loop/strand-flow.mmd carries the SVG's content:
the three owners that report, `observe` as the sole mutator, the fold into
`BraidState`, the `POST /braid` write edge (503 on a failed dispatch, not
deduplicated), the refused `Quarantined` variant (400 before the fold), the
durable copies the braid keeps none of, and the `GET /braid` read row.

strand-flow.svg/.png stay: the published entry's absolute URL still resolves to
them, and the publish gate checks that URL. The `.mmd` is the diagram going
forward.

cargo run --quiet -p qualia-gates -- figures             -> figures: OK (11 entries, 55 figures, 400 KiB budget)
cargo run --quiet -p qualia-gates -- figures --self-test -> figures: self-test OK (17 mutations)
cargo run --quiet -p qualia-gates -- provenance          -> provenance: OK
@superposition

Copy link
Copy Markdown
Owner Author

agent: Impl261MermaidDiagrams
branch: docs/mermaid-diagrams (head fb1e05c, base main 42e5a5f, PR #263)
state: complete — Mermaid sanctioned in docs/figures/README.md rule 1, strand-flow.mmd committed, gates green, PR open
next: run one correctness review, then merge (docs-only; qualia-gates figures is the machine check)
blocked_on: nothing
evidence: figures: OK (11 entries, 55 figures, 400 KiB budget); figures --self-test: OK (17 mutations); provenance: OK; mermaid 11.17.2 parse+render OK in headless Chromium (9 nodes, 8 edges, dashed refused-variant edge visible)

files

  • docs/figures/README.md (+17/-3) — rule 1: an entry's drawing may be Mermaid (a .mmd beside the figures, whose mermaid block the published entry carries; or a fenced block in the entry with the .mmd the source of record here), because GitHub renders it and it stays editable text; the hand-drawn schematic keeps the box/arrow and house-palette cases. The rule says what the check does with it: the row's Kind must be known (diagram) and the file must exist, but the .mmd is source, not an asset — not counted in figures: OK, not budget-checked, not rendered — and a diagram only inside the published Markdown is invisible to the check. The Layout sketch lists <name>.mmd.
  • docs/figures/the-agent-in-the-loop/strand-flow.mmd (+22) — flowchart TD in docs/architecture/braid.mmd's style (one subgraph, \n breaks, no colour).
  • docs/figures/the-agent-in-the-loop/README.md (+8/-2) — the .mmd row is the diagram going forward; the .svg row is the published raster; Regenerating says the .mmd is hand-edited.

commands (worktree C:/Users/ericm/wt/MermaidDiagrams)
BEFORE — branch at origin/main with the .mmd moved aside:

cargo run --quiet -p qualia-gates -- figures             -> figures: OK (11 entries, 55 figures, 400 KiB budget)   rc 0
cargo run --quiet -p qualia-gates -- figures --self-test -> figures: self-test OK (17 mutations)                   rc 0

AFTER — this head:

cargo run --quiet -p qualia-gates -- figures             -> figures: OK (11 entries, 55 figures, 400 KiB budget)   rc 0
cargo run --quiet -p qualia-gates -- figures --self-test -> figures: self-test OK (17 mutations)                   rc 0
cargo run --quiet -p qualia-gates -- provenance          -> provenance: OK                                         rc 0

crates/gates/src/figures.rs was not touched: .mmd is not in FIGURE_EXTS, so the checker accepts the new table row (known kind, file present) without counting it — the total is 55 before and after, which is what rule 1 now says.

the SVG: kept. strand-flow.svg/.png stay. The live entry (superposition.github.io/journal/the-agent-in-the-loop/, fetched) embeds https://raw.githubusercontent.com/superposition/qualia/main/docs/figures/the-agent-in-the-loop/strand-flow.svg as its <img>, so deleting it would break a published page and the publish gate's URL leg. The entry README now says the .svg is the published raster and the .mmd is the diagram going forward; wiring the fenced mermaid block into the entry is a change in the site repo, not this tree.

brief discrepancy. The brief called the refused Quarantined variant "409"; the SVG text, runners/agent/src/braid.rs:163 (StatusCode::BAD_REQUEST), runners/agent/tests/braid.rs:208 and the published entry's own alt text all say 400. The .mmd says 400; no code changed.

@superposition

Copy link
Copy Markdown
Owner Author
role: correctness
verdict: approve
notes: 3
agent: Rev263Mermaid
branch: docs/mermaid-diagrams (head fb1e05c3144d1be3591d8ec7f6727eb3ebd29925, base main 42e5a5f, PR #263)
state: correctness review complete — approve; the `.mmd` traced to the SVG generator and the Rust, the rule's enforceability measured, Mermaid re-rendered at the head
next: Main merges #263; #261 adopts the rule-1 `.mmd` form
blocked_on: nothing
evidence: at fb1e05c — `figures: OK (11 entries, 55 figures, 400 KiB budget)` exit 0; `figures --self-test OK (17 mutations)` exit 0; `provenance: OK` exit 0; mermaid@11.17.2 parse ok, render 9 nodes / 8 edges / 1 cluster / viewBox `0 0 966 1616`; 5 mutation runs against the built checker

Reviewed at fb1e05c (gh pr view 263 --json headRefOid == git ls-remote origin refs/heads/docs/mermaid-diagrams, re-checked before posting). Diff is three files: docs/figures/README.md +17/-3, docs/figures/the-agent-in-the-loop/README.md +8/-2, strand-flow.mmd +22. crates/gates/src/figures.rs is untouched, so the new row passes through the existing generic rules.

The .mmd against the SVG's generator. Every boxed claim in make_figures.py::strand_flow (lines 233–361) reappears in strand-flow.mmd verbatim: the three owners and their process split (it runs in this process vs another process … over the edge), observe(state, event) as "the sole mutator of BraidState", the POST /braid edge (frozen BraidEvent in / GET /braid view out, 503 on a failed dispatch, "Not deduplicated … a re-delivered mission_opened counts twice"), the refused Quarantined variant, the state row, the durable copies (MCAP quarantine_partials, the registry's route() reason, a sealed segment as its own record, "the braid keeps none of them") and the GET /braid read row with the BeliefClock::decision_latency_ns() carve-out. Drops: the figure's title ("Every strand reports into one place"), its subtitle framing line, and the sources footnote (crates/braid/src/lib.rs, crates/braid/src/rules.rs, runners/agent/src/{braid.rs,mission_control.rs}, the two test files, the console fixture). Strengthens: nothing factual — the two new edge labels (the frozen BraidEvent, the crate's fold, over a local root) restate words already inside the boxes. 9 nodes, 8 edges, isomorphic shapes.

The status code. strand-flow.mmd says 400, and the code agrees: runners/agent/src/braid.rs:163 returns StatusCode::BAD_REQUEST with UNSUPPORTED_EVENT (:189–192); the refusal is documented at :147–151 as happening "before the fold — nothing moved, no file touched"; the 503 is :180 SERVICE_UNAVAILABLE. Not-deduplicated is crates/braid/src/lib.rs:148–152 — "a strand that publishes the same BraidEvent::MissionOpened twice is counted twice" — with observe :155–160 adding/subtracting under saturating_*. The brief's 409 was wrong; the file, the generator and the live page's caption all say 400.

Rule 1's enforceability — measured, not inferred. Against the built qualia-gates on this worktree (restored clean after each; git status --porcelain empty at the end): a committed but undeclared .mmd → figures: OK (11 entries, 55 figures, 400 KiB budget); a .mmd row whose Kind is chart, with the entry's own chart row deleted, → figures: OK; a zero-byte .mmd → figures: OK. A declared name that does not exist → figures: FAIL - docs/figures/the-agent-in-the-loop/README.md: declared file strand-flow.mmd is missing, exit 1; an unknown Kind → figures: FAIL - docs/figures/the-agent-in-the-loop/README.md: unknown kind \widget`, exit 1. So the amendment's positive claims all hold (.mmdis not inFIGURE_EXTS, so not counted / not budget-checked / not rendered; a declared .mmdmust exist; its Kind must be known), but three *accepted* combinations show what the check cannot enforce: it cannot require the.mmdto be declared at all, it cannot require the Kind to be narrower than any known kind (so a.mmdrow declaredchartcan satisfy rule 1's chart leg with no chart), and it never opens the file. The paragraph does say the check "reads this tree, not the published entry" and "does not render Mermaid"; it should also say outright that **declaration itself, and the entry's carrying of themermaid` block, are convention rather than enforced** — otherwise a later author reads "committed here" as "checked".

The .svg/.png retention. Verified against the live page: https://superposition.github.io/journal/the-agent-in-the-loop/ embeds <img src="https://raw.githubusercontent.com/superposition/qualia/main/docs/figures/the-agent-in-the-loop/strand-flow.svg"> — the raw URL, exactly as the PR says. Deleting the .svg would break the published image and the publish gate's URL leg, so keeping it is required, and the entry README's row ("kept because the published entry's absolute URL still resolves to it") is honest. The same page still shows the hand-drawn SVG, not a Mermaid block; the .mmd row is labelled "the flow diagram going forward", so the Mermaid arm of rule 1 is prospective for this entry — true as written, not overclaimed.

The Mermaid itself. Re-rendered at the head in the harness's headless Chromium with mermaid@11.17.2 (jsdelivr): mermaid.parse ok; mermaid.render → 9 nodes, 8 edges, 1 cluster, viewBox="0 0 966 1616", the dotted refused-variant edge present, and no literal \n in the text (the quoted \n became line breaks). That matches the author's independent numbers (9 nodes, 8 edges, 966×1616) exactly.

Notes (non-blocking).

  1. Rule-1 wording vs the check. As measured above, the amendment should state that the check cannot require the .mmd to be declared nor the published entry to carry the block; the current "A diagram that lives only inside the published Markdown is invisible to the check, which is why the .mmd is committed here" invites the reading that committing alone makes it checked (it does not — crates/gates/src/figures.rs enumerates assets by extension and table rows by the README, and .mmd is in neither).
  2. The state row's six fields. BraidState (the agent's own copy) lists schema_version among the six, but schema_version is on the agent's wire view BraidView (runners/agent/src/braid.rs:52–63, field at :57); the crate's BraidState has the other five (crates/braid/src/lib.rs:44–50). Inherited verbatim from the SVG (make_figures.py:321–327) and restated in the entry README ("the folded BraidState and its six fields"), so not introduced here — but if the .mmd becomes the diagram of record, say "the agent's view: the five state fields plus the schema tag".
  3. The doc's own example line is stale. docs/figures/README.md:12 still prints figures: OK (10 entries, 49 figures, 400 KiB budget); measured at the head is 11 entries, 55 figures. Pre-existing (the PR adds no figure assets), but this PR is the one teaching the check's output, so refresh it.

provenance: OK was run as the same gate the clean-room role uses; that role and contract are optional per the landing-wave rules and I did not run them — this change has no interface.

@superposition
superposition merged commit 6d3f867 into main Sep 12, 2026
superposition added a commit that referenced this pull request Sep 12, 2026
Reframes the EPIC-06 entry (docs/figures/the-fly-brain-on-the-robot/README.md)
so its subject is the robot and the fly driving it:

- The robot: the WaveShare UGV the leash owns end to end (drive on
  /dev/ttyTHS1, LD06 lidar, MJPEG camera, IMU) and the safety-shaped motor
  path (DriveCommand::WheelSpeeds, NavGoal -> wheel speeds, link claimed at
  zero speed, ACTION_SAFETY_DISARMED / ACTION_SAFETY_TRANSPORT_ERROR).
- The fly: the released male-CNS connectome as a spiking controller producing
  left/right/hold from the robot's own camera; crates/fly-circuit named as the
  invented-dynamics rate model it is, observe-only and off the motor path.
- The learning: transitions -> dataset -> JEPA train_batch, and D-027's floor
  (1,499 valid of 50k/12/3/3) as the honest frontier.
- Figures: drive-commands.svg replaces step-rates.svg and is re-counted from
  the committed trace CSVs; dataset-gate.svg kept; the loop diagram is
  driving-loop.mmd, the Mermaid form rule 1 sanctions (#263). No logo or mark.

Refs #6
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant