rose-ash/plans/agent-briefings/host-persist-loop.md

# host-persist loop agent (single agent, builds the durable storage host)

Role: make `lib/persist`'s durable backend **actually durable**. The persist
substrate (`lib/persist/**`, 201/201 tests) performs `{:op "persist/..." :args}`
IO requests for every storage op; under `sx_server.exe` today nothing services
them, so writes silently vanish. You build the **host-side adapter** that answers
those ops against real on-disk storage — the one piece standing between persist
and "all subsystems share a durable substrate."

```
worktree:    /root/rose-ash-loops/host-persist
branch:      loops/host-persist   (push origin/loops/host-persist; NEVER main/architecture)
```

## The authoritative contract — read this first, every restart

`plans/persist-on-sx.md` → **Blockers → "OPEN — host durable-storage adapter"**.
That entry is the spec: the silent-data-loss repro, the full op contract table,
the hard invariants (monotonic `last-seq`, etc.), the blob adapter shape, where
to register in `sx_server.ml`, and the acceptance test. Do not restate it here —
read it there and implement it. The reference implementation to mirror is
`persist/serve` in `lib/persist/durable.sx` (same op names, same shapes).

## Restart baseline — check before iterating

1. Read the Blocker spec (above) + this briefing.
2. `git log --oneline -8` on `loops/host-persist` to see what's done.
3. Is there a worktree-local build? `ls hosts/ocaml/_build/default/bin/sx_server.exe`.
   Fresh worktrees have none — the first build is the first task.
4. If an acceptance suite exists (e.g. `hosts/ocaml/test/persist_durable_*` or a
   `lib/persist/tests/durable-real.sx`), run it against the **worktree-built**
   binary. Green before new work.

## The queue (phases)

- **Phase 0 — reproduce.** Confirm the silent-data-loss repro from the spec under
  this worktree. Builds your mental model; costs one short run.
- **Phase 1 — storage module.** A new OCaml module under `hosts/ocaml/` that
  implements the op contract over **real persistent storage**. Start simple and
  correct: a filesystem-backed store (one append-only file per stream + a kv
  file + a per-stream seq high-water file), or SQLite if the toolchain has it.
  Honour every invariant in the spec — especially: `last-seq` is a monotonic
  counter stored separately from rows so it survives `truncate`; values
  round-trip structurally.
- **Phase 2 — register.** Wire a `"persist/..."` arm into the kernel's IO
  resolver (`Sx_types._cek_io_resolver`, ~line 3864 of `hosts/ocaml/bin/sx_server.ml`)
  and/or the `cek_run_with_io` bridge path (~528–576), dispatching to the storage
  module. Op names are the contract — do not rename.
- **Phase 3 — acceptance.** New tests that use `persist/durable-backend` (REAL
  `perform`, not the mock) run under the freshly-built worktree binary: the
  `durable` + `recovery` semantics must pass, and a **real process restart**
  (start the built server, write, stop it, start again, replay) must recover
  state from disk. Put host-owned tests under a host path (e.g.
  `hosts/ocaml/test/`) — do not churn persist's existing suites.
- **Phase 4 — blob adapter.** Same pattern for `blob/put|get|has?` backed by a
  content-addressed directory; persist stores only the ref.

Every iteration: implement → build → test → commit (short factual message) →
push → update `plans/persist-on-sx.md` (tick the Blocker toward CLOSED, append a
dated Progress-log line, newest first) → next.

## Ground rules (hard)

- **Build is your job** (unlike the persist loop). But build **only in this
  worktree's `_build`** via `dune` from `/root/rose-ash-loops/host-persist`.
  **NEVER overwrite the shared binary** at
  `/root/rose-ash/hosts/ocaml/_build/default/bin/sx_server.exe` — every sibling
  loop uses it; clobbering it breaks them all. Point acceptance tests at the
  worktree binary (`hosts/ocaml/_build/default/bin/sx_server.exe` *inside this
  worktree*).
- **First build is slow** (full OCaml). The `sx_build` MCP tool has a ~600s
  watchdog that may kill it — prefer `dune build bin/sx_server.exe` (or `@all`)
  run via Bash with `run_in_background: true` and a long timeout, then poll.
- **NEVER `pkill sx_server`** — siblings share the process/binary. Start your own
  server on a throwaway path/port for restart tests and stop only that PID; bound
  every run with `timeout`.
- **Scope:** `hosts/**`, host-owned test files, and the Blocker entry +
  Progress log in `plans/persist-on-sx.md`. Do **not** modify `lib/persist/**`
  source (the persist loop owns it; its API is your contract, not your code) —
  if you need an upstream change, leave a note in the Blocker entry.
- **Determinism:** replay from disk must equal the in-memory semantics; same log
  → same state.
- **Commits:** one feature per commit; push to `origin/loops/host-persist`.
- **SX files:** `sx-tree` MCP tools ONLY, `file:` not `path:`, `sx_validate`
  after edits. (Most of your work is OCaml — edit those with normal tools.)

## Definition of done

The Blocker entry flips to **CLOSED**: `persist/durable-backend` writes land on
disk, survive a real server restart, and the durable + recovery acceptance suites
are green against the worktree-built binary. At that point a subsystem migrated
per `lib/persist/examples/acl.sx` is genuinely durable.

Go. Read the Blocker spec; reproduce the gap; build the storage module.