# Repository Guidelines ## Project Structure & Module Organization - `ocaml/` contains the OCaml Nock interpreter: core modules in `lib/`, tests in `test/`, benchmarks in `bench_*`, plus pills and scripts for experiments. - `vere/` hosts the Zig runtime: `pkg/` implements packages such as `noun` and `vere`, `ext/` bundles C dependencies, and `doc/`/`docker/` provide references and tooling. - Root `flake.nix` defines the shared Nix dev shell; keep repo-level scripts executable and language-agnostic so both stacks can reuse them. ## Build, Test, and Development Commands - `nix develop` seeds an environment with OCaml 5.3, Zig 0.14, dune, sqlite, and the tooling pinned in `flake.nix`. - `dune build` (from `ocaml/`) compiles the interpreter; `dune exec ./test_nock.exe` or `make -C ocaml test` runs the opcode regression tests with logs. - `make -C ocaml bench` benchmarks the OCaml implementation; capture the output when tuning performance-sensitive code. - `zig build` (inside `vere/`) produces a debug `urbit`; append `-Doptimize=ReleaseFast` for release-grade binaries or `-Dall` for cross compilation. - `zig build nock-test ames-test --summary all` exercises the key runtime suites; invoke additional named targets when modifying other packages. ## Coding Style & Naming Conventions - OCaml files use two-space indentation, modules in `Camel_case`, values/functions `snake_case`; run `dune fmt --auto-promote` (ocamlformat) before committing. - Zig sources rely on `zig fmt`; keep functions `lower_snake_case`, types `UpperCamelCase`, and mirror existing spacing in `vere/pkg/*`. - Bench C helpers under `ocaml/bench_*` should stick to the supplied `gcc` flags and simple `snake_case` utilities. ## Testing Guidelines - Extend OCaml coverage under `ocaml/test/`, mirroring the `test_` functions already in `test_nock.ml`; ensure failures exit non-zero for CI scripts. - Add Zig tests next to the package being touched (e.g., `vere/pkg/noun/test_*.zig`) and register them in `build.zig` so `zig build ` exposes them. - When altering benchmarks or runtime behavior, include before/after metrics from `make -C ocaml bench` or the relevant `zig build` target. ## Commit & Pull Request Guidelines - Commits follow the repository’s short, lowercase subject line pattern (`moar docs`, `iris and dill`); keep them under ~60 characters and expand detail in the body when necessary. - Name branches `i//` consistent with `vere/CONTRIBUTING.md`; open PRs with `Resolves #` plus the commands and fake-ship steps used for validation. - PRs should flag test coverage, benchmark deltas, and pill or configuration updates; attach screenshots only when developer UX changes are visible. codex resume 0199b79c-dc49-7563-8dc4-bf017dbf45a6