@flowsilver/algoviz 0.0.0-stage → 0.4.0

package/apps/inspector/style.css

@@ -0,0 +1,85 @@
+:root {
+  color-scheme: light;
+  font-family: "Geist", "Inter", system-ui, sans-serif;
+  color: #182922;
+  background: #eef1ea;
+  --border: #cbd5cb;
+  --green: #176249;
+  --muted: #50635a;
+  --mono: "IBM Plex Mono", ui-monospace, monospace;
+}
+
+* { box-sizing: border-box; }
+[hidden] { display: none !important; }
+body { margin: 0; }
+main { max-width: 75rem; margin: auto; padding: 2.4rem clamp(1rem, 4vw, 3rem); }
+.header { display: flex; flex-wrap: wrap; justify-content: space-between; align-items: baseline; gap: .5rem 1rem; margin-bottom: 1.5rem; }
+h1 { margin: 0; font-size: clamp(2rem, 6vw, 3rem); letter-spacing: -.07em; }
+#source { color: var(--muted); font: .8rem var(--mono); overflow-wrap: anywhere; }
+.timeline { display: flex; flex-wrap: wrap; align-items: center; gap: 1rem; padding: .85rem; border: 1px solid var(--border); border-radius: .85rem; background: #fff; margin-bottom: 1rem; }
+.buttons { display: flex; gap: .5rem; }
+button { min-height: 2.65rem; padding: .5rem .9rem; border: 1px solid var(--border); border-radius: .5rem; background: #f8faf7; color: inherit; font: inherit; font-weight: 650; cursor: pointer; }
+#next { background: var(--green); border-color: var(--green); color: #fff; }
+button:disabled { opacity: .45; cursor: default; }
+button:focus-visible, input:focus-visible { outline: 2px solid var(--green); outline-offset: 3px; }
+.seek { display: flex; flex: 1 1 12rem; align-items: center; gap: .7rem; font-size: .82rem; color: var(--muted); }
+.seek input { flex: 1; min-width: 4rem; accent-color: var(--green); }
+#step { font: .8rem var(--mono); font-variant-numeric: tabular-nums; }
+#error { padding: .75rem; border: 1px solid #b75242; border-radius: .5rem; background: #fff4f0; color: #7f2c21; }
+.views { display: flex; flex-wrap: wrap; align-items: stretch; gap: 1rem; }
+.views[data-layout="column"] { display: grid; }
+.view { flex: 1 1 18rem; min-width: 0; border: 1px solid var(--border); border-radius: .85rem; background: #fff; overflow: hidden; }
+.view--graph { flex: 2 1 27rem; }
+.view :is(h2, h3) { margin: 0; padding: .95rem 1rem; border-bottom: 1px solid #e5ebe4; font-size: 1rem; }
+.graph { display: block; width: 100%; max-height: min(28rem, 54vh); min-height: 12rem; background: #f9fbf8; }
+.graph-edge { fill: none; stroke: #6c8074; stroke-width: 1.5; }
+.graph-arrow { fill: #6c8074; }
+.graph-edge-label { fill: #253e33; font: 650 11px var(--mono); text-anchor: middle; dominant-baseline: central; paint-order: stroke; stroke: #f9fbf8; stroke-width: 4px; stroke-linejoin: round; pointer-events: none; }
+.graph-node circle { fill: #f1f4ef; stroke: #98ac9d; stroke-width: 1.5; }
+.graph-node[data-status="queued"] circle { fill: #f9ead1; stroke: #a87729; }
+.graph-node[data-status="visited"] circle, .graph-node[data-status="settled"] circle { fill: #d9efe1; stroke: var(--green); }
+.graph-node text { fill: #182922; font: 650 12px var(--mono); text-anchor: middle; }
+.graph-node .graph-status { fill: var(--muted); font-size: 10px; font-weight: 500; paint-order: stroke; stroke: #f9fbf8; stroke-width: 3px; stroke-linejoin: round; }
+.array { display: flex; flex-wrap: wrap; gap: .55rem; list-style: none; padding: 1rem; margin: 0; }
+.array li { min-width: 2.6rem; max-width: 100%; padding: .5rem .7rem; border: 1px solid #cadbcf; border-radius: .5rem; background: #edf6ef; overflow-wrap: anywhere; }
+.array code { font: .9rem var(--mono); white-space: pre-wrap; }
+.array--labeled li { display: grid; gap: .15rem; min-width: 3.15rem; }
+.array-label { color: var(--muted); font-size: .75rem; }
+.empty { margin: 0; padding: 1rem; color: var(--muted); }
+
+.inspection { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); align-items: start; gap: 1rem; margin-top: 1rem; }
+.inspection details { min-width: 0; border: 1px solid var(--border); border-radius: .85rem; background: #fff; }
+.inspection summary { padding: .95rem 1rem; font-weight: 650; cursor: pointer; }
+.inspection details[open] summary { border-bottom: 1px solid #e5ebe4; }
+[data-state-json], [data-change-list] { max-height: 22rem; overflow: auto; margin: 0; }
+[data-state-json] { padding: 1rem; background: #f9fbf8; font: .82rem/1.5 var(--mono); border-radius: 0 0 .85rem .85rem; }
+.changes { margin: 0; padding: 0; list-style: none; }
+.changes li { padding: .75rem 1rem; border-bottom: 1px solid #e5ebe4; }
+.changes li:last-child { border-bottom: 0; }
+.change-heading { display: flex; flex-wrap: wrap; align-items: baseline; justify-content: space-between; gap: .3rem; }
+.change-heading code { overflow-wrap: anywhere; font: .8rem var(--mono); }
+.change-kind, .change-value-label { color: var(--muted); font-size: .75rem; }
+.change-values { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: .65rem; margin-top: .55rem; }
+.change-values pre { min-height: 2rem; max-height: 6rem; overflow: auto; margin: .15rem 0 0; padding: .45rem; border-radius: .35rem; background: #f1f5ee; font: .78rem var(--mono); }
+.change-values .change-absent { color: var(--muted); }
+
+.episode-form, .episode-form label { display: flex; align-items: center; gap: .5rem; }
+.episode-form label { color: var(--muted); font-size: .82rem; }
+.episode-form input { width: 5.5rem; min-height: 2.65rem; border: 1px solid var(--border); border-radius: .5rem; padding: .5rem; font: 1rem var(--mono); }
+#comparison { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 1rem; align-items: start; }
+.comparison-run { min-width: 0; }
+.comparison-run > header { margin-bottom: .8rem; }
+.comparison-run > header h2 { margin: 0; overflow-wrap: anywhere; font-size: 1.25rem; }
+[data-run-status] { margin: .3rem 0 0; color: var(--muted); font: .84rem var(--mono); }
+.comparison-run .inspection { gap: .6rem; }
+
+@media (max-width: 48rem) {
+  .inspection { grid-template-columns: 1fr; }
+  #comparison { grid-template-columns: 1fr; }
+}
+
+@media (max-width: 34rem) {
+  .timeline { gap: .7rem; }
+  .seek { order: 1; flex-basis: 100%; }
+  #step { margin-left: auto; }
+}

package/apps/inspector/views.js

@@ -0,0 +1,40 @@
+import { resolvePointer } from "../../packages/core/json-pointer.js";
+import { renderArray, renderGraph } from "../../packages/renderers/index.js";
+
+function viewTitle(id) {
+  const title = id.replaceAll(/[-_]+/g, " ").trim() || id;
+  return title.charAt(0).toUpperCase() + title.slice(1);
+}
+
+export function attachViews(container, specText, renderers, runIndex, headingTag = "h2") {
+  const spec = JSON.parse(specText);
+  container.dataset.layout = spec.layout;
+  const panels = spec.views.map((view, index) => {
+    const title = viewTitle(view.id);
+    const key = `${runIndex}-${index}`;
+    const panel = document.createElement("section");
+    panel.className = `view view--${view.type}`;
+    panel.dataset.viewId = view.id;
+    const heading = document.createElement(headingTag);
+    heading.id = `view-heading-${key}`;
+    heading.textContent = title;
+    panel.setAttribute("aria-labelledby", heading.id);
+    const content = document.createElement("div");
+    panel.append(heading, content);
+    container.append(panel);
+    let render;
+    if (view.type === "graph") render = (data) => renderGraph(data, title, key);
+    if (view.type === "array") render = (data) => renderArray(data, view.item);
+    if (view.type === "custom") {
+      const custom = renderers.get(view.renderer);
+      if (typeof custom !== "function") throw new Error(`Missing renderer "${view.renderer}"`);
+      render = (data) => custom(data, { id: view.id, title });
+    }
+    return { view, render, content };
+  });
+
+  return (frame) => {
+    const nodes = panels.map(({ view, render }) => render(resolvePointer(frame.state, view.source)));
+    for (const [index, panel] of panels.entries()) panel.content.replaceChildren(nodes[index]);
+  };
+}

package/docs/protocol.md

@@ -0,0 +1,105 @@
+# AlgoViz protocol v1
+
+The inspector consumes a JSON Visualization Specification and a JSONL Execution Trace for one run. The spec and the trace's initial record both declare `version: 1`. Reject missing, unsupported, or mismatched versions. Encode both files as UTF-8 without a byte order mark. Reject duplicate member names in JSON objects so each binding and update has a single interpretation.
+
+## Visualization Specification
+
+Validate the spec against the [Visualization Specification schema](../schemas/visualization-spec.schema.json). The `views` list determines display order. The `layout` field arranges views left to right (`row`) or top to bottom (`column`). Each view has a unique `id`, a `type`, and a `source` pointer into the state of the current step. The empty pointer binds the whole state.
+
+| View type | Data at `source` |
+| --- | --- |
+| `graph` | A graph with `nodes` and `edges` arrays. Nodes have stable `id` values and optional `label` and `status` text. Each edge has a stable `id` plus `source` and `target` node IDs. Starting in `v0.2.0`, text and numeric values in `edge.label` appear beside the edge. Other values remain valid graph metadata. [Graph view data schema](../schemas/graph-view-data.schema.json) |
+| `array` | A JSON array in display order. For a frontier queue, index `0` holds the next item. Starting in `v0.2.0`, an optional `item` binding displays a label and value for each entry. |
+| `custom` | A JSON value passed to a renderer registered explicitly when building the offline preview. The required `renderer` field names that registration. |
+
+Use unique node IDs and unique edge IDs within a graph. Both endpoints of each edge must resolve to nodes in that graph at the same step. Keep an element's ID stable as its data changes. Resolve and validate every binding at step 0 and after applying all updates in each subsequent step. Each view reads the same committed state.
+
+### Labeled Array items
+
+An Array view's `item.label` and `item.value` are JSON Pointers evaluated against each array entry. The label resolves to a string and the value resolves to any JSON value. Both pointers must resolve in every frame. `item.nullLabel` sets the display text for an explicit `null` value. It defaults to `—`.
+
+```json
+{
+  "id": "tentative-distances",
+  "type": "array",
+  "source": "/distances",
+  "item": { "label": "/vertex", "value": "/distance", "nullLabel": "∞" }
+}
+```
+
+The entry `{"vertex":"S","distance":0}` displays `S` with value `0`. The entry `{"vertex":"U","distance":null}` displays `U` with `∞`. Array views without `item` display their entries directly, including the original `v0.1.0` specs.
+
+### Custom renderers
+
+A view such as `{"id":"lake","type":"custom","renderer":"frozenlake","source":""}` binds the whole frame to the named renderer. Names start with a lowercase letter and can contain lowercase letters, digits, and hyphens.
+
+Pass `--renderer frozenlake=./grid.js` to `preview` or `compare` to register one local browser module. Its default export is a synchronous function `(data, { id, title }) => Node` called for each displayed frame. Return a DOM node or fragment. The bound data comes from a detached replay frame and should be treated as read-only. The replay engine checks that the pointer resolves. The renderer defines the expected shape of its data.
+
+The CLI bundles the module and its browser-compatible imports into the output HTML. The spec selects a registered renderer by name. Registration and the module path come from the CLI caller. The bundled module executes as JavaScript with access to the preview page and its embedded traces, so register code you trust before opening or sharing the HTML. [FrozenLake renderer](../examples/frozenlake/grid.js)
+
+### Comparing two runs
+
+`algoviz compare <left-spec> <left-trace> <right-spec> <right-trace>` reads two v1 runs. Each state has zero-based integer `episode` and `t` fields. Both start at zero. Within an episode, `t` increases by one per trace step. A reset advances `episode` by one and sets `t` to zero. When both runs record a string at `/last/action`, the viewer can jump to the first differing action in the selected episode.
+
+The common position is the episode and its step, with steps available up to the longer run's episode length. A shorter run shows where the episode ended or that the episode is unavailable. Each run's Changes panel compares its selected state with its own preceding recorded step. [FrozenLake example](../examples/frozenlake/README.md#compare-the-runs)
+
+## Execution Trace
+
+Write one JSON record per line, using LF or CRLF with an optional final newline. Reject empty files and blank lines. Validate each record against the [trace record schema](../schemas/trace-record.schema.json).
+
+| Record | Position | Meaning |
+| --- | --- | --- |
+| `initial` | First line, exactly once | Holds `version` and the initial `state` object. This is step 0. |
+| `step` | Every subsequent line | Holds an `updates` array and optional `events`. Each record advances the step index by one, even when `updates` is empty. |
+
+Apply each `updates` array in order to a candidate state starting from the last committed state. An operation sees the results of earlier operations in its batch. Publish the new state and its events together after every operation and binding check succeeds. On failure, reject the whole step, preserve the previous committed state, and stop at the failed line. Semantic events can inform presentation. Only state updates determine the next state, and replay works when an event type is unknown.
+
+### State updates
+
+Use `add`, `remove`, and `replace` from JSON Patch. `path` is a JSON Pointer to a member or array element within the state object. Updates to the root are invalid. Pointer tokens decode `~1` to `/`, then `~0` to `~`. Resolve each intermediate token against an existing object member or array element. Array indices are zero-based decimal integers with no leading zeroes except `0`. [JSON Patch](https://www.rfc-editor.org/rfc/rfc6902#section-4) · [JSON Pointer](https://www.rfc-editor.org/rfc/rfc6901#section-4)
+
+| Operation | Object member | Array element |
+| --- | --- | --- |
+| `add` | Set the member to `value`, creating it when absent. | Insert `value` at an index from `0` through the current length. Use `-` to append. |
+| `remove` | Delete an existing member. | Delete an existing element and shift later elements left. |
+| `replace` | Set an existing member to `value`. | Set an existing element to `value` without changing the array length. |
+
+`add` and `replace` require `value`, which can be any JSON value, including `null`. `remove` takes only `op` and `path`. Report an error for a missing or scalar parent, a missing `remove` or `replace` target, or an array index outside the operation's allowed range. Treat object keys as literal member names. For example, `/frontier/00` fails when `frontier` is an array. The array append token `-` is valid only as the final array token of `add`.
+
+### Validation errors
+
+For an invalid spec, report the file, the location of the offending field when available, and the reason. For an invalid trace, report the file, one-based line number, and reason. For a failing update, also report the zero-based operation index and the update path. For a failing view binding, include the view ID and source pointer. Schema validation checks each document or record's shape. The reader must also enforce record order, apply state updates, and validate bindings and graph references at each step.
+
+## Graph-search fixture
+
+The example traces breadth-first search from node `A`. It visits outgoing neighbors in the order shown in the graph, queues each node at discovery, and records a step after each node is processed. `B` discovers `D`, so processing `C` leaves `D` in the queue once.
+
+- [Spec](../examples/graph-search/visualization.json) binds the views to `/graph` and `/frontier`.
+- [Trace](../examples/graph-search/trace.jsonl) records the initial state and four steps.
+- [Expected states](../examples/graph-search/expected-states.json) lists the fixed edge set, each node's status, and the ordered frontier at every step. Compare against these values after committing each step.
+
+## Replay API
+
+The [replay core](../packages/core/index.js) takes decoded JSONL text. Supply `specText` to validate the spec and its bindings at each reconstructed step. Optional `traceSource` and `specSource` names appear in `ReplayError` diagnostics.
+
+```js
+import { readFileSync } from "node:fs";
+import { loadReplay } from "./packages/core/index.js";
+
+const replay = loadReplay(readFileSync("examples/graph-search/trace.jsonl", "utf8"), {
+  specText: readFileSync("examples/graph-search/visualization.json", "utf8"),
+});
+
+console.log(replay.current.state.frontier); // ["A"]
+console.log(replay.stepForward().state.frontier); // ["B", "C"]
+console.log(replay.stepBackward().state.frontier); // ["A"]
+console.log(replay.seek(replay.lastStep).state.frontier); // []
+```
+
+`current`, `stepForward()`, `stepBackward()`, and `seek(step)` return detached frames containing `step`, `state`, and `events`. Stepping at an endpoint returns its current frame. Seeking outside `0` through `lastStep` throws a `RangeError`.
+
+The offline preview's State panel shows the selected frame's JSON state. The Changes panel compares it with the preceding recorded step using JSON Pointer paths. Step 0 is the initial state. Added or removed values display `Absent` on the missing side, while an explicit JSON `null` displays as `null`. Array entries are compared by index.
+
+`replay.changes` returns the same net comparison as detached `added`, `removed`, and `changed` records. Each record includes its path and the applicable `before` and `after` values. The comparison follows recorded step order regardless of navigation direction. Writes that cancel within a batch produce no change for that path.
+
+Loading validates record structure and the initial view bindings when a spec is supplied. Navigation checks update targets and view bindings as it reconstructs steps. A failed step or seek throws a `ReplayError` and preserves the current frame and its change baseline. Replay keeps the initial state, the selected state, and its preceding state when available. An optional positive integer `checkpointInterval` also caches reconstructed states at that interval for seeking. The comparison uses checkpoints every 128 trace steps. Decoding bytes is the caller's responsibility. The JavaScript reader rejects numbers that decode outside its finite range.

package/examples/frozenlake/README.md

@@ -0,0 +1,96 @@
+# Compare two FrozenLake Q-learning runs
+
+Why did two Q-learning runs with different exploration rates take different paths through the same grid? This fixture records two tabular Q-learning runs in deterministic FrozenLake. It then checks the traces independently and finds the first action where a selected episode diverges.
+
+Both runs use the default 4×4 map, seed `7`, learning rate `0.5`, and discount `0.95`. Only the exploration rate differs: `ε = 0.1` and `ε = 0.3`. Each run trains until it has recorded at least 10,000 transitions and then finishes its current episode. [Run settings](runs.json)
+
+| Run | Episodes | Transitions | Trace states |
+| --- | ---: | ---: | ---: |
+| `epsilon-0.1` | 1,557 | 10,000 | 11,557 |
+| `epsilon-0.3` | 1,448 | 10,000 | 11,448 |
+
+Both runs happen to finish an episode on exactly the 10,000th transition.
+
+## Environment
+
+[frozenlake.py](frozenlake.py) implements Gymnasium's `FrozenLake-v1` with `is_slippery=False` using only the Python standard library. It follows the documented map, the action encoding `0 = LEFT`, `1 = DOWN`, `2 = RIGHT`, `3 = UP`, the observation `row * ncol + col`, the reward schedule `(1, 0, 0)`, and the 100-step time limit. A move off the grid leaves the agent in place. [FrozenLake documentation](https://gymnasium.farama.org/environments/toy_text/frozen_lake/)
+
+The learner chooses a uniformly random action with probability ε. Otherwise it picks the highest-valued action, breaking ties at random. With equal seeds, the two runs make identical choices through episode 115. When the action values at a cell are tied, a greedy choice and an exploratory choice consume the same random draws. The runs first take different actions in episode 116.
+
+## Record and check the runs
+
+From the AlgoViz checkout, use Node.js 22 or later and Python 3.10 or later:
+
+```sh
+npm ci
+python -B examples/frozenlake/record.py frozenlake-runs
+node examples/frozenlake/check.mjs frozenlake-runs
+```
+
+[record.py](record.py) writes `frozenlake-runs/<run>/trace.jsonl` and a `visualization.json` for each run. It mirrors the learner's resets and transitions into the observable state and passes each state to [algoviz_trace.py](algoviz_trace.py). This small standard-library recorder writes the v1 `add`, `remove`, and `replace` updates that reproduce the state. Each trace is about 4.5 MB.
+
+Step 0 is the reset for episode 0. Each transition and each later reset advances the trace by one step. In every state, `episode` and `t` locate the step within its episode, `cell` is the observation, and `last` holds the transition that produced it. `q` holds the action values in `LEFT`, `DOWN`, `RIGHT`, `UP` order.
+
+[check.mjs](check.mjs) replays each trace with the AlgoViz core and checks it against a separate JavaScript implementation of the environment and learner. It does not share code with the recorder. For every recorded step, it checks the following:
+
+- **Transitions.** Each action moves the agent to the cell, reward, termination, and truncation that FrozenLake gives. The episode return, path, totals, and the single updated action value follow the Q-learning update. A greedy action must be one of the highest-valued actions.
+- **Resets.** A new episode follows every terminated or truncated episode and only those. It returns the agent to cell 0 with step 0, return 0, and the learned values unchanged. The trace ends with a finished episode.
+- **Separate run.** Running [frozenlake.py](frozenlake.py) without the recorder produces summaries of the same runs. The checker compares each episode's length, return, outcome, and action sequence with them.
+
+The checker prints each trace's SHA-256 digest, along with the comparison below. [expected.json](expected.json) holds the expected report. The tests regenerate both runs and require an exact match.
+
+## Compare the runs
+
+Build the offline comparison from the repository root after recording both traces:
+
+```sh
+npm run algoviz -- compare examples/frozenlake/comparison.json frozenlake-runs/epsilon-0.1/trace.jsonl examples/frozenlake/comparison.json frozenlake-runs/epsilon-0.3/trace.jsonl --renderer frozenlake=examples/frozenlake/grid.js --output frozenlake.html
+```
+
+Open the printed file URL. Enter episode **1008**, select **Go**, then select **First differing action**. The grid, action values, episode path, State, and Changes all follow the selected position. At step 6, the right run shows that it ended at step 5. At episode 1500, only the left run has data. [Renderer contract](../../docs/protocol.md#custom-renderers)
+
+## Run from an npm installation
+
+The package includes the Python recorder, its FrozenLake adapter, and the comparison spec and renderer. From an empty directory with Node.js 22+ and Python 3.10+, install `@flowsilver/algoviz` when the package is available on npm. To verify an unpublished release candidate, install its packed `.tgz` in place of the registry name.
+
+```sh
+npm install @flowsilver/algoviz
+python -B node_modules/@flowsilver/algoviz/examples/frozenlake/record.py frozenlake-runs
+node node_modules/@flowsilver/algoviz/examples/frozenlake/check.mjs frozenlake-runs
+npm exec -- algoviz compare node_modules/@flowsilver/algoviz/examples/frozenlake/comparison.json frozenlake-runs/epsilon-0.1/trace.jsonl node_modules/@flowsilver/algoviz/examples/frozenlake/comparison.json frozenlake-runs/epsilon-0.3/trace.jsonl --renderer frozenlake=node_modules/@flowsilver/algoviz/examples/frozenlake/grid.js --output frozenlake.html
+```
+
+The Python module `algoviz_trace.py` has no third-party dependencies. Reuse its `TraceWriter` in an adapter by giving it a writable UTF-8 file and the initial state, then calling `step(state)` with the observed state after each transition.
+
+## Episode 1008
+
+In episode 1008, the `ε = 0.1` run reaches the goal and the `ε = 0.3` run falls into a hole. Both runs take `DOWN`, `DOWN`, `RIGHT`, `DOWN` and reach cell 13. In both runs, the learned values there favor `RIGHT`.
+
+| Step 5 | `epsilon-0.1` | `epsilon-0.3` |
+| --- | --- | --- |
+| Trace step | 7517 | 8089 |
+| Values at cell 13 (L, D, R, U) | 0, 0.9025, 0.95, 0.8574 | 0, 0.9025, 0.95, 0.8574 |
+| Action | `RIGHT`, greedy | `LEFT`, exploratory |
+| Resulting cell and reward | 14, 0 | 12 (hole), 0 |
+| Episode outcome | Goal after 6 steps, return 1 | Hole after 5 steps, return 0 |
+
+The values are rounded here. The `ε = 0.3` run did not learn a different preference at cell 13. It took an exploratory action. `LEFT` still has value 0 in both runs because a hole gives the same reward as an unexplored move. The `ε = 0.3` run ends one step earlier. Episode 1008 starts at trace step 7512 in `epsilon-0.1` and 8084 in `epsilon-0.3`.
+
+To inspect one run now, preview it and seek to its trace step:
+
+```sh
+npm run algoviz -- preview frozenlake-runs/epsilon-0.3/visualization.json frozenlake-runs/epsilon-0.3/trace.jsonl
+```
+
+Expand **State** to read `last`, `cell`, `status`, and `q` at the selected step.
+
+## Fault injection
+
+The tests change one trace line, then confirm that the altered trace still passes v1 replay and that the checker rejects it. The checker reports the run, line, episode, and step within the episode:
+
+```text
+epsilon-0.1 epsilon-0.1/trace.jsonl:7519 episode 1008 step 6: reward is 0, expected 1
+epsilon-0.3 epsilon-0.3/trace.jsonl:8085 episode 1008 step 0: reset placed the agent at cell 1, expected the start cell 0
+```
+
+The first line comes from setting the goal reward to 0. The second comes from resetting the agent to cell 1. A third test checks a trace against a separate run with another seed and reports the first episode whose summary differs.

package/examples/frozenlake/algoviz_trace.py

@@ -0,0 +1,69 @@
+"""Write AlgoViz v1 execution traces from Python using only the standard library.
+
+Pass the complete observable state to ``TraceWriter.step``. The writer compares it
+with the previous state and records the JSON Patch ``add``, ``remove``, and
+``replace`` operations that reproduce it.
+"""
+
+import json
+
+
+def _token(key):
+    return str(key).replace("~", "~0").replace("/", "~1")
+
+
+def _same(before, after):
+    return type(before) is type(after) and before == after
+
+
+def diff(before, after, path=""):
+    """Return v1 state updates that turn ``before`` into ``after``."""
+    if isinstance(before, dict) and isinstance(after, dict):
+        updates = [{"op": "remove", "path": f"{path}/{_token(key)}"} for key in before if key not in after]
+        for key, value in after.items():
+            member = f"{path}/{_token(key)}"
+            if key not in before:
+                updates.append({"op": "add", "path": member, "value": value})
+            else:
+                updates.extend(diff(before[key], value, member))
+        return updates
+    if isinstance(before, list) and isinstance(after, list):
+        if len(after) == len(before):
+            return [update for index, (old, new) in enumerate(zip(before, after)) for update in diff(old, new, f"{path}/{index}")]
+        if len(after) > len(before) and all(_same(old, new) for old, new in zip(before, after)):
+            return [{"op": "add", "path": f"{path}/-", "value": value} for value in after[len(before):]]
+    if _same(before, after) and not isinstance(before, (dict, list)):
+        return []
+    if not path:
+        raise ValueError("the trace state must remain a JSON object")
+    return [{"op": "replace", "path": path, "value": after}]
+
+
+def _encode(record):
+    return json.dumps(record, separators=(",", ":"), ensure_ascii=False, allow_nan=False) + "\n"
+
+
+def _snapshot(state):
+    return json.loads(json.dumps(state, allow_nan=False))
+
+
+class TraceWriter:
+    """Record one run as a v1 JSONL trace."""
+
+    def __init__(self, file, state):
+        if not isinstance(state, dict):
+            raise TypeError("the initial state must be a dict")
+        self._file = file
+        self._state = _snapshot(state)
+        self.steps = 0
+        file.write(_encode({"type": "initial", "version": 1, "state": self._state}))
+
+    def step(self, state, events=None):
+        """Record the next state and optional ``{"type": ..., "data": {...}}`` events."""
+        after = _snapshot(state)
+        record = {"type": "step", "updates": diff(self._state, after)}
+        if events:
+            record["events"] = events
+        self._file.write(_encode(record))
+        self._state = after
+        self.steps += 1