Run blueprint§

Align an automation compiler§

blueprint compiler-version prints one release tag and a newline, with no labels or colour. It reports this binary’s pinned compiler even when ROC or PATH selects another executable. It works offline without a project, configuration evaluation, compiler installation or cache writes. Native smoke tests run the actual bundled roc version and require it to match this tag on every released system.

A CI check or commit hook can compare an installed automation compiler:

test "$(roc-stable version)" = \
  "Roc compiler version $(blueprint compiler-version)"

A project can also compare its committed compiler pin with the reported tag before installing tools. Keep upgrades explicit: align that pin when the project’s automation is ready for the new compiler.

When a project fetches the same nightly with Recipes.roc_nightly, it can reuse the compiler archive Blueprint installed in its store. Matching tags does not make an independently installed roc-stable, such as a Nix package, reuse Blueprint’s cached executable.

Use an environment from another program§

blueprint env NAME describes the shell NAME as data instead of entering it: the directory of fetched programs the core puts first on PATH, and what the provider’s shell would export, obtained by asking the provider for its shell as data (Nix answers with nix print-dev-env). Nothing runs in the environment. The directory of programs is kept at .blueprint/env/NAME/bin, rebuilt on every call, so what was printed stays valid until the next blueprint update.

eval "$(blueprint env dev)"              # this shell
blueprint env dev --github-path >> "$GITHUB_PATH"
blueprint env dev --github-env >> "$GITHUB_ENV"
blueprint env dev --json                 # for an editor or agent

The shell rendering single-quotes every value and prepends to the caller’s own PATH. The JSON report has format 1, path entries { directory, origin } first on the search path first, and variables { name, value, origin }; origin names what supplies each, such as blueprint for fetched programs or nix. A provider’s shell variables that describe its own process, such as HOME and PWD, are not exported.

What a run does, in order§

blueprint run, shell, workflow and build share the following validation and execution boundary:

1. Read Blueprint.roc with the Roc compiler, and refuse what the configuration alone rules out, such as a task that does not exist or a program its recipe says is unavailable on this system.

2. Read Blueprint.lock and require that it matches Blueprint.roc.

3. Plan every step of the request. All problems are reported together: a program the lock does not hold, one whose URLs changed, a build this machine cannot run.

4. Look on PATH for every program the steps need of the machine: the tools their environments Expect, and nix when a step has a tool from a Nix source or is a build. Everything missing is named in one message.

5. Make every fetched program ready in the store, downloading what is not there and checking each against the lock.

6. Run the steps. Each gets its Roc packages published and its fetched programs first on PATH.

Nothing is downloaded, generated or run for a request that fails an earlier check. Work without a provider describes the store and the PATH of a step.

What each command validates§

Provider capability checks follow the requested environment closure; unrelated valid provider declarations do not block selected operations. Whole-project structural validation and required-feature checks still apply. Full rendering (gen, update, check, flake) checks every shell, task and build environment that Nix builds; one with no tool from a Nix source is entered without Nix and is left out of the flake.

The lock and generated files§

• Commit Blueprint.roc and the authority (default Blueprint.lock, a versioned S-expression listing each fetched program with its digest and each pinned source with its revision and digest); generated state (default .blueprint/) is not committed: blueprint writes a .gitignore there that ignores everything in it.

• Normal gen, shell, run, build and workflow require a lock that matches Blueprint.roc and never rewrite it. A lock that does not match says what changed, and one in a format this blueprint does not read is refused; both name blueprint update.

• A fetched program is stale by itself. When its URLs in Blueprint.roc are not those in the lock, only requests that use it fail, and blueprint update <name> resolves it alone.

• nix develop takes the bash it runs a shell or task with from a flake input named nixpkgs, so the generated flake gives that name to the first Nix package source declared and that bash is pinned by Blueprint.lock like every tool, unless the project declares an input named nixpkgs itself.

What tasks need§

blueprint requirements reads Blueprint.roc and nothing else: not PATH, not the store and not Blueprint.lock. It answers before anything is installed or resolved, and gives the same answer on every machine. The system is BLUEPRINT_TARGET, or the one it runs on.

