Reference implementation behavior

Behavior that is specific to dk0 and may differ in other implementations.

Workspace directories

dk0 keeps its durable workspace configuration under etc/dk/ (transient build state lives under t/; see the Configuration and Security options for the t/d, t/c and t/k defaults). The etc/dk/ directories are:

Directory	Contents	Written by	Read for
etc/dk/d	Prepared distribution keys: <MAJOR.MINOR>.<PATCH>.dist.json files carrying the producer public key and signed continuations for the version lines this workspace releases. Author-owned; commit them.	prepare-version	distribute and combine (signing); every import (the keys are locally prepared trust anchors).
etc/dk/i	The import directory: verified release <LIBRARY>.<VERSION>.values.json files, plus the values.unattested.json download scratch file. On the workspace include path, so the imported distributions resolve values and traces. The files double as prior-import trust anchors. Machine-managed: update garbage-collects entries its resolution no longer uses, and an import prunes the strictly older releases it supersedes on the same MAJOR.MINOR line.	add, import, restore, and workspace import declarations	distribution resolution; prior-import trust anchoring.
etc/dk/t	Consumer trust records. Three kinds: (1) byte-identical copies of directly imported release values files (<LIBRARY>.<VERSION>.values.json), recorded only after the consumer trust checks pass; (2) imports.json, the machine-written import ledger. Each entry records a values_sha256 (SHA-256 of the dos2unix-ed content) that an import/restore verification accepted, its kind (record for the imported values.json file, or scriptmodule for an exported values.lua whose hash the producer signed into build_to_sign.build_script_module_sha256s), and the distribution's producer pubkey_base64. A rule whose run-time content SHA matches a keyed entry is attributed to that producer; (3) capabilities.json, the human-authorized request.ui capability grants (run, write) keyed by producer public key (pubkey_base64) or by local values content (values_sha256). A .gitignore written by dk0 keeps the machine-written records (1) and (2) out of git while leaving capabilities.json committable so a repository can carry its grants into CI. Deliberately not an include directory, so no values or traces are ever resolved from a record; a record only anchors the producer key and rotation of later imports, gates producer-key grants (ledger), or carries grants.	import local (record copies); every import/restore (ledger); trust grant and the capability prompt's [a]lways answer (grants)	prior-import trust anchoring; producer-key grant activation (ledger); request.ui capability decisions (grants).
etc/dk/v	Authored values files (*.values.jsonc, *.values.lua) belonging to the workspace. On the workspace include path. distribute seals them into the distribution manifest together with the workspace script and dist/*.u.	the workspace author	distribution resolution; manifest sealing.

Lua interpreter

dk0 uses a pure-OCaml version of Lua (lua-ml), which is fully type-safe, re-entrant, and can have Lua evaluations bounded in time and sandboxed to the project directories. The internal table of packages is stored in an OCaml analog of the Lua C registry.

• Lua scripts should minimize the use of global variables. dk0 does not yet enforce the complete removal of global variables, but it will in the future.
• bug: string.len( "a\000bc000" ) is 9 in dk0 (https://github.com/diskuv/dk/issues/54).

Limits and platform quirks

• A few internal buffers are bounded by dk0's Sys.max_string_length limit on 32-bit systems.
• The byte positions, lines and columns embedded in the AST for error reporting are Unix byte positions. On Windows the byte positions may be inaccurate if the JSON file is checked out by git with CRLF endings; this may be fixed if dk0 moves exclusively to lines and columns.
• dk0 only recognizes the OSFamily property (as of 2025-11-09).
• The execution_abi wildcard defaults to the ABI of this build executable; it can be set by dk0 (see --execution-abi).

Change detection

The Specification does not mandate how change detection is implemented. dk0 scans all the globs at startup, with optimizations to skip directories it can prove will never match a glob. Invalidation can be forced with the --invalidate TARGET global option.

Assets and the library cell

When a unified.asset declaration runs, the origin is named after the library id and its mirrors are set to the library cell. In dk0:

• when run with a directory-based unified script (e.g. dk0 test unifiedscript.u/), the library cell is set to the unified-script directory while the script is evaluated
• when the unified script being evaluated is the workspace script, the library cell is set to the directory containing the workspace script
• the dk0 combine command can adjust the mirrors permanently during distribution.

In the workspace, asset libraries are implicitly trusted, so no --trust-local-package ASSET_LIBRARY is needed to access the workspace assets.

Note

dk0 reference implementation behavior

In the workspace script, if the existing output block has a size and checksum then the asset's size and checksum won't be recomputed. The workspace script is re-evaluated only when the update command is issued.

The precise behavior depends on which unified script the unified.asset declaration is in and how it was reached:

When unified.asset runs in...	What happens
A unified test or distribution script that is not the workspace script	The asset's file or directory contents are always read to calculate its size and checksum.
The workspace script	If the existing output block under the asset's command already contains size and checksum, those values are reused. Otherwise the asset is always read to recompute them.
An update-style command refreshing the workspace script	The asset is always read to recompute the size and checksum.

Distributions

• dk0 add places distribution metadata in the source tree at <workspace>/etc/dk/i/<LIBRARY>-<VERSION>.values.json.
• dk0 add places lazy value files in the value store by default, to avoid the time and space to download every binary artifact from a distribution.
• dk0 add downloads an internal copy of the GitHub CLI and uses it to download from GitHub releases and validate attestations.
• dk0 accepts only the JSON request derived from command-line name-values. There is no ability today to accept the form document directly from an HTML form (per the W3C HTML JSON Forms specification) or a JSON document.

Values

• A values.lua file added to the valuestore is an in-memory file in dk0.

Other behavior

• Before submitting work, dk0 prints the resolved inner argument vector (it can pass the exact argument vector to a subshell/remote engine).
• dk0 asks for confirmation before a rule runs a program or writes a file, unless a matching capability grant is recorded (dk0 trust grant or a prior [a]lways answer; see Security).