From fb1e05c3144d1be3591d8ec7f6727eb3ebd29925 Mon Sep 17 00:00:00 2001 From: superposition Date: Sat, 12 Sep 2026 09:50:18 -0400 Subject: [PATCH] docs: sanction Mermaid as a figure form, and draw the strand flow in it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/figures/README.md | 20 ++++++++++++++--- docs/figures/the-agent-in-the-loop/README.md | 10 +++++++-- .../the-agent-in-the-loop/strand-flow.mmd | 22 +++++++++++++++++++ 3 files changed, 47 insertions(+), 5 deletions(-) create mode 100644 docs/figures/the-agent-in-the-loop/strand-flow.mmd diff --git a/docs/figures/README.md b/docs/figures/README.md index 05d78e8..68e6fbd 100644 --- a/docs/figures/README.md +++ b/docs/figures/README.md @@ -20,6 +20,7 @@ docs/figures/ make_figures.py the generator: `python make_figures.py` rewrites the figures below README.md the table, the data, and how to regenerate (the shape below) .svg .png one figure: vector source, and the raster beside it + .mmd a Mermaid diagram (rule 1); source, not a counted asset .json the recording the figure draws (optional) .glb a Blender render (optional; steps 42–43) ``` @@ -31,9 +32,22 @@ ticket rather than to a published entry takes a short slug for that set — `fly ## The rules 1. **One chart and one drawing.** Every entry ships with at least one **chart** (matplotlib) and at - least one **diagram or render**: a schematic drawn in `_house.py`'s box/arrow vocabulary, or a - Blender render from steps 42–43. A human learner needs the picture as well as the number, and the - teaching editor's checklist refuses an entry with only one of the two. + least one **diagram or render**: a schematic drawn in `_house.py`'s box/arrow vocabulary, a + Blender render from steps 42–43, or **Mermaid** — a `.mmd` committed beside the figures, + whose `mermaid` block the published entry carries (or a fenced block written straight into the + entry, with the `.mmd` as the source of record here). Mermaid is sanctioned because 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; it draws in the viewer's theme rather than the house palette, so the + hand-drawn schematic stays the form where the subject needs the box/arrow vocabulary or the house + colours. A human learner needs the picture as well as the number, and the teaching editor's + checklist refuses an entry with only one of the two. + + The machine check reads this tree, not the published entry. A `.mmd` named in the entry's figure + table is held to the table's own rules — the row's Kind must be one of the known kinds + (`diagram`), and the file must exist beside the README — but it is not an asset: it is not + counted in the `figures: OK` total, it is not budget-checked, and the check does not render + Mermaid, exactly as it does not run `make_figures.py`. A diagram that lives only inside the + published Markdown is invisible to the check, which is why the `.mmd` is committed here. 2. **The mesh band only where the subject is a numeric field.** The render band is an extra, not a default: it is added to an entry whose subject is a numeric field (steps 42–43 own the asset), and an entry that is a story with a chart and a schematic does not get one. diff --git a/docs/figures/the-agent-in-the-loop/README.md b/docs/figures/the-agent-in-the-loop/README.md index 526bd10..9d412d7 100644 --- a/docs/figures/the-agent-in-the-loop/README.md +++ b/docs/figures/the-agent-in-the-loop/README.md @@ -1,12 +1,14 @@ # Figures — the agent in the loop Two figures for the journal entry -[`the-agent-in-the-loop`](https://superposition.github.io/journal/the-agent-in-the-loop/). +[`the-agent-in-the-loop`](https://superposition.github.io/journal/the-agent-in-the-loop/), plus the +Mermaid source of the flow diagram. | File | Kind | What it encodes | | --- | --- | --- | | `mission-lifecycle.svg` (+ `.png`) | chart, two panels | Left: `open_missions` through the fold — the crate's test folding open m1, open m2, close m1, close m2 and a close for a mission it never saw (1, 2, 1, 0, 0), and the agent's write edge folding one open and one close (1, 0). Right: the belief pace gate — the window (1×), the stale window (8×), the hold region and the two stale publications `runners/map`'s tests assert (a 10 s-old belief tick under the 250 ms default; a 300 ms-old tick released at the 200 × 8 = 1,600 ms window). | -| `strand-flow.svg` (+ `.png`) | diagram | The three owners that report — the mission broker calling `observe` directly (it runs in this process), and the two strands that live in other processes, the evidence recorder's `EvidenceSealed` and the JEPA runtime's `PromotionAccepted` / `PromotionRolledBack`, crossing the one write edge (`POST /braid` carrying the frozen `BraidEvent`, 503 on a failed dispatch, no de-duplication) — then `observe` as the sole mutator, the folded `BraidState` and its six fields, the durable copies the braid does not keep (MCAP quarantine, the registry's rollback record), recovery's `Quarantined` shown as the variant the edge refuses with 400, and the `GET /braid` read the console, TUI and operator page poll. | +| `strand-flow.mmd` | diagram | The strand flow going forward, in Mermaid: the three owners that report — the mission broker calling `observe` directly (it runs in this process), and the two strands that live in other processes, the evidence recorder's `EvidenceSealed` and the JEPA runtime's `PromotionAccepted` / `PromotionRolledBack`, crossing the one write edge (`POST /braid` carrying the frozen `BraidEvent`, 503 on a failed dispatch, no de-duplication) — then `observe` as the sole mutator, the folded `BraidState` and its six fields, the durable copies the braid does not keep (MCAP `quarantine_partials`, the registry's `route()` reason, a sealed segment as its own record), recovery's `Quarantined` shown as the variant the edge refuses with 400, and the `GET /braid` read the console's Mission view, the TUI's Braid line and the operator page poll. | +| `strand-flow.svg` (+ `.png`) | diagram, the published raster | The hand-drawn original of the Mermaid diagram above, kept because the published entry's absolute URL still resolves to it. The three owners that report — the mission broker calling `observe` directly (it runs in this process), and the two strands that live in other processes, the evidence recorder's `EvidenceSealed` and the JEPA runtime's `PromotionAccepted` / `PromotionRolledBack`, crossing the one write edge (`POST /braid` carrying the frozen `BraidEvent`, 503 on a failed dispatch, no de-duplication) — then `observe` as the sole mutator, the folded `BraidState` and its six fields, the durable copies the braid does not keep (MCAP quarantine, the registry's rollback record), recovery's `Quarantined` shown as the variant the edge refuses with 400, and the `GET /braid` read the console, TUI and operator page poll. | | `loop-state.json` | data | The two event sequences the fold is replayed from, the pace gate's constants and its two asserted stale publications, and the console fixture's `BraidState` fields. | ## Data @@ -55,6 +57,10 @@ $ py -3.13 docs/figures/the-agent-in-the-loop/make_figures.py figures: crate fold [1, 2, 1, 0, 0], edge fold [1, 0], pace 250 ms × 8 (stale at 2000 ms), wrote mission-lifecycle, strand-flow ``` +`strand-flow.mmd` is not written by the generator — there is no Mermaid step here — so it is edited +by hand, and `make_figures.py` still rewrites the `.svg`/`.png` beside it that the published entry's +absolute URL resolves to. The figures check is the gate the `.mmd` passes. + No Blender step: this entry is a state machine and a gate — a chart and a schematic, not a numeric field with a shape to turn — so the render band of `docs/figures/README.md` rule 2 is not added, and the entry's `.svg` figures are diff --git a/docs/figures/the-agent-in-the-loop/strand-flow.mmd b/docs/figures/the-agent-in-the-loop/strand-flow.mmd new file mode 100644 index 0000000..a5b8aff --- /dev/null +++ b/docs/figures/the-agent-in-the-loop/strand-flow.mmd @@ -0,0 +1,22 @@ +flowchart TD + subgraph owners["the three owners that report"] + MB["mission broker\nopens and closes a mission by calling observe directly:\nit runs in this process"] + ER["evidence recorder\nanother process: it hands over EvidenceSealed\nwith the segment's digest, over the edge"] + JEPA["JEPA runtime\nanother process: it hands over PromotionAccepted /\nPromotionRolledBack on a move"] + end + + EDGE["POST /braid — the write edge the two other-process strands cross\nfrozen BraidEvent in, the GET /braid view out; a failed dispatch is 503.\nNot deduplicated: the count is the events folded, so a re-delivered\nmission_opened counts twice"] + OBS["observe(state, event)\nthe sole mutator of BraidState"] + REFUSED["the variant the edge refuses\nrecovery's Quarantined is not a strand report: the edge refuses it with 400,\nand the dispatch (renaming *.partial files aside) stays in the crate's fold,\nover a local root — no strand, and no state moved"] + STATE["BraidState (the agent's own copy)\nschema_version · generation · session_id\nopen_missions · last_promotion_ns · last_quarantine_ns —\nthe fold, rebuildable by replaying the stream"] + COPIES["the durable copies — where the records live\nMCAP: quarantine_partials moves the partials aside\nregistry: route() writes a rollback's reason, a handle the fold does not hold\na sealed segment is its own record — the braid keeps none of them"] + READ["GET /braid — the read every strand and page polls\nthe console's Mission view, the TUI's Braid line and the operator page read it;\nBeliefClock::decision_latency_ns() reads the arena's own stamps instead —\nit is a view over the region, not a field of this state"] + + MB --> OBS + ER --> EDGE + JEPA --> EDGE + EDGE -- "the frozen BraidEvent" --> OBS + OBS -- "the fold" --> STATE + REFUSED -. "the crate's fold, over a local root" .-> COPIES + STATE --> READ + COPIES --> READ