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