1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
|
# Repository Guidelines
## Project Structure & Module Organization
- `ocaml/` hosts the OCaml port; runtime modules live in `ocaml/lib/` (`noun.ml`, `nock.ml`, `serial.ml`, `state.ml`, `boot.ml`), tests in `ocaml/test/`, utility scripts in `ocaml/scripts/`.
- `vere/` is the production C runtime; reference `vere/pkg/noun` and related subsystems when matching behaviour or layout.
- `sword/` holds the Rust experiments (`sword/rust/`); use them for parity checks and implementation ideas when OCaml semantics feel unclear.
## Build, Test, and Development Commands
- `cd ocaml && dune build` — compile the OCaml port and dependencies.
- `cd ocaml && dune exec ./test_nock.exe` — run the focused opcode suite.
- `cd ocaml && dune runtest` — execute the full `ocaml/test/` matrix.
- `cd ocaml && dune exec ./bench_nock.exe` or `make bench` — benchmark against Vere baselines; prefer after changes that touch evaluator hot paths.
- `cd ocaml && make bench-c` — opt-in comparison against the C runtime (requires `vere/build` artifacts).
## Coding Style & Naming Conventions
- Keep the current OCaml style: two-space indentation, `snake_case` values, `CamelCase` modules, and doc-comments (`(** ... *)`) where APIs surface.
- Maintain feature parity with the C headers (e.g., `_n_nock_on` → `nock.ml`) and reuse existing aliases and record layouts.
- Avoid broad `open` statements; prefer explicit module references until a formatter (likely `dune fmt`) is agreed upon.
## Testing Guidelines
- Add targeted test executables under `ocaml/test/` when porting new behaviour; name them after the Vere feature being exercised (`test_hashcons.ml`, `test_parallel_clean.ml`).
- Compare outputs with the Vere runtime, log temporary deviations in `ocaml/STATUS.md`, and use `make bench` plus `ocaml/compare*.sh` to show performance parity when changing evaluator paths.
## Commit & Pull Request Guidelines
- Use short, imperative commit subjects that describe the observable change (`add`, `fix`, `align`).
- Reference affected subsystems (`nock`, `jets`, `runtime`) in either the subject or first line of the body.
- PRs should link the relevant Vere and Sword files, note parity considerations, list test commands run, and include artefacts (bench numbers, logs) when behaviour or performance shifts.
## Current Progress & Next Steps
- ✅ **Interpreters**: Rebuilt `noun` and `nock` modules from scratch; opcode test suite mirrors Sword’s expectations.
- ✅ **Serialization**: Bitstream utilities plus fresh jam/cue implementation; exhaustive tests ported from Sword (`test_jam_cue_*`, invalid encodings, random round-trips).
- ✅ **State & bootstrap scaffolding**: `state.ml` manages the Arvo core/event counter; `boot.ml` cues pills, runs the lifecycle formula `[2 [0 3] [0 2]]`, and stashes the ivory kernel.
- ✅ **Pill sanity**: Smoke tests confirm `cue ∘ jam` succeeds for `baby.pill` and `ivory.pill`.
- ⏳ **Up next**:
1. Finalise `%solid` replay: extract bot/mod/use events and feed them through `State.poke` using the real gate formula.
2. Compare the ivory boot result (core digest, event counter) against Vere/Sword to confirm lifecycle parity.
3. Introduce the event log (append/replay jammed events) so pill replay and runtime events share one pipeline.
4. Once parity is verified, wire a minimal runtime loop and drivers around `State`.
|
