Repository navigation
docs: Mermaid as the sanctioned diagram form, and the strand flow in it - #263
Conversation
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
|
agent: Impl261MermaidDiagrams files
commands (worktree AFTER — this head:
the SVG: kept. brief discrepancy. The brief called the refused |
Reviewed at The The status code. Rule 1's enforceability — measured, not inferred. Against the built The The Mermaid itself. Re-rendered at the head in the harness's headless Chromium with Notes (non-blocking).
|
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
The operator, on the hand-drawn
docs/figures/the-agent-in-the-loop/strand-flow.svg:Based on
main(42e5a5f, the #260 merge); no ticket number — this PR body carries the operator's words.What changed
docs/figures/the-agent-in-the-loop/strand-flow.mmd— the strand flow as a Mermaidflowchart TD, indocs/architecture/braid.mmd's style: one subgraph,\nline 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>.mmdcommitted beside the figures, whosemermaidblock the published entry carries (or a fenced block written into the entry, with the.mmdthe 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.mmdrow must carry a known kind (diagram) and the file must exist beside the README, but it is source, not an asset — not counted in thefigures: OKtotal, not budget-checked, not rendered (the check does not runmake_figures.pyeither); a diagram that lives only inside the published Markdown is invisible to the check, which is why the.mmdis committed here. The Layout sketch lists<name>.mmd.docs/figures/the-agent-in-the-loop/README.md— the table now namesstrand-flow.mmdas the diagram going forward and marks the.svgrow as the published raster; the Regenerating section says the.mmdis hand-edited andmake_figures.pystill rewrites the.svg/.pngbeside it.Content trace (SVG ->
.mmd)Carried line by line from
make_figures.py'sstrand_flow()labels: the three owners (mission broker — "opens and closes a mission by callingobservedirectly: it runs in this process"; evidence recorder and JEPA runtime — "another process",EvidenceSealedwith the segment's digest,PromotionAccepted/PromotionRolledBack);observe(state, event)as "the sole mutator ofBraidState"; thePOST /braidbox ("frozenBraidEventin, theGET /braidview out; a failed dispatch is 503. Not deduplicated: the count is the events folded, so a re-deliveredmission_openedcounts twice."); the refused variant ("recovery'sQuarantinedis not a strand report: the edge refuses it with 400, and the dispatch (renaming*.partialfiles 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_partialsmoves 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."); theGET /braidread row naming the console's Mission view, the TUI's Braid line and the operator page; the "the fold" arrow; and both arrow directions intoBraidStateand into the read row.Deliberately dropped, and why:
observeis 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 ofBraidState" and "the braid keeps none of them". The entry README's table row is the caption.crates/braid/src/lib.rs, …). The entry README's Data section names the same files and what each number comes from.observe,BraidEvent,quarantine_partials,route()appear bare.Two labels are additions worth naming: the
POST /braid->observeedge 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.mjsbundled 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.parseOK,mermaid.renderOK — 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 againstdocs/architecture/braid.mmd; the only difference is that labels containing(/)are quoted, whichbraid.mmd's names do not need.Gates (
cargo run --quiet -p qualia-gates -- …, run on this branch):The figure count is unchanged (55) because
.mmdis not in the checker'sFIGURE_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.rswas not touched; there was nothing to fix.The SVG: kept
strand-flow.svgandstrand-flow.pngstay committed. The published entry onsuperposition.github.ioreferences the.svgby 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 themermaidblock. The entry README's table row now says both things: the.svgis the published raster, and the.mmdis 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) andrunners/agent/tests/braid.rs:208all say 400. The.mmdsays 400 and nothing in the code was changed.