# `SuperPi.CodeMode.Journal`
[🔗](https://github.com/oleksandr/super-pi-beam/blob/v0.1.0/lib/super_pi/code_mode/journal.ex#L1)

Deterministic Codemode Replay Journal (`Decision 07`, `Step 8`).

When a Codemode script executes nested `execute_tool(call_index, tool_name, args)` calls inside a
durable task (`task_id`), each completed nested call is persisted in a task-scoped document
(`scope_kind: "task"`, `scope_id: task_id`, `kind: "pi.codemode.journal"`).

If the BEAM node or worker crashes mid-script and `TaskEngine.reconcile_on_open!/1` restarts the
Codemode task, `execute_journaled_tool/5` replays the exact recorded 3-channel result for already
completed `call_index` steps without re-executing external side effects, and only runs live tool
execution for unrecorded steps.

# `execute_journaled_tool`

Executes a nested tool call at deterministic step `call_index` within `task_id`.
- If `(call_index, tool_name, args)` is already recorded in `pi.codemode.journal` for `task_id`,
  returns `{:replayed, cached_result}` without invoking `executor_fun`.
- Otherwise invokes `executor_fun.(tool_name, args)`, persists the result in `pi.codemode.journal`,
  and returns `{:executed, fresh_result}`.

# `run_script`

Runs a sequence of Codemode step specifications `[{tool_name, args}, ...]` under `task_id` with
automatic crash recovery replay. If `simulate_crash_at_index` is set, raises after that step so
tests can verify deterministic replay on subsequent runs.

---

*Consult [api-reference.md](api-reference.md) for complete listing*