Reference implementation behavior

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

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 prompts the user and asks for confirmation before running a program.