Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 17 additions & 3 deletions docs/figures/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
<name>.svg <name>.png one figure: vector source, and the raster beside it
<name>.mmd a Mermaid diagram (rule 1); source, not a counted asset
<name>.json the recording the figure draws (optional)
<name>.glb a Blender render (optional; steps 42–43)
```
Expand All @@ -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 `<name>.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.
Expand Down
10 changes: 8 additions & 2 deletions docs/figures/the-agent-in-the-loop/README.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down
22 changes: 22 additions & 0 deletions docs/figures/the-agent-in-the-loop/strand-flow.mmd
Original file line number Diff line number Diff line change
@@ -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