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). dk0 drops a self-ignoring .gitignore (*) into t/ and each of its build directories, so a project keeps its t/ tree out of git without a hand-written /t/ line. 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-written but committable, so a clone can carry them for clone-and-build (see "Committing imports for clone-and-build repositories"); 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. Four 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); (4) acceptances.json, the durable dk0 trust accept records keyed by package name, each carrying an optional pinned producer key and optional pending capabilities that become grants at the first successful import. A .gitignore written by dk0 keeps the machine-written records (1) and (2) out of git while leaving capabilities.json and acceptances.json committable so a repository can carry its trust decisions 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), carries grants, or carries acceptances.	import local (record copies); every import/restore (ledger, and acceptance resolution); trust grant and the capability prompt's [a]lways answer (grants); trust accept (acceptances)	prior-import trust anchoring; producer-key grant activation (ledger); request.ui capability decisions (grants); import-time key acceptance (acceptances).
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

An implementation chooses how it detects changes to the globbed files. 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.

Reading an asset index

dk0 loads the index file for an asset once per command and gives every later request in that command that same index.

dk0 keys that index on (values_file_sha256, form, index-asset-key):

• values_file_sha256 is the SHA256 of the values file (V256) that declares the asset, as the specification defines it.
• form is the value type letter of that values file, j for a values.json file and l for a values.lua file.
• index-asset-key is the key of the index asset.

Under that key dk0 stores four things in memory: the i value id, that value's SHA-256, the index file the value id names, and the dependency fetches the first load made. dk0 stores that entry after the load finishes. A load that reports pending stores nothing, and the requesting task asks again when it runs again. dk0 frees the entry when the command ends.

dk0 still re-runs the cheap dependency fetch, so the calling task's recorded trace is identical to what it would have been without the memo. Before dk0 gives a task an index it loaded earlier in the command, it fetches for that task the same dependencies the first load fetched, in the same order.

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 block is the \dk.asset(byteSize: "...", checksum: (sha256: "...")) metadata markup; the legacy three Lua value lines ('asset', size, checksum) that predate the markup are still read so already-published packages keep working, and update rewrites them to the markup. 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).