Run one rule of the CommonsLang_OCaml.Dk.OpamLock scriptmodule so its author-time OpamLock uirule ships in this distribution. Running any rule of a scriptmodule brings in the whole scriptmodule; the marker output is otherwise unused. The value-id is harvested from the first CI run (the DkML pattern).
The scriptmodule carries the uirules a maintainer runs to lock, adopt, and regenerate an opam and dune project: Solve, Adopt, Refresh, OpamVenv, the three Generate rules (GenerateSrc, GenerateDriver, GenerateFinal), and GenerateForms. Each rule declares in M.uirule_capabilities the capabilities it may request: Solve, Adopt, Refresh, and OpamVenv request run and write, and the Generate rules and GenerateForms request write. An engine at 2.4.2.339 or later enforces that manifest as an upper bound and lists every declared capability in its trust prompts and suggested trust grant commands, so a consumer grants a rule's full need in one command.
Adopt carries a first-time adoption end to end: it seeds the pin table, solves, generates the forms, and registers the dk.u assets. It re-solves with --with-test, since the canonical adoption lock is the with-test lock (wtest=f opts out), forwards wdoc=, and takes reuse_lock=t to keep an existing committed lock and regenerate only the build forms. GenerateDriver derives its nine arguments from one pkg=MODULE@VERSION: the formid, pkgpath, version, localsrc, and out path from that token, the roots from the lock's stamped generated.roots, and the rulefn from the CommonsLang_OCaml import. GenerateSrc and GenerateFinal generate the localized-source and thin final forms, GenerateForms runs the fixed trio (Src, driver, Final) from one pkg=, and building the emitted forms requires dk 2.4.2.342 or later.
GenerateSrc emits the assembled tree's dune-workspace root marker: the project's own file, or a minimal (lang dune <X>) that Adopt synthesizes into the dk-owned dk-src/ directory and registers. The marker lets a warm run-object of the final executable read its traces from cache. Adopt forwards its derived root to the form generators, so the reuse_lock=t path works against a minimal-stamp lock whose generated.roots is unrecorded.
The generators emit deterministic archives through the engine's in-process --zip special form: GenerateSrc's localized-source form and GenerateDriver's mergedprefix driver archive produce the same bytes on every platform from the same inputs, and the emitted Src form carries no S7z dependency.
GenerateDriver keys its emission off the rulefn family. An F_BuildLockedClosure rulefn, the default when the import declares one, emits one run-function precommand carrying the whole parameter set, and the closure rule re-derives the per-package plan from the lock at build time. An F_BuildLockedPackage rulefn emits the per-package lines. Import resolution runs at author time, so the emitted line carries resolved impdep_ ids, and it keeps a literal ocaml= token that OpamVenv reads off the raw driver text.
Parallel scheduling is the default; sequential=t opts out, and Refresh injects sequential=t when it replays a driver that stamped neither, so an older driver stays byte-stable. Every stamped tool id and printed message derives from M.id, and in-module cross-calls dispatch through version-unique function bindings (H.Solve, H.GenerateDriver, and the rest).
The generated driver values.jsonc is a committed, on-disk artifact that GenerateDriver and Adopt write, so it costs the maintainer zero typed characters. Its generated stamp powers Refresh mode=check and the CI refresh-check gate, both of which read the on-disk driver; it sits on the include path at scan time, so a fresh clone builds offline before any generator runs; and its formid is a published contract that the thin form and dist/*.u reference by name (Closure@VER). Under the closure shape the driver is one run-function line, so a reviewer reads the build plan as the committed lock plus the closure rule.
How the lock is produced: the OpamLock.Solve uirule launches opam to solve the dependency closure. It runs opam list --resolve to compute the closure and opam show to read each package's version, source, dependencies, and build commands, and never runs opam install. opam has no switch-less solve, since the solver needs a switch's repositories, pins, and os/arch variables, so Solve creates an empty opam switch purely as a throwaway resolution context: it adds the pinned repositories, applies the version pins from dk-opam-pins.txt, path-pins the local packages, then resolves. That switch is an ephemeral local switch in the rule's sandbox, unique per run so no cross-project or cross-run pin leaks into the lock, and the rule removes it once the solve finishes; nothing is installed into it.
The solve universe is hermetic. The opam-lock helper (Apparatus.OpamLockHelper) registers each pin-table repository under a URL-derived dk-owned name and selects only those names for the ephemeral switch, so a pre-existing repository in the machine's opam root stays out of the solve universe. The helper recreates the ephemeral switch on every solve, embeds the work directory in the constraints repository name so concurrent solves sharing one root leave each other's universe intact, and verifies every pin visible in the universe before solving, failing with a message that names the repository that should contain it. Solve passes --with-doc to opam when wdoc is set and stamps wdoc into the lock's generated block, so a with-doc lock carries odoc, the package dune build @doc needs.
Resolving ocaml 5.1.1 as the solve compiler
ocaml is left unpinned so the solve resolves it from the pinned repository commit to 5.1.1, one of the first releases with the corrected ocaml-env, host-arch and conf-mingw-w64 selectors (pinning ocaml in the shared pin table would break the CI build's DkML toolchain). The pinned commit makes that resolution deterministic, and the version is a solve artifact only: the DkML 4.14.3 toolchain ocaml replaces it at build time.
- ocaml 5.1.1 carries the corrected ocaml-env, host-arch and conf-mingw-w64 selectors, so the solved closure resolves the right platform packages for every slot.
- The resolved ocaml version drives per-slot mingw selection: 5.1.1 resolves the Windows_x86 slot to the 32-bit ocaml-env-mingw32 toolchain.
- The DkML 4.14.3 toolchain ocaml replaces this solve compiler at build time, so the lock's ocaml and ocaml-base-compiler entries record only the solve.
Relocatable ocamlfind and ocamlbuild
The solver still resolves ocamlfind and ocamlbuild (so the rest of the closure resolves and both still satisfy their dependents at the resolved version), but when the helper emits these two entries it substitutes a fixed relocatable specification for the solved source and build commands. A stock findlib bakes an absolute stdlib path into topfind and findlib.conf, and a stock ocamlbuild bakes an absolute libdir. Those absolute paths are valid only in the build tree that produced them, so a prebuilt CommonsBase_Dk.Dk0.Pkg.Ocamlfind or Pkg.Ocamlbuild object is unusable once imported into a different build tree (the imported #use "topfind" loads a dead #directory). The relocatable builds write paths relative to the tool's own location, so the imported objects stay usable across build trees.
- ocamlfind is pinned to dra27's relocatable fork (v1.9.8) and built with
-sitelib ".", so findlib writes a relative topfind and findlib.conf. - ocamlbuild is pinned to dra27's relocatable-0.14.3 fork (0.14.3 plus the relocatable patch) and built through
configure.make with OCAMLBUILD_LIBDIR=.., so ocamlbuild computes its libdir at runtime. - Both sources are addressed by git commit, so the pin does not move. The substitution is a property of the lock the helper writes; downstream projects do not list these packages in their
dk-opam-pins.txt. - The DkML
4.14.3+relocatable toolchain supplies the runtime support the two forks rely on (standard_library_relative, -set-runtime-default), so no compiler change is needed.
ocamlfind and ocamlbuild are host tools: their built artifacts are native executables that run on the build host during every later package build (topkg's ocaml pkg/pkg.ml build invokes ocamlfind and ocamlbuild). They are dual-role: the build runs them, and their findlib metadata (stdlib path, ocamlmklib and ocamlc config, arch flags) flows into every later package build. GenerateDriver emits targetabi=Release.target_abi for these two by default, so on a cross slot whose host can emulate the target (Windows_x86 under WOW64, Darwin_x86_64 under Rosetta, Linux_x86 under multilib) the metadata matches the target and the tool still runs. This is the dual-role convention in SPECIFICATION "Object Slot ABI".
The hosttoolabi=SLOT parameter restores Release.execution_abi for a matrix that contains a cross slot the host cannot emulate. Building a host tool at the target ABI there produces a binary the host cannot run: on Release.Linux_x86_64_musl the tool links against the target musl toolchain and becomes a musl-dynamic executable, and the glibc host that runs it during the build lacks the musl loader. The opam-build form is host-keyed and carries the Release.target_abi wildcard in its value-id, so a single such build is stored under one key and shared to every slot, including the glibc Release.Linux_x86_64 one, where the tool then fails to exec. A consumer whose matrix includes such a slot passes hosttoolabi=Release.execution_abi to keep the host tools host-native, guarding that musl hazard.
Refresh: self-describing regeneration
The lock and the driver stamp their inputs, and the Refresh uirule reads those stamps back. Solve records roots and pins (and wtest and local_opam_dir when set) in the lock's generated block, and GenerateDriver records its full parameter set in a top-level generated member of the driver values.jsonc, right after schema_version. MlFront's value reader pulls members by name and ignores an unknown top-level member, so the stamp needs no dk-value schema change. A consumer regenerates from the stamp rather than re-copying the roughly ten parameters, and CI detects a stale driver in seconds.
Refresh has four modes. Default (driver) regenerates the driver from the existing lock using the stamped parameters, so a routine repin never silently changes solved package versions; when the lock is not checked in (a consume-from-archive consumer), it substitutes the target rulefn in place, which equals a full regeneration for a rule-version-only move. mode=solve fetches opam hermetically, re-solves the lock from its stamped roots and pins, then regenerates. mode=check is read-only: it compares each driver's stamped rulefn and tool against the newest the imported etc/dk/i/CommonsLang_OCaml.<ver>.values.json declares (and, when the lock is checked in, the stamped lock-sha256 against the lock on disk), prints the exact fix command, and exits nonzero when stale. version=NEW rewrites the coupled version, formid, and localsrc and regenerates.
An unstamped driver carries no stamp; the first driver-mode Refresh recovers its parameters from the generated text and emits the stamped form. mode=check on an unstamped driver recovers the rulefn, fails when that rulefn is stale, and otherwise prints an "unstamped: run Refresh once to adopt" advisory and exits zero, so CI adoption stays graceful. The rules are co-versioned: a Refresh rule bakes in its sibling Solve, GenerateDriver, and OpamVenv at the same version and, absent an explicit rulefn=, prefers the newest F_BuildLockedClosure the import declares (falling back to F_BuildLockedPackage); rulefn= remains an explicit override.
OpamVenv: a native dune inner loop
dk's incremental unit is the whole package object: editing one source file and rebuilding re-stages the localized-source object and rebuilds the entire leaf package in a fresh hermetic sandbox, which takes minutes even with every dependency cached. The OpamVenv uirule hands the inner loop to dune. It reuses a GenerateDriver mergedprefix=t skiplocal=t driver, whose whole non-local dependency closure merges into one cached prefix.zip object, and stages that prefix, the DkML compiler, and dune into the project's opam-venv/ directory, so source opam-venv/env.sh && dune build -w recompiles only the edited module and its dependents.
OpamVenv discovers the dev-prefix driver (the sole one whose stamp carries mergedprefix=t, or an explicit driver=), reads its stamp for the formid, lock, and lock-sha256, and refuses to run when the lock on disk no longer matches that stamp (pointing at the Refresh fix command). It get-objects the prefix for the requested slot= (default: the host execution ABI), rewrites the staged prefix to be relocatable (the @OPAM_IP@ dune-package sentinel and findlib.conf), and writes env.sh/env.ps1/env.cmd activators plus a dk-opam-venv.json stamp. A re-run is a no-op when that stamp still matches (force=t overrides); after a lock change, Refresh regenerates the dev-prefix driver and the next OpamVenv re-materializes.
A caller can also skip the driver: formid=ID@VER names the merged-prefix form to get-object directly, so a project whose merged prefix is a released object (a released with-test closure form, for one) needs no dev-prefix driver of its own, and lock=PATH names the lock that prefix was solved from so the stamp records its sha256 and a lock edit forces a rebuild. The stamp also records the formid, and the up-to-date check compares it, so a new closure version is never mistaken for the old one.
The activators also carry the project's declared environment modifications. A committed dk-opam-venv.envmods beside dk.u (or envmods=PATH) holds one modification per line in the specification's grammar (+NAME=VALUE, <NAME=VALUE, -NAME; # comments; ${PREFIX} and ${DKML} stand for the staged prefix and compiler), planned by the engine's envmod library so the ordering and dedupe are the engine's. Each of env.ps1, env.cmd and env.sh renders the same plan after its toolchain block: a prepend adds no separator when the variable is empty in all three, a removal is Remove-Item, unset or cmd's set "NAME=", and the stamp records the file and its sha256 so an edit re-materializes. A project with no such file gets the same activators as before.
The opam venv is additive and host-only: opam-venv/ and dune's _build/ are invisible to git and to dune. dk0 drops a self-ignoring .gitignore ("*") and a dune ("(dirs)") into its t/ store, and the OpamVenv dialog does the same for opam-venv/, so a host dune build never scans them and the reproducible run-object release build is unchanged. It resolves to the same dependency versions and the same DkML compiler the release build uses, driven from the same lock.
An activated venv does not reproduce everything the release gate stages, and the gap is a debt ledger rather than a waiver: the maintainer requires parity for every venv use case, so each item below is a thing to close, and an item a later module bump fixes leaves this list. What the venv does not reproduce today, grouped as the gate sees it:
- Test toggles the gate sets and the venv leaves to the host or a committed
dk-opam-venv.envmods: ENABLE_NETWORK_TESTS, ENABLE_ZIPBOMB_TESTS, OCAMLRUNPARAM=b, MLFRONT_STUBS_BUILD_TYPE, FLEXLINKFLAGS, and the dksdk-coder stublib PATH prepend. MLFRONT_GATE and the DK_SBOM_* keys agree (both unset). - MSVC capture on
Windows_*: the INCLUDE, LIB and LIBPATH values and the vcvarsall architecture. env.ps1 captures them only when cl.exe is absent and hardcodes x64 whatever the slot= is, so a Windows_x86 venv does not get the x86 mapping from assets/table/msvc-arch/Release.<slot>; env.cmd and env.sh capture nothing and print a note. The gate also derives OCAMLFIND_LDCONF, CAML_LD_LIBRARY_PATH and OCAMLLIB at run time and copies the ocaml*.opt executables on Windows, neither of which the venv reproduces. - Host tools that switch tests on or off rather than fail them:
sh on PATH (the gate stages MSYS2), node, gh and zig. - Network access and the GitHub credential the gate serves through
GH_TOKEN; a committed envmods file must never carry that secret. - Host platform the gate pins: the Linux glibc floor and assembler, the
Linux_x86 32-bit userland, the Darwin Command Line Tools clang, the Windows MAX_PATH junction, and a Visual Studio install carrying the VC.Tools.x86.x64 component.
The localized source, the gate's dev-then-release test sequence and its -j 1, the zero-test refusal, and the CommonsLang_OCaml pin-alignment guard are gate mechanics rather than environment, so the venv does not carry them.