$ blueprint requirements
system x86_64-linux
providers: nix
task check [dev]: programs roc-stable; expects gh, git; roc packages 2
task host [zig]: provider nix (nix#zigpkgs."0.16.0"); programs roc-stable; expects gh, git; roc packages 2

With --json the report is one JSON object for a program to read:

{"format":1,"system":"x86_64-linux","providers":["nix"],"expects":["gh","git"],"tasks":[
 {"name":"check","environment":"dev","providers":[],"tools":[],"programs":["roc-stable"],"unavailable":[],"expects":["gh","git"],"roc_packages":2},
 {"name":"host","environment":"zig","providers":["nix"],"tools":["nix#zigpkgs.\"0.16.0\""],"programs":["roc-stable"],"unavailable":[],"expects":["gh","git"],"roc_packages":2}]}

A task that is not declared is an error, and nothing is printed for the others. To install Nix only where it is needed, test whether providers holds "nix" for the tasks a job runs:

blueprint requirements --json check | jq -e '.providers | index("nix")'

Inspect committed pins§

blueprint lock show reads only Blueprint.lock. It does not evaluate Blueprint.roc, check freshness against declarations, invoke Roc or Nix, access the network, or write generated files or caches. BLUEPRINT_ROOT and BLUEPRINT_LOCK select the project directory and lock path as usual; other workspace, target and compiler settings have no effect. It reports committed authority even when a working configuration has changed. Run blueprint gen when you need the ordinary freshness checks.

The stable S-expression lock remains the authority and is directly readable through core.Lock. The optional JSON projection gives Python, jq, Nix and other consumers public provider-qualified identities, digest kinds and native metadata without decoding private provider hints. See Choose the authority or its public projection for when to use each interface and the projection’s compatibility boundary.

Names select package sources, inputs, overlays, build sources, or fetched programs. With no names, every entry is included. A program name selects all its systems. Unknown names, unreadable locks, unsupported lock major versions and inconsistent provider pins fail with nonzero status and no report on stdout. Diagnostics go to stderr. Output order follows the lock; use the per-entry identity when fingerprinting a dependency, rather than the output bytes or whole lock.

--json emits one JSON object followed by a newline. Its format is 2, independent of the lock’s own format. Every field listed here is present; a change a reader of format 2 could misread gets another number. Readers should check format, accept extra fields and treat ordering as insignificant.

{
  "format": 2,
  "sources": {
    "nix": {
      "name": "nix",
      "provider": "nix",
      "ref": "github:NixOS/nixpkgs/nixos-unstable",
      "rev": "4975466d324710c576dc11ad614684e6bd8cad8e",
      "digest": "sha256:c49f97e2106d39c00518139ee6700cc8c51e17d7e82419883aedcd8c1a81c9c5",
      "digestKind": "tree",
      "flatSha256": null,
      "content_identity": "sha256:c49f97e2106d39c00518139ee6700cc8c51e17d7e82419883aedcd8c1a81c9c5",
      "metadata": {
        "nix": {
          "fetchTree": {
            "type": "github",
            "owner": "NixOS",
            "repo": "nixpkgs",
            "rev": "4975466d324710c576dc11ad614684e6bd8cad8e",
            "narHash": "sha256-xJ+X4hBtOcAFGBOe5nAMyMUeF9foJBmIOu3NjBqBycU=",
            "lastModified": 1790185690
          }
        }
      }
    }
  },
  "fetched": []
}

An external producer can save a named pin without parsing Blueprint’s lock:

blueprint lock show --json nix > locked-input.json

A Nix expression can consume that JSON directly:

let
  locked = builtins.fromJSON (builtins.readFile ./locked-input.json);
  pin = assert locked.format == 2; locked.sources.nix;
  nixpkgs = builtins.fetchTree pin.metadata.nix.fetchTree;
in import nixpkgs.outPath { }

The inspector itself is offline; evaluating builtins.fetchTree may fetch the source if Nix does not already have it. Use sources.nix.content_identity as the producer’s input fingerprint so an unrelated roc-stable update does not invalidate the producer’s artifacts.

Verify the store§

Every use of a fetched program checks the store of downloads first: its archive is hashed again and compared with the SHA-256 it is named by, and its tree is hashed again and compared with the record written beside it when it was unpacked. An archive that differs is downloaded again, and a tree that differs is made again from its archive. That check guarantees a tree is what its record says. It cannot see a tree and its record changed together, so that they agree: nothing in it compares the tree with what its archive unpacks to.

blueprint store verify makes that comparison, at the cost of unpacking every archive again. It hashes each archive in the store; for each tree with a record, it unpacks the archive afresh into a scratch directory beside the trees, never inside one, compares the tree and its record with that extraction, and removes the scratch directory. It reads the store and nothing else: not Blueprint.roc, the lock, a compiler or the network. It changes nothing.

$ blueprint store verify
intact /home/me/.cache/blueprint/v1/artifacts/sha256/<a>
tree differs /home/me/.cache/blueprint/v1/trees/sha256/<a>.tar.gz: it and its record agree, but it holds sha256:<x>, and its archive unpacks to sha256:<y>
intact /home/me/.cache/blueprint/v1/artifacts/sha256/<b>
intact /home/me/.cache/blueprint/v1/trees/sha256/<b>.file
store /home/me/.cache/blueprint: 4 checked, 3 intact, 1 tree differs
blueprint: the store is not intact; `blueprint store verify --repair` makes what differs again from its archive

Each archive is followed by its trees, in the order of their digests. A finding is intact; archive damaged, when an archive is not its SHA-256; tree differs or record differs, from the fresh extraction; no record, for a tree with none; or no archive, for a tree whose archive is missing or damaged, which nothing can verify without a download. The status is 0 when every finding is intact, and 1 otherwise.

--repair then makes the store what it should be, and prints a repaired line for each change. A tree that differs, or has no record, is replaced by its fresh extraction, with a record; a record that differs is written again. A damaged archive is removed, and so is a tree with no archive, for the next use to download the archive and make the tree from it. Nothing is downloaded, and the status still says what was found: run verify again to see a clean store.

--json prints one JSON object for a program to read: format 1, store, findings as { item, verdict, detail } with verdict one of intact, archive_damaged, tree_differs, record_differs, no_record and no_archive, counts of each verdict, and repaired as { item, action }. The JSON is presentation: the records in the store remain S-expressions.

What update needs and records§

blueprint update is the command that explicitly selects dependency pins. It writes the whole lock or nothing.

Pure Roc consumers can import the official core.LockSnapshot module from this release’s existing core bundle. See Consume lock inspection in pure Roc for typed parsing, lookups, metadata and the offline schema/profile.

Without Nix, and with it§

blueprint update starts Nix only when Blueprint.roc declares something Nix resolves: a Nix package source, an input or overlay, or a build source, including the bundle of a Roc package that a build uses. It looks for nix before doing anything else and says why it needs it:

blueprint: this machine lacks what blueprint update needs, and blueprint installs none of it:
  nix: Blueprint.roc declares the Nix source nix, which Nix resolves

A project that declares none of these is updated with no Nix on the machine. In a project that does, the pins Nix resolves and the digests of fetched programs share the one lock, and blueprint update PROGRAM..., naming fetched programs alone, asks Nix for nothing: it needs a lock that is already current for everything else. A name that is neither an input nor a program is an error that lists both kinds.

The digests of fetched programs§

For each fetched program and each declared system, the lock holds the URLs the program is declared with, the SHA-256 and the length of the download, and how the digest was obtained:

A reviewer of a lock change reads these: Computed alone rests on the one download blueprint update made, and Published on what the publisher’s release says.

An entry whose URLs are unchanged is kept, and nothing is asked or downloaded for it; a program named on the command line is resolved again regardless. Otherwise the download for the system the update runs on is fetched and hashed, and is kept in the store for the run that follows. A program that is the very download blueprint fetched as its own compiler, as a Recipes.roc_nightly of that nightly is, is hashed from the store and not fetched a second time.

When the first URL is a GitHub release asset, https://github.com/<owner>/<repo>/releases/download/<tag>/<asset>, the release is asked once what it publishes. A digest computed here that differs from the published one stops the update, and nothing is written. For another system the published digest is recorded and nothing is downloaded; an asset with no published digest, or a URL that is not a release asset, is downloaded and hashed instead.

When the release cannot be asked§

The question to GitHub carries no token, and GitHub answers 60 such requests an hour from one address. A question that is refused, that cannot be put, or whose answer does not describe a release does not stop the update: blueprint update says so once for the release, downloads and hashes that release’s assets for every system, and records each as Computed. A digest that is published and differs from the computed one always stops it. A run never asks GitHub anything.

blueprint: could not ask for the digests roc-lang/nightlies publishes for its release nightly-2026-10-28-bad769b: HTTP 403 from https://api.github.com/repos/roc-lang/nightlies/releases/tags/nightly-2026-10-28-bad769b (1 attempt). GitHub answers 60 such requests an hour from one address when no token is sent, and blueprint sends none. The digests of its downloads are computed by downloading each of them instead, and Blueprint.lock records them as computed

Such an update downloads the program for every declared system, where one that is answered downloads it for this machine alone.

New download hosts§

For each download it hashed, the lock records the hosts that served the bytes, after any redirect, beside the URLs Blueprint.roc declares. Before it writes the lock, blueprint update prints every download host the new lock names and the lock before it did not, one to a line, and says whether a URL in Blueprint.roc declares it or a redirect led there:

Blueprint.lock will name download hosts it did not name before:
  github.com, declared in Blueprint.roc
  release-assets.githubusercontent.com, reached by a redirect

It prints nothing when there is none. A new host in a lock update is worth a reviewer’s look, and one reached by a redirect is named by no line of Blueprint.roc. The list comes before the lock is written, so an update that then fails to write it has still said what it would have named.

Environment variables§

• BLUEPRINT_ROOT names the directory containing Blueprint.roc (default: the current directory).

• BLUEPRINT_WORKSPACE, BLUEPRINT_GENERATED_ROOT, BLUEPRINT_LOCK choose caller paths; relative values resolve against the selected project root, not the invocation directory. Out-of-tree generated roots are supported.

• BLUEPRINT_TARGET selects the declared execution system (default: this machine’s System), not a separate artifact target.

• ROC selects the compiler that reads Blueprint.roc, which must be the nightly blueprint was built for; unset, a matching roc on PATH is used, or the nightly is downloaded into the store.

• XDG_CACHE_HOME names the directory that holds the store of downloads, blueprint/, and Roc’s package cache, roc/packages (default: .cache in HOME).

• SHELL names the program blueprint shell starts for an environment with no tool from a Nix source (default: /bin/sh).

• PATH is where expected tools, nix, tar, ln and chmod are found.

No variable selects a provider or turns Nix on or off: Blueprint.roc alone decides what a request needs. No request blueprint makes carries a token or any other credential, and it reads none from the environment.