# Agent Notes

This repository is an implemented OCaml research prototype in release-hardening
mode. Treat it as a semantic artifact with evidence, not as a greenfield
language project. Before editing code, read:

1. `README.md`
2. `docs/README.md`
3. `docs/development-plan.md`
4. `docs/ast.md`
5. `docs/release/0.3/EVIDENCE.md`

The original development plan has been completed. Use Task Master only for
local historical context unless the user explicitly asks for it.

```bash
task-master next
task-master show <id>
task-master set-status <id> in-progress
task-master validate-dependencies
```

## Tooling

Use asdf only to provide `opam`. Use the repo-local opam switch for OCaml and OCaml packages.

Run this before OCaml commands in a fresh shell:

```bash
eval "$(opam env)"
mkdir -p "$PWD/.scratch/tmp"
export TMPDIR="$PWD/.scratch/tmp"
```

Keep temporary clones, worktrees, release reproductions, and generated test
stores under `.scratch/` in this repository. The root filesystem is small: do
not create Jacquard workspaces or build artifacts under `/tmp`.

Expected local toolchain:

- `opam` 2.5.1 from `.tool-versions`
- OCaml 5.1.1 from the repo-local switch
- `dune`
- `alcotest`
- `qcheck`
- `digestif`
- `ocamlformat`
- `menhir`
- `cmdliner`
- `ocaml-lsp-server`
- `utop`
- `odoc`

Core commands for the current scaffold:

```bash
eval "$(opam env)"
opam exec -- dune build
opam exec -- dune build @all
opam exec -- dune test
opam exec -- dune runtest
opam exec -- dune fmt
git diff --exit-code
opam exec -- dune build @doc
```

The implementation is in `src/` with suites in `test/`. Verify the environment with:

```bash
eval "$(opam env)"
ocaml -version
dune --version
opam exec -- dune build @all
opam exec -- dune runtest
```

When adding valid corpus files, regenerate the golden hashes with
`opam exec -- dune exec test/gen_goldens.exe` and commit the diff (see
`corpus/README.md`).

## Working Rules

- Preserve the release-hardening posture unless the user explicitly asks for
  feature work.
- Start from existing tests and docs. Jacquard behavior is pinned by cram
  transcripts, Alcotest/QCheck suites, corpus goldens, demos, and release docs.
- Keep behavior tied to the 27 kernel forms in `docs/ast.md`. Public `.jac`
  syntax must remain a projection onto those forms, and bootstrap `.jqd`
  remains the permanent kernel/debug carrier.
- Do not hand-maintain a `.jqd` twin for an ordinary `.jac` program or demo.
  Add paired carriers only when a conformance test explicitly requires hash or
  lowering parity; twins are evidence fixtures, not a publishing requirement.
- During 0.3 release hardening, do not expand the native/performance scope or
  add macros beyond quote/unquote/gated eval, records, typed staging,
  continuous distributions, package management, self-hosting, or
  ownership/borrowing.
- Use `dune`, `alcotest`, and `qcheck` for build and tests.
- Use `digestif` for the initial hash implementation unless the owner changes D1.
- Use `menhir` for the bootstrap reader if a generated parser is needed.
- Use `cmdliner` for the CLI.
- Use `ocamlformat` for formatting once the project has a formatter config.
- Public functions in touched modules should have doc comments describing contracts and failure modes.
- Library code should return `('a, Diag.t list) result`; exceptions are only for internal invariant failures and should be prefixed `Bug_`.

## Where To Look

- Fresh-clone setup and common commands: `README.md`.
- Documentation map: `docs/README.md`.
- Runtime examples: `docs/tutorial.md`.
- Demo catalog: `demos/README.md`.
- CI and release process: `docs/ci-cd.md`.
- Current release evidence: `docs/release/0.3/`; historical 0.1 evidence stays
  immutable under `docs/release/0.1/`.
- Kernel and hashing rules: `docs/ast.md`, `spec/serialization.md`,
  `src/canon.ml`.
- Effects and capabilities: `prelude/03-effects.jqd`, `src/check.ml`,
  `src/prelude.ml`.
- Handlers and evaluation: `src/eval.ml`, `test/test_handlers.ml`,
  `test/test_gauntlet_handlers.ml`.
- Host integration contracts: `docs/host-boundary.md` and
  `spec/host-protocol-v0.md`; strict framing, selection, first-order type/value
  codecs, and checked invoke preflight: `src/host_protocol_v0.ml`,
  `test/test_host_protocol_codec.ml`, `test/test_host_boundary_codec.ml`,
  `test/test_host_invoke_preflight.ml`. Serial session actions and terminal
  accounting: `Host_protocol_v0.Session`, `test/test_host_session.ml`, and
  `docs/host-session-v0.md`. The opt-in serial carrier `jac host worker`:
  `src/host_worker.ml`, `test/test_host_worker.ml`, `test/cli/host-worker.t`,
  and `docs/host-worker-v0.md`. The executable conformance kit and its fake
  host: `spec/host-protocol-v0/kit/`, `test/host_kit.ml`,
  `test/test_host_kit.ml`, regenerated with `dune exec test/gen_host_kit.exe`;
  the HB.3 evidence pack is `docs/release/host-boundary/`.
  Existing evaluator capture and host-readiness
  modules are internal seams, not a public ABI; adapters and application
  servers belong outside this repository.
- Program preparation shared by the commands and the host worker (parse,
  resolve, install, read-only check, sealed checked artifact, transactional
  store installation): `src/frontend.mli`, `test/test_frontend.ml`. Internal
  seam, not a public embedding ABI.
- Public-interface identities (API.1): `src/interface.mli` (interface-v1
  manifests: exports with exact identities, name-independent signatures, call
  labels, hidden members; identity, verification, API diff),
  `docs/release/api-identities/DECISION.md`, `test/test_interface.ml`,
  `test/cli/interface.t`. `jacquard interface emit|verify|diff`.
- Evaluation lifetimes (RF.2): `Eval.with_invocation` in `src/eval.mli`
  scopes grants, observers, coverage, and teardown to one evaluation over a
  reusable `Eval.ctx` (Once ownership stays evaluator-lifetime);
  `test/test_invocation.ml`.
- Allocation limits (RT.2): `src/alloc_meter.ml`, `Eval.with_invocation ~alloc`, the alloc-v1
  charging points in `src/eval.ml` (`charge_alloc`), `jacquard run --alloc`, E0921;
  `docs/designs/allocation-limits.md`, `test/test_invocation.ml`, `test/cli/alloc.t`.
- Result propagation (SX.29, D77): `try` block items in `src/surface_parse.ml`,
  `src/surface_lower.ml` (`lower_block`), and `src/surface_print.ml`
  (`try_item`); `test/test_surface_try.ml`, `test/cli/surface-try.t`,
  `demos/request-validation/`.
- Labeled-field accessors, setters and `with` updates (SX.27, SX.28, SX.28b,
  design `docs/designs/everyday-language-ergonomics.md` §5): generation in
  `src/surface_lower.ml` (`generated_accessor`, `generated_setter`); the
  `Ctor(value with label: e)` form in `src/surface_parse.ml`
  (`parse_call_argument_list`), its let-and-match elaboration in
  `src/resolve.ml` (`elaborate_field_update`), printing in
  `src/surface_print.ml` (`pp_field_update`), and the sum-type setter advice in
  `src/check.ml` (`field_update_hint`); `test/test_surface_decls.ml`,
  `test/test_surface_field_update.ml`, `test/cli/surface-field-update.t`.
- Local projects (PKG.1, design `docs/designs/project-structure.md`): the
  `project.jqd` reader and validator `src/project_manifest.mli`, the composing
  frontend `src/project_frontend.mli`, bundles `src/project_bundle.mli` and `src/project_bundle_reader.mli`,
  `jacquard project check|run|test|build|hash|pin|interface|bundle|fmt`;
  `test/test_project_manifest.ml`, `test/test_project_frontend.ml`,
  `test/cli/project-manifest.t`, `test/cli/project-local.t`,
  `test/cli/project-deps.t`, `test/cli/project-bundle.t`, `test/cli/project-guards.t`.
- Behavior review (RW.8): `src/behavior_review.mli` (two checked versions of an
  entry over declared List/Distribution domains, modeled root operations,
  exact-conjunction grouping, request/report format 1), `jacquard review run`,
  `docs/behavior-review.md`, `test/test_behavior_review.ml`, `test/cli/review.t`.
- Exploration recording (EXP.1): `src/exploration_log.ml` (exploration-log-v1
  recorder, encoding and strict parser), `jacquard run --record`, application
  sites on `Value.FAppFn`/`FAppArgs` and `Observation.Operation.site`,
  `Store.retain_source_declarations`; `docs/exploration-log.md`,
  `test/cli/exploration-log.t`, `test/test_exploration_log.ml`.
- Model documents (MODEL.1): `src/model_doc.mli` (jacquard-model-v1 parser,
  validation against the checked source, dependency records and keys),
  `src/model_eval.mli` (evaluation, model-result-v1, the result cache),
  `src/model_history.mli` (history records, snapshots, `model explain`),
  `jacquard model eval|explain`; `docs/designs/model-dependencies.md`,
  `test/test_model_doc.ml`, `test/test_model_eval.ml`, `test/cli/model-eval.t`.
- Dist and inference: `prelude/06-dist.jqd`, `prelude/13-dist-lib.jqd`,
  `src/infer_dist.ml`, `test/test_infer.ml`.
- Warp: `prelude/15-warp.jqd`, `prelude/16-gen.jqd`, `src/warp.ml`,
  `test/cli/warp.t`, `test/cli/props.t`.

## Git Hygiene

- `_opam/` is a local switch and must stay ignored.
- `.scratch/` is repo-local disposable workspace state and must stay ignored.
- `.taskmaster/` is currently ignored in this repo. Task Master data is available locally but will not be committed unless the ignore policy changes.
- Do not rewrite unrelated dirty worktree changes.

## CI/CD Expectations

GitHub Actions mirrors the local definition of done:

- `CI / Development gate` runs build, full tests, clean formatting, version
  smoke, and release-doc presence on PRs, `main`, and `release/**`.
- `CI / Native parity (clang)` and `CI / Native parity (gcc)` run the runtime
  memory, differential, leak, and seeded fuzz evidence.
- `Governance / Governance playground` runs the source-checkout viewer's
  lint, type, unit/accessibility, build, and browser checks.
- `GM12B / GM12B exhaustive forwarding evidence` runs or explicitly carries
  forward the scoped 50,000-case forwarding proof.
- `Release Evidence / Reproduce 0.3 evidence` runs
  `scripts/release/reproduce-0.3.sh` on `release/**`, `jacquard-core-*` tags, and
  manual dispatch, then uploads the evidence transcripts.

Release-facing changes should keep `scripts/release/reproduce-0.3.sh` green and
should not add features outside the release hardening scope.

## Decisions To Preserve

The plan assumes these defaults until the owner decides otherwise:

- D1: SHA-256 via `digestif`, named `HASH_V0`, swappable.
- D2: OCaml native 63-bit int; overflow wraps and is documented.
- D3: UTF-8 text, no normalization.
- D4: seedable splittable PRNG via a `splitmix64` port, seed required in CLI.
- D5: uncurried final call convention.