forked from
anil.recoil.org/monopam-myspace
My aggregated monorepo of OCaml code, automaintained
Add design doc: day10 uses jtw opam for per-package artifacts
Eliminates code duplication between jtw.ml and jtw_gen.ml by having
day10's container script call `jtw opam` instead of reimplementing
artifact generation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+57
+57
docs/plans/2026-02-20-day10-use-jtw-opam-design.md
+57
docs/plans/2026-02-20-day10-use-jtw-opam-design.md
···
1
+
# Design: day10 uses `jtw opam` for per-package artifact generation
2
+
3
+
## Problem
4
+
5
+
`jtw_gen.ml` (day10) reimplements artifact generation logic that already exists in
6
+
`jtw.ml` (the `jtw opam` CLI). When we renamed `findlib_index` to
7
+
`findlib_index.json`, we had to make the same change in both places. Any future
8
+
changes to the artifact format will have the same duplication problem.
9
+
10
+
day10 already installs `jtw` inside its containers (via `jtw_tools.ml`) and runs
11
+
`jtw opam stdlib` to build the base tools layer. But for per-package compilation,
12
+
`jtw_gen.ml` hand-rolls `js_of_ocaml compile` commands and reimplements
13
+
`generate_dynamic_cmis_json` and `generate_findlib_index`.
14
+
15
+
## Design
16
+
17
+
Replace `jtw_container_script` with a call to `jtw opam <pkg> --path <pkg> --no-worker -o /home/opam/jtw-output`.
18
+
19
+
This means `jtw` handles all per-package artifact generation inside the container:
20
+
- `.cmi` copying
21
+
- `.cma` -> `.cma.js` compilation via `js_of_ocaml compile`
22
+
- `dynamic_cmis.json` generation
23
+
- Per-package `findlib_index.json` generation
24
+
25
+
### Delete from `jtw_gen.ml`
26
+
27
+
- `generate_dynamic_cmis_json` (lines 9-40) — `jtw` generates these inside container
28
+
- `jsoo_compile_command` (lines 118-123) — no longer needed
29
+
- Most of `jtw_container_script` body (lines 127-152) — replaced by `jtw opam`
30
+
31
+
### Keep in `jtw_gen.ml`
32
+
33
+
- `generate_findlib_index` (lines 42-50) — still needed for universe-level
34
+
findlib_index.json with `"compiler"` key (distinct from per-package ones)
35
+
- `assemble_jtw_output` including `rewrite_dcs_urls` — still needed to copy from
36
+
layers into content-hashed paths and rewrite `dynamic_cmis.json` URLs
37
+
- All content hashing, layer management, layer metadata
38
+
39
+
### No changes needed
40
+
41
+
- `jtw_tools.ml` — already calls `jtw opam stdlib`, unchanged
42
+
- `jtw opam` CLI — already has `--path` and `--no-worker` flags
43
+
- `findlibish.ml` (reader side) — unchanged
44
+
- `assemble_jtw_output` URL rewriting — day10-specific concern, stays
45
+
46
+
### `rewrite_dcs_urls` duplication
47
+
48
+
`assemble_jtw_output` still reimplements `dynamic_cmis.json` generation in
49
+
`rewrite_dcs_urls`. This is acceptable because it's specifically rewriting URLs
50
+
after copying to content-hashed paths — a day10-only concern. The JSON schema
51
+
is trivial (`dcs_url`, `dcs_toplevel_modules`, `dcs_file_prefixes`) and unlikely
52
+
to change independently of the URL rewriting logic.
53
+
54
+
## Risk
55
+
56
+
The `jtw` binary inside the container must match the repo. This is already
57
+
guaranteed — `jtw_tools.ml` pins `js_top_worker-bin` from the same repo/branch.