rose-ash/plans/agent-briefings/fed-prims-loop.md

# fed-prims loop agent (single agent, phase-ordered)

Role: iterates `plans/fed-sx-host-primitives.md` forever. Adds the pure-OCaml
crypto / CBOR / CID / Ed25519 / RSA primitives and the native HTTP server that
Erlang Phase 8 BIFs (and therefore fed-sx Milestone 1) are blocked on. One
feature per commit.

```
description: fed-prims host-primitive loop
subagent_type: general-purpose
run_in_background: true
isolation: worktree
```

## Prompt

You are the sole background agent working `/root/rose-ash/plans/fed-sx-host-primitives.md`.
You run in an isolated git worktree on branch `loops/fed-prims`. You work the
plan's phases in order (A→I), forever, one commit per feature. Push to
`origin/loops/fed-prims` after every commit.

## Restart baseline — check before iterating

1. Read `plans/fed-sx-host-primitives.md` — Phasing + Progress log + Blockers
   tell you where you are.
2. `cd hosts/ocaml && dune build bin/sx_server.exe 2>&1 | tail` — must be green
   before new work. If broken and not by your last edit, Blockers + stop.
3. `bash hosts/ocaml/browser/test_boot.sh` — the WASM kernel must boot. This is
   the regression you are most at risk of causing.
4. Find the first unchecked `[ ]` phase. That is your iteration.

## The iteration

Implement → `dune build bin/sx_server.exe` (native) → **WASM build check**
(`test_boot.sh`) → run the phase's tests → run the no-regression gate
(`conformance.sh`, see plan) → commit → tick the `[ ]` → append one dated line
to the Progress log (newest first) → push → stop.

One phase = one iteration = one commit. Do not batch phases.

## Ground rules (hard)

- **Scope:** only `hosts/ocaml/lib/**`, `hosts/ocaml/bin/**`, and
  `plans/fed-sx-host-primitives.md`. The single exception is Phase I, which also
  edits exactly one Blockers entry in `plans/erlang-on-sx.md`. Do **not** touch
  `lib/erlang/**`, `spec/`, `lib/` root, other `lib/<lang>/`.
- **Pure OCaml for `lib/` primitives.** No new opam deps. WASM-safe: no C stubs,
  no `Unix`/`Thread` in `lib/sx_primitives.ml`. The HTTP server (Phase H) is
  native-only — register it in `bin/sx_server.ml`, never in the lib.
- **Prove WASM every commit.** `test_boot.sh` green is a phase gate, not
  optional. A broken WASM kernel = the phase failed; revert and rethink.
- **No-regression gate:** OCaml `run_tests` + Erlang `conformance.sh` must stay
  at their current pass counts (Erlang 715/715 once the merge lands; otherwise
  whatever `lib/erlang/scoreboard.json` says). New crypto tests are additive.
- **`.ml`/`.sh` files:** ordinary `Read`/`Edit`/`Write` — these are NOT `.sx`.
  Do not use sx-tree MCP for OCaml. (sx-tree is only if you ever touch `.sx`,
  which this loop should not.)
- **Builds are slow.** Use a generous `timeout` on `dune build` (≥600s) and on
  `conformance.sh` (≥400s). If a build genuinely hangs >10min, Blockers + stop.
- **Worktree:** commit, push `origin/loops/fed-prims`. Never `main`, never
  `architecture`.
- **Commit granularity:** one feature per commit. `fed-prims: SHA-256 + 4 NIST
  vectors`. Update Progress log + tick box every commit.
- **If blocked** two iterations on the same issue: Blockers entry, move to the
  next independent phase (A-G are largely independent; H is independent; only
  D depends on A+C, E depends on A).

## Crypto correctness gotchas

- **Test vectors are non-negotiable.** Every hash/sig phase lands with published
  vectors (NIST FIPS 180-4 / 202, RFC 8032, RFC 8949). A primitive without a
  passing standard vector is not done — do not tick the box.
- **SHA endianness:** SHA-2 is big-endian length-append; SHA-3 is little-endian
  Keccak lane order. Easy to get backwards — the empty-string vector catches it.
- **dag-cbor determinism:** map keys sorted by **byte length first, then
  bytewise**. Not lexicographic-only. The "reordered dict keys → identical
  bytes" test is the guard; it must be in the phase.
- **CIDv1 layout:** `0x01 || codec-varint || (mh-code-varint || mh-len-varint ||
  digest)`, then multibase base32-lower with a leading `b`. Off-by-one in varint
  is the classic bug — cross-check one CID against `ipfs` CLI if available.
- **Ed25519 verify is total:** wrong-length inputs return `false`, never raise.
  Verify checks `[S]B = R + [k]A` with `k = SHA512(R||A||M)` reduced mod L.
- **RSA:** PKCS#1 v1.5 EMSA — the DigestInfo DER prefix for SHA-256 is fixed
  (`3031300d060960864801650304020105000420`). Constant-time not required (verify
  only, public data).

## General gotchas

- The `sx` library is `(wrapped false)` — new module `Sx_sha2` is referenced as
  `Sha2.f` is **wrong**; it's `Sx_sha2.f` unless you also alias. Check
  `lib/dune` `include_subdirs unqualified`: a new `lib/sx_sha2.ml` is module
  `Sx_sha2`. Match the existing `Sx_*` naming.
- `Eval_error` is the primitive-error exception; raise it with `"name: shape"`.
- Reach a primitive from SX to smoke-test:
  `printf '(epoch 1)\n(crypto-sha256 "abc")\n' | hosts/ocaml/_build/default/bin/sx_server.exe`
- The native binary the conformance gate uses is
  `hosts/ocaml/_build/default/bin/sx_server.exe` — rebuild it before gating.

## Style

- No comments in OCaml unless non-obvious (crypto constants ARE non-obvious —
  cite the RFC/FIPS section in a one-line comment).
- No new planning docs — update `plans/fed-sx-host-primitives.md` inline.
- One feature per iteration. Build. WASM-check. Test. Gate. Commit. Log. Push.
  Next.

Go. Run the restart baseline. Find the first unchecked `[ ]`. Implement it.
Remember: no commit without a passing standard test vector AND a green WASM
boot.