The roc-blueprint manual

Blueprint.roc is an ordinary Roc application on the roc-blueprint platform. Its one value, config, is a list of settings, so configurations compose with ordinary Roc lists, functions and imports.

Roc checks quoted values and whole-configuration rules during roc check Blueprint.roc: missing names, duplicate declarations, unknown references and inheritance cycles are compile-time errors. An editor shows them as you type. Checking needs a Roc nightly the platform release was built for; each release’s notes name it. A download’s URL, the path of a program inside an archive and the name of a system are each checked where they are written. Every tool names the package source it comes from, and its name is checked against that source’s grammar. Whether a package exists is decided by Nix, and whether a URL serves anything by blueprint update, not by Roc.

The platform lowers and validates the whole configuration, then prints it as a Spec, a provider-neutral S-expression (format 2.7). The blueprint command runs Roc to get that Spec, validates it again through the same shared rules, plans the request, and owns every download, file write, the lock and execution. It fetches programs into a per-user store itself, and asks the Nix provider only for the environments that have a tool from a Nix source. The core package and the Nix renderer are pure: they discover nothing about the host and perform no effects. The architecture chapter explains the model and the rules that keep it independent of any one package ecosystem.

A blueprint binary is released for x86_64 Linux, arm64 Linux and Apple Silicon macOS. It needs no Roc and no Python: it downloads the Roc compiler that reads Blueprint.roc. It needs Nix with flakes enabled where the table’s last two columns apply, and tar, ln and chmod to unpack and link what it fetches.

On Intel macOS blueprint stops with a message naming the supported systems. On Windows the code that runs a task without Nix is present, and nothing of it can be used; see Windows.

Systems in a configuration declares the systems a project is for: a fetched program gets a digest for each, and the generated Nix outputs have each. It installs nothing and is not evidence that a target runs: x86_64-darwin may still be listed there.

Each release attaches a blueprint binary for x86_64 Linux, arm64 Linux and Apple Silicon macOS, named blueprint-x86_64-linux, blueprint-aarch64-linux and blueprint-aarch64-darwin, with their SHA-256 sums in blueprint.sha256. Download the one for your system from the latest release, check it and put it on your PATH:

That is all the first project below needs. Nix with flakes enabled is needed for the tools a project takes from a Nix package source and for its sandboxed builds, and for nothing else: blueprint requirements says which of a project’s tasks need it. Where Nix is installed, the same version also runs from the flake:

In GitHub Actions, the setup-blueprint action installs Nix and a release’s binary and checks its sum.

Loading a configuration runs one exact Roc nightly. The binary uses a roc on PATH when it is that nightly, and otherwise downloads it from its release, checks it against a digest the binary records, and keeps it in its store of downloads. Set ROC to choose the executable yourself; it must be that same nightly.

Put this in Blueprint.roc at the root of your repository. The platform URL is the latest release’s:

Use each release’s blueprint binary with that release’s platform URL. The two are built and tested together.

The file declares one environment, dev. It has two commands:

Each task names its environment and an exact argument list.

blueprint update is the only command that decides anything: it downloads the compiler for your system, hashes it, and writes the digest for every system to Blueprint.lock. Every other command uses that file and fails if it no longer matches Blueprint.roc. blueprint run then downloads nothing: the compiler is kept in a per-user store and checked against the lock on every use.

None of this starts Nix, and blueprint requirements says so:

A tool that should be installed, rather than fetched as one program or expected of the machine, comes from a Nix package source. Declare the source, and write each tool with the source’s name. Inside config:

To give native the fetched compiler and git as well, start its settings with Extend("dev").

The project now declares something Nix resolves, so blueprint update needs Nix: it pins the source’s revision in the same Blueprint.lock. After that, only what uses the source starts Nix. blueprint run zig-version does; blueprint run version still does not, on a machine with Nix or without. blueprint update nix moves that one source and keeps every other pin and digest.

Commit Blueprint.roc and Blueprint.lock. The lock is the authority: a versioned S-expression listing each download with its digest and each pinned source with its revision.

blueprint keeps what it generates under .blueprint/ and writes a .gitignore there, so that directory never reaches a commit. If your repository already tracks .blueprint/, untrack it once:

Inside an Environment, Tools and Overlays occur at most once, ToolsFor occurs at most once per System, Command occurs at most once per command name, ToolWith occurs at most once per tool, and RocPackages, Programs and Expect occur at most once each:

Inheritance deduplicates by first occurrence, parent first. Omitted or empty Tools/ToolsFor/Overlays lists do not clear inherited values. A standalone environment has no overlays unless selected. Run must contain a nonempty executable; arguments remain separate strings, including extra CLI arguments after --. There is no In setting or implicit task environment. One name is only one of a program, an expected tool and a Command in an environment, including what it inherits.

A program that is published as a file or an archive is fetched: downloaded from a URL Blueprint.roc gives, checked against a digest in Blueprint.lock, and put on the PATH of the environments that list it. No package source is involved and Nix is not started.

Fetch(name, recipe) is a command name and a recipe: a function from a system to where the program is downloaded from on that system. The environment gains the command name. A recipe downloads nothing. It is asked once for each of the project’s Systems while Blueprint.roc is checked, and its answers are what blueprint works from. The Recipes module is the platform’s; import it with import pf.Recipes.

Some tools are better taken from the machine than installed: git, which every developer and CI runner has, or gh, which must be the one that is logged in. Expect declares them:

Before a task or shell of that environment starts, and before anything is downloaded for it, blueprint looks for each name on PATH. One message names everything that is missing:

An expected tool is not installed, not put on PATH and not pinned, and no version is asked of it: the environment runs with whichever one the machine has. Where a version matters, fetch the program or take it from a package source instead, or have a task check tool --version. blueprint requirements lists what a project’s tasks expect, so a CI job can install it first.

A sandboxed build has nothing of the machine, so an environment a build uses may not have Expect or Programs.

A tool that a package source installs is written "<source>#<name>", for a source declared with Packages:

The source’s name is the project’s choice; nix and stable mean nothing to blueprint. The source is always written, in Tools, ToolsFor, Command and ToolWith alike, and there is no default. "git" alone is refused where it is written:

A tool that names a source the project does not declare is refused with the sources it does declare, as unknown source: nix; Blueprint.roc declares stable. A project whose environments have no such tool declares no source, and Nix is not started for it.

Nix is started only for an environment that has a tool from a Nix source. An environment Nix must build although it has no tool of its own, such as the sandbox of a build whose environment is empty, is built with the first Nix source declared, in the order of Blueprint.roc. The bash that nix develop runs a shell or task with comes from that first source too.

The core does not autodetect a provider or translate package names. Guix source intent and pure capability validation exist, but there is no Guix renderer or executor. An incompatible requested environment fails; it never retries another provider. Missing native packages and unavailable target packages fail in Nix rather than being silently filtered out. Unsupported Nix target declarations fail before file writes or provider execution.

For a shell shared by Linux and macOS, put common tools in Tools and declare platform libraries explicitly:

ToolsFor is provider-neutral Spec intent. It applies to inherited environments, shells, tasks and builds on that System; undeclared systems and duplicate declarations are rejected during evaluation.

Command exposes one tool of a package source under another command name, without adding the tool’s own executables. It keeps a pinned tool beside another of the same name: a second Python, say, for scripts that must not follow the project’s own:

The environment gains python-stable beside the python3 of nix. The command runs the tool’s main program as its package declares it; a package that declares none fails in Nix. Command names are plain file names. An extending environment inherits commands and replaces one by declaring the same name.

A Command is a tool of a package source, so its environment starts Nix. A program that is published as a download needs neither: Fetch names its command itself. A Roc compiler for scripts is written Fetch("roc-stable", Recipes.roc_nightly(tag)), as in Fetch a program; Command("roc-stable", "nix#rocpkgs.<tag>") with the roc-overlay selects the same compiler through Nix, for an environment a sandboxed build uses.

Some packages are built to order. A Rust toolchain from rust-overlay comes with the host’s standard library only; the targets it can compile for and its extra components are options of the package. ToolWith names the tool and those options:

The environment gains cargo and rustc from Rust 1.95.0 with both musl targets and the standard library’s source. Zig needs no options: zig-overlay names each release as an attribute, which Tools selects.

The options are the names and values the package’s own override takes, written as Val data: strings, integers, booleans, lists and attribute sets. They are passed as data and are never an expression, so they select among what the package offers and cannot say how to build it. A package that takes no options, or not the ones named, fails in Nix.

A tool is either plain or configured in an environment, not both. An extending environment inherits configured tools; configuring an inherited tool replaces all of its options. Three things are not supported:

A tool’s version is whatever its source holds at the pinned revision. Blueprint.roc names the tool, not its version, so to hold one tool at an exact version, give it a package source of its own, pinned to a nixpkgs revision that ships that version. For CPython 3.14.3:

<revision> is a full nixpkgs commit whose python314 is 3.14.3. To find one, look at the history of the package’s file in nixpkgs, or evaluate a candidate:

How the source is written decides whether the version can move:

Nothing in Blueprint.roc states the version, so nothing fails if it changes. If a version matters, assert it where the tool is used, for example by having the project’s check task run python3.14 --version and compare.

An overlay that publishes each version under its own attribute needs no second source: select the attribute, quoting a segment that contains dots.

A Roc script names its platform and packages by release URL, and Roc downloads them on first use. RocPackages names those bundles for an environment instead, so Blueprint has them in place before its scripts start, and they run at all in a sandboxed build, which has no network:

Each URL must be https:// and end in <hash>.tar.zst. The hash is that of the bundle’s bytes, so the URL itself says what the download must be.

List every bundle, including dependencies of dependencies. basic-cli above depends on http, so both are listed. roc deps <file> prints the URLs a program depends on. Blueprint does not read package headers, so it cannot add a missing one for you. A bundle that is not listed is downloaded by Roc as usual in a shell or task, and fails to resolve in a sandboxed build.

Use ordinary Roc lists and functions for composition, not a plugin registry. ProjectTasks.roc returns List(Config.Setting); its app concatenates those settings into config. Imports do not install tools or add runtime operations to the CLI.

The Nix provider accepts attribute data at two targets:

Values are Str, Int, Bool, List([…​]) and Attrs([(name, value), …​]). They are data, not Nix expressions. Duplicate attributes and overrides of managed packages/devShells are rejected. Raw for other providers is ignored.

Inside config, with scripts/build.roc in the project and the build-scripts environment of Lock the Roc packages scripts use:

Run is any argv; nothing about a build requires Roc. Roc takes the first -- of its arguments for itself, so pass a script its own arguments after one: Run(["roc-stable", "scripts/build.roc", "--", "--release"]).

Run blueprint update, then blueprint build app. The printed store path is resolved by Nix and contains exactly the declared file or directory. Missing outputs fail. Needs(["library"]) adds build dependencies; cycles fail during configuration validation. Sources live under $BLUEPRINT_INPUTS/<name> and needed artifacts under $BLUEPRINT_ARTIFACTS/<name>, both read-only and separate from the writable project copy.

Each build snapshots current project files, including untracked/task-generated files, excluding VCS metadata, caller-generated roots, authority and all local input trees. Nix makes that copy directly from the project, so a file is executable in a build only when its owner may execute it. Changing a locked local source requires explicit update. Initial source/output policy rejects symlinks and special files. Only local x86_64 Linux sandboxed execution is verified; tasks/config compilation are not sandboxed. A build’s PATH holds exactly the tools its environment takes from its package sources, and nothing of the machine: no sh, cp, mkdir or python3 unless the environment’s Tools name bash, coreutils or python3. A command that is not there fails with build command not found, or inside the build’s own script when that script calls one. A build does not see the variables Nix’s stdenv exports either. A tool may give what it runs more than the build was given: the Roc compiler’s package puts coreutils and a C compiler on the PATH of a script it runs. An environment with fetched programs or expected tools cannot be a build’s: a sandbox holds only what its package sources supply, and the build is refused when it is planned. The blueprint executable is itself each build’s builder inside the sandbox, so blueprint build refuses to run unless that executable is an x86_64 Linux one. See the complete runnable example, real build fixture.

Inside config, referring to existing tasks and builds:

blueprint workflow ci plans the complete dependency/capability/layout/lock closure before executing any task. Steps run in order and stop on the first failure. Repeated explicit tasks and builds repeat; every build snapshots current project files and rebuilds its dependency graph from that snapshot. Nix may reuse unchanged inputs, but Blueprint never caches artifact results across tasks. Locked sources are verified again; task edits to them require explicit update. Cycles and excessive depth/expansion fail during configuration validation. See the real workflow fixture.

blueprint run, shell, workflow and build do the same things in the same order, and each stops the command before the next begins:

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

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.

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.

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

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 update is the one command that decides what a project uses. It writes the whole lock or nothing.

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.

Nothing in this file is Nix’s: there is no Packages, Overlay, Input, Source or Build, and no tool written "<source>#<name>". The compiler comes from a release by a digest in Blueprint.lock, git is the machine’s, and the Roc packages are downloaded by the URLs that name their hashes.

What starts Nix is decided by Blueprint.roc alone, never by a variable, a flag or what happens to be installed:

blueprint requirements gives the first row’s answer for a project’s tasks without running anything; see What tasks need. Where Nix is needed and nix is not on PATH, the command stops before it downloads or runs anything and names the tool that asked for it:

A task still needs a Blueprint.lock that matches Blueprint.roc: the digests are in it. Evaluating Blueprint.roc needs the Roc compiler blueprint was built for, which it downloads into the same store when ROC is unset and no matching roc is on PATH.

Everything blueprint downloads for itself is kept in one per-user directory, named by content:

<store> is blueprint under XDG_CACHE_HOME, or under .cache in HOME when that is unset; a relative value is refused. <kind> is file, tar.gz, tar.xz or zip: a single file made executable, or an archive unpacked whole, because a program may need what lies beside it. On macOS roc links with the darwin directory of its archive.

The store may be deleted at any time; the next run fetches what it needs again. The files of a tree are read-only and its directories are not, so an ordinary rm -r removes it. A Roc nightly is about 67 MB as an artifact and about 220 MB unpacked.

blueprint downloads over HTTPS itself. It sends no token, cookie or other credential, and follows at most five redirects, each of which must be HTTPS. A request that fails in transit or is answered 408, 429 or a 5xx status is tried three times; a 404 is final at once. When a download has alternate URLs (Mirrored), they are tried in order, and the message for a program no URL served lists what each one answered. A whole download is held in memory while it is hashed.

Roc packages are not kept in this store. They go into Roc’s own package cache; see Lock the Roc packages scripts use.

For each step, blueprint makes a directory run/run-<random>/bin under the generated directory (.blueprint/ unless you moved it), holding one symbolic link for each fetched program, named as Fetch names it and pointing at the program inside its tree. That directory is put first on the step’s PATH, ahead of everything the caller had, and is removed when the step ends, however it ends. A task whose command is the name of a fetched program is started from that link whatever else is on PATH.

Expected programs are not put anywhere: they are found on the caller’s PATH, which the step inherits after the links. In an environment that also has Nix tools, nix develop is started with that PATH and puts its own tools ahead of it.

Three programs of the machine are used on this path, besides the compiler and whatever the project expects:

The release includes blueprint-x86_64-windows.exe and the platform’s x64win target. The no-nix CI job checks fetching the compiler, writing a lock, reporting requirements, and building and running a basic-cli program.

The store uses LOCALAPPDATA when XDG_CACHE_HOME is unset. Recipes.roc_nightly selects the nightly’s zip and roc.exe; the Windows tar reads zip archives. Fetched programs are exposed with hard links, or copies when the store is on another drive, and need no ln or chmod.

Include "x86_64-windows" in the project’s Systems: the default list contains Linux and macOS only, and fetched programs are locked for the declared systems.

Windows does not execute a script’s shebang. Name its interpreter in the task: Run(["roc-stable", "hello.roc"]). Nix tools and sandboxed builds remain unavailable. CI checks Windows Server; Windows 10 and 11 desktop installations have not been verified here.

In an unpacked examples archive, with the blueprint binary of the same release:

Only an explicit update creates or changes Blueprint.lock. gen, shell, run, build and workflow require a lock that matches and leave it as it is; the generated .blueprint/flake.lock is derived from it. Every example declares a Nix package source, so blueprint update needs Nix in each; Work without Nix has a project that needs none.

In a checkout of the repository the examples need the platform host built first; see Build and test.

Blueprint turns a typed description of a development environment into a working, reproducible environment. Many tools do this for one ecosystem, and in doing so they tie the user’s intent to that ecosystem’s formats and commands. Blueprint separates the two.

It adopts proven ideas from reproducible build systems: pinned inputs, content addressing, fetches checked against a known digest, and substitution from caches. Every ecosystem-specific concern belongs to a replaceable provider. The same Blueprint can therefore be realised through different package ecosystems, or through Blueprint’s own store, on macOS, Linux and Windows.

The protocol is the product; providers are adapters.

The vocabulary has three parts: data (the things Blueprint records and produces), stages (the steps that turn one kind of data into another) and roles (who carries out each step).

Each kind of data belongs to one layer. A layer is defined by the question its data answers, how long that data lives, and which stages may change it.

The two committed layers, Intent and Decision, are the protocol. Everything below the Lock can be replaced by another provider and rebuilt from the Lock.

The diagram shows how data moves through the layers. Solid arrows are stages that produce new data; each arrow is labelled with its stage name. Dotted arrows are read-only: Inspect reads committed data, and a remote cache can supply or receive trees. Each box is labelled with its layer, so the diagram does not depend on color.

The Lock is the trust boundary. Everything to its left expresses and records decisions; everything to its right follows those decisions without making new ones.

These rules keep the model neutral and reproducible. A design that breaks one of them breaks the architecture.

A new use case should need only a new provider or a new rendering. It should never change the Core or the committed data.

A proposal breaks the architecture, and needs redesigning, if it requires any of these:

roc Blueprint.roc prints the Spec as an S-expression: records are ((field value) …​), lists (a b), tags Tag or (Tag payload …​), and ; starts a comment. blueprint-core/Spec.roc documents every field.

In outline:

Value is Str, Int, Bool, List or Attrs. Its S-expression encoder and parser are hand-written to avoid recursive-codec derivation problems. requires is reserved in Roc; the Roc field is requires_, and Sexpr drops a trailing _ on the wire. There is no major-1 shell packages field.

Lower.lower checks authoring-setting cardinality, asks the recipe of each Fetch in an environment’s Programs once for every declared System and keeps its answers as programs (the function never reaches the Spec; a program listed by several environments is there once, and two recipes under one name that answer differently for the declared Systems are refused), then calls Project.validate as a top-level constant. The CLI calls that same semantic validator after Spec.parse and required-feature checks, so external Spec does not bypass reference or graph rules. Spec.parse rejects other majors before decoding nested records; parsing alone does not establish semantic validity.

Static checks cover generic references, duplicates, inheritance cycles, argv, download URLs (https://<host>/<path> with no credentials, query or fragment; http://127.0.0.1 is accepted so that a test can serve one) and each source’s own grammar for the names of its tools. A tool that names no declared source is refused with the sources that are declared. Package existence and target availability are Nix runtime checks. Core validation never probes the host or installs/fetches anything.

Blueprint.lock is a blueprint-core/Lock.roc value in the same S-expression codec, with its own format (currently 1.1) and the same compatibility rules as the Spec. It holds intent (the parts of the Spec Resolve consumed: source and input declarations, the build sources a provider resolves and per-environment overlay order), which the CLI records on update and compares before every other command, failing with what changed; sources (one provider-neutral { name, provider, ref, rev, digest } per declared input; digest is sha256:<hex>: the Nix provider converts its NAR hashes for remote inputs, and local inputs carry Blueprint’s own tree digest from core Tree), provider-namespaced hints, and fetched (one { name, system, urls, sha256, size, obtained } per declared program and System: the SHA-256, in hex, and the length of the download when it was resolved, the URLs it was declared with, and whether the digest was Computed from the bytes, Published by the release that serves them, or Both; an entry with no obtained is read as Unstated. Programs are not part of intent; each entry carries its URLs, so a program whose URLs changed is stale alone). A project that asks no provider for anything has a Lock with no sources and no hints. The Nix provider’s hint carries its declared input identity and the complete native lock graph; decoding rejects a lock whose Sources disagree with those pins, so hand edits to either side fail. The graph’s root holds one edge that is no declared input: nixpkgs, following the package source Locks.shell_source selects, which Nix writes for the alias in the generated flake (see Providers). Decoding accepts that edge only as the declarations determine it. A Lock written before the alias has no such edge and is still valid: Locks.derive adds it to the working lock, which changes no pin, so nothing needs blueprint update and the next update records it. A Lock that blueprint 0.5 or older wrote records, in its intent, the Auto source every project had then: it is read, found stale for every Spec, and reported as old. Older JSON locks are not migrated. Either way, run blueprint update. fuzz/lock-parse fuzzes the parser.

Realise.plan(spec, request, system, layout, lock, providers) is the Core’s own pure plan of a request. An environment’s fetched programs, the tools it expects of the machine and its Roc packages are planned from the Spec and the Lock alone, as Present, Programs and RocBundles operations. A provider is asked only for an environment that has a tool from a source it realises, and its steps then follow what the Core supplies. A task whose environment has no such tool is its own argv, and a shell with none has no argv: the executor starts the caller’s shell. Every problem of every step is collected before one is reported, and a request with a problem yields no step. Realise.requirements answers, from the Spec alone, which providers a task needs and which programs it fetches and expects.

The executor checks every Present program of every step on PATH and reports all that are missing together; then makes every Programs entry ready in its store, where a download is kept by its SHA-256 and hashed again on each use; then runs the steps, each with a directory of links to its programs first on PATH, removed when the step ends.

Request, Steps and Layout are importable pure core types. NixProvider.plan(project, request, target, layout, locks) derives an ordered Steps.steps sequence, each holding action, files, exact argv, artifact metadata and materialization operations. Request.Workflow(name) uses the same atomic planner as standalone tasks/builds. Execute each step’s operations, stage its files, then invoke its argv; stop immediately on failure. The entire plan must succeed before effects. The caller owns all effects; no provider registry or serialized config recipes are involved. blueprint-core/Provider.roc is the Core/Provider contract: a name, the features the provider implements, render, preflight, realises (which package sources it supplies), realise (Steps from the Lock) and resolve plus lock_from_native (the programs the machine must have, and what to stage and run to produce new pins). Resolve asks a provider only when the Spec declares something it resolves (Realise.resolvers); the digests of fetched programs are the Core’s own to obtain. The CLI uses only that record; scripts/test.roc fails if it reaches into a provider’s modules directly. Nix is the only implemented provider. It:

Project.check_environment(project, Nix | Guix, name) is a pure compatibility check. Guix source intent, native tool grammar and overlay-capability rejection are modeled; no Guix renderer, task implementation or executor exists. The reference CLI lists Nix as its one provider and selects nothing: Realise.plan asks a provider only for an environment that has a tool from a source it supplies, so which requests reach Nix is decided by the Spec.

The source package exports NixProvider and Locks, without importing the CLI or an effectful platform. Locks.decode parses the Lock, checks that its Sources match the "nix" hint’s pins, and validates the native Nix graph; Locks.derive validates declaration/ordered-overlay identity and translates local project-relative paths into a disposable working lock. NixProvider.plan uses that translation. The former opaque-text render_files seam was removed, not retained as a bypass. fixtures/consumer/main.roc is an independent app using these APIs, including caller-selected paths, decoded supplied authority and exact argv; scripts/test.roc checks it and runs its expect`s. `scripts/test_builds.roc separately proves actual relocated local-source translation.

gen, shell, run, build and workflow require existing matching authority. Only explicit update resolves new pins and publishes authority; normal commands stage derivatives and prohibit native lock updates. Named input declarations remain stable across selected closures; selected overlays remain scoped and ordered. Local authority contains relative identity and Blueprint tree digests (core Tree, computed and verified by the CLI without Nix), not checkout paths. Dirty local inputs fail until explicit update. Local verification, caller observation and Nix’s filtered project copy repeat per explicit build, never reusing artifact results by name across tasks.

A new feature usually means: a setting in the platform (Config.roc, Lower.roc), then either an extensions kind or a new optional Spec field (a minor bump), then support in a provider. Prototyping it as Raw or Custom first needs no Spec change at all.

The local platform and CLI share blueprint-core, including Project.validate. The Spec wire format is major 2 (currently 2.7); published major-1 bundles are not compatible. The architecture, terminology (Spec, Provider, Lock, stages) and invariants are defined in the architecture chapter; keep it in sync with changes.

Full development and CI require x86_64 Linux with Nix and flakes enabled.

gives two Roc compilers from roc-overlay, Zig 0.16 and the programs the scripts start: coreutils, git, curl, tar, gzip, zip, unzip and gh. It has no Python. roc is the product compiler, the nightly in blueprint-cli/compiler-version: it builds and tests the CLI, the packages and the platform, and a released blueprint fetches it. roc-stable is the nightly rocStableTag names in flake.nix: the scripts in scripts/ start with #!/usr/bin/env roc-stable and run on it, so they keep working while the product moves to a newer nightly. The scripts reach the product compiler through ROC, or roc on PATH. This shell is the one definition of the toolchain: every CI job runs its scripts through nix develop -c, so what passes in the shell is what CI runs. blueprint is not in the shell, so entering it never compiles the CLI; build it as below, or use nix run ..

blueprint-cli/main.roc uses the released basic-cli platform by URL. Roc downloads it on first use outside Nix; the Nix blueprint package fetches the same archive by hash, so its sandboxed build needs no network.

The .roc files in scripts/ are Roc programs; they start other programs by argument list, not through a shell. Run one from the repository root with the pinned roc on PATH, or as "$ROC" scripts/test.roc.

The platform’s linker inputs are not committed. scripts/link_inputs.roc fetch downloads the release pinned in link-inputs.lock.json into .cache/link-inputs/, verifies it and installs the files beside libhost.a; nothing that evaluates a Blueprint.roc against the local platform links without them. scripts/link_inputs.roc check verifies what is installed without the network. See blueprint-platform/targets/README.md.

scripts/test.roc is the full CI entry point. Its groups are static (formatting; no tracked object file, archive or import library; the CLI’s use of the Provider contract; the compiler downloads Bootstrap.roc records, one for each system the CLI runs on; each workflow’s permissions and checkouts; the release notes chapter against the notes files; the flake’s list of core modules and its version), unit (the platform’s, the scripts', the CLI’s and the consumer’s expect`s, the configuration fixtures and the Roc the manual shows), `cli, scenarios (test_scenarios.roc, test_roc_packages.roc and the golden flakes parsed by Nix), builds (test_builds.roc and test_workflows.roc), package (the flake’s package and development shell, the packaged CLI building an artifact with only Nix on PATH, and a dry run of what a release ships: core and the platform bundled and smoke-tested, the examples archived and the archive tested; see The two bundles), glue (scripts/check_glue.roc: the host’s committed roc_platform_abi.zig is what roc glue writes for the platform with the product compiler; scripts/check_glue.roc --update rewrites it) and fuzz (each target’s committed corpus, replayed, which takes seconds; .github/workflows/fuzz.yml fuzzes each target for five minutes every week, starting from the inputs earlier runs found, which it keeps in the Actions cache through FUZZ_CORPUS, and uploads any crashing input). scenarios and builds are the real-Nix suites, split into two groups of about the same length so that CI runs them as two jobs at the same time. scripts/test_config.roc runs the compiler on generated Blueprint.roc fixtures: the platform’s own rules, which only a compiler run can show (a setting given twice or not at all, in Lower.roc, and each checked name’s from_quote), a few core rules and bounds as witnesses that shared validation surfaces at compile time, and that settings composed from an imported module emit the same Spec as inline ones. Every other rule of Project.validate has an expect in blueprint-core/Project.roc. The bundle gate repeats a few of the fixtures against the served platform, plus the all-settings example. It then compiles the manual’s Roc (scripts/src/DocSnippets.roc): every [source,roc] block of docs/ and docs/releases/, and the first program of the Get started chapter, against the platform in the working tree; see Write the manual. scripts/test_cli.roc exercises the built CLI with and without a configuration, checks validation and help/version handling, and records Nix argv to verify shell selection and task arguments without entering a shell. It holds what only a run can show: the order of checks before any effect, how often the configuration is evaluated, exact provider argv and error text. Rules that a pure expect in blueprint-core or blueprint-nix already holds are not repeated there. The all-settings integration tests separately run tasks through real Nix. scripts/test_scenarios.roc writes projects and runs them through the real CLI and real Nix: the all-settings and extensions examples, noncommutative overlays in both orders with inheritance, an unselected overlay’s native missing-package failure and a declared overlay that throws if evaluated, system-scoped tools on Linux and macOS with the package-target rejection of an unscoped one, renamed commands, and a task that names a script by path, as scripts/check_all.roc, which starts by its roc-stable shebang on a platform RocPackages supplies and imports a module beside it, and zig-overlay and rust-overlay as overlays, each supplying an exact release named in a quoted attribute, and configured tools: a fixture overlay’s package says which options it was built with, and rust-overlay evaluates a toolchain with two targets and a component. It also runs nix develop --debug on a staged flake and requires Nix’s own report that its bash comes from the locked package source, with no registry lookup, and runs a task with the nixpkgs edge removed from Blueprint.lock, as an earlier blueprint wrote it. A project it writes pins its inputs to the revisions in fixtures/consumer/inputs.lock and flake.lock, and its Blueprint.lock is read-only and compared after every step. fixtures/consumer/main.roc holds the staged bytes and supplied-lock preservation as expect`s. Parse fuzzing also checks successful semantic normalization for idempotence. `scripts/test_builds.roc runs real sandboxed builds of artifacts, dependencies and sources, including host-file and TCP isolation with positive host controls, fail-closed runner checks, exact argv, immutable locks, freshness and relocation. It also checks what Nix copies from the project (bytes, the owner’s execute bit, raw names, exclusions, refused symlinks and special files) and that an undeclared tool is not found. It runs blueprint _build-runner directly on the host for the checks that need no sandbox, with a hand-written witness naming namespaces the host does not have. scripts/test_workflows.roc runs real ordered task/build workflows, nested repetitions, failure stops, snapshot/dependency freshness, repeated locked-source verification, whole-closure preflight and immutable authority, including out-of-tree layouts, and then a temporary copy of the complete artifacts example. Both are Roc scripts on the harness in scripts/src/BuildHarness.roc, and the tasks and builds of their fixtures are Roc scripts run as roc-stable through RocPackages. Their inputs are pinned in fixtures/consumer/inputs.lock and fixtures/roc-inputs.lock.json; one first step fetches them and every later Nix call is recorded and run with --offline. See fixtures/builds/README.md. scripts/test_update.roc checks local-source preflight, authority observation, concurrent publication, named updates and what a lock from blueprint 0.5 is told. scripts/test_isolation.roc checks what a build stages about its caller: the namespace identities, the CLI’s own path as the runner, and the refusals when either cannot be used. Both put a failing python3 on PATH: the CLI itself must not use a host Python. scripts/test_programs.roc runs projects whose environments fetch programs and expect tools of the machine. Nothing selects how they run but their own Blueprint.roc: one with no Nix tool must never start the nix stub. The downloads come from a server the script runs on the loopback address, the store is a directory of the test’s own, and the lock entries are written by the test. It checks what is kept in the store and under which names, that a second run makes no request, that a stored artifact with other bytes is removed with its tree and fetched again, two runs at once from an empty store, every refusal (a missing expected program, a program the lock does not hold or holds under other URLs, another length or digest, each URL’s failure, an archive with a link out of its tree), the caller’s own shell, and parity: the same task with one Nix tool added prints the same from the same store file, and only then starts Nix. Its last cases let blueprint update write the lock: with no nix on PATH for a project that only fetches, with nothing asked when nothing changed, for a named program alone, after a URL list changed, and for release assets. A download URL must be https://, with one exception made for these tests: http://127.0.0.1:<port>/, which no other machine can serve. A loopback URL of the shape /<owner>/<repo>/releases/download/<tag>/<asset> is a release asset, and the same server describes its release at /repos/<owner>/<repo>/releases/tags/<tag>, as GitHub’s API does for a GitHub URL. That is the whole seam: no variable or flag redirects the question. Through it a digest computed here is compared with a published one, another system’s is recorded unfetched, a published digest that differs stops the update, a question that is refused or answered with something else leaves every digest computed and says so once, and a download missing for one system says how to declare that. It ends with blueprint requirements, asked with no nix, no lock, an empty store and no server: the report is the same, a declared and unused Nix source requires no provider, and nothing is written. These are Roc scripts, run from the repository root with ./blueprint built; ROC names the compiler. They replace every tool the CLI runs with one program, scripts/stubs/tool.roc, which each test builds once and installs under several names (roc-record, roc-wire, roc-probe, nix, guix, python3, readlink). A copy decides what to be from its own file name and how to behave from STUB* variables, and records each invocation as a file holding one line of JSON in <name>-calls/ under its working directory. Its header lists what each name does. scripts/src/CliHarness.roc holds what the three tests share. scripts/test_roc_packages.roc is a Roc script, like link_inputs.roc. It runs the real CLI and Nix with a Roc package cache of its own in a temporary directory, and refuses to run if that directory lies inside ~/.cache. A task’s bundles are downloaded by blueprint itself from the releases their URLs name. It checks publication into an empty cache, that a second run writes nothing, that an existing package is left alone and an incomplete one replaced, that failures leave nothing behind, that a project with no build locks no bundle and its task still downloads them, and that a sandboxed build resolves its bundles from the lock with no network while the same build without one of them does not. Normal execution tests explicitly initialize authority with update first. The complete artifacts example is executed in a temporary copy by the workflow suite (scripts/test_workflows.roc).

Every suite above runs where Nix is installed, and replaces it with a stub where it must not be started. One job of .github/workflows/ci.yml runs on machines that have no Nix at all: no-nix, on ubuntu-latest, ubuntu-24.04-arm and macos-latest, with the binaries and platform hosts the build job produced and no step that installs anything. It runs dist/smoke-<system> --no-nix dist/blueprint-<system>, the NoNix mode of scripts/src/SmokeBinary.roc, which:

It reaches GitHub for the nightly and the Roc packages, and asks GitHub’s API once for the nightly’s published digests; a refusal there is a notice, not a failure. To run it on a machine that has Nix, hide Nix from PATH:

The manual is the AsciiDoc in docs/. index.adoc is a book that includes one chapter per top-level .adoc file; .github/workflows/docs.yml renders it as a site and a PDF with the shared build-docs action, on every pull request, and deploys the site from main. Every Asciidoctor warning fails the build.

To render it as CI does, with Docker and a checkout of roc-automation beside this one:

The site is .docs-out/site/ and the PDF .docs-out/roc-blueprint.pdf; neither is committed.

The manual describes the tool as it is: one recommended way to do each thing, in the present tense. What changed between versions belongs in the release notes, and what is unfinished in an issue.

The Roc in the manual is compiled by scripts/test.roc unit, so a block must be one of four things:

Nothing moves either compiler automatically. Each moves in one reviewed pull request, with whatever the new compiler breaks fixed in the same request.

To move the product compiler:

One release holds the platform bundle, the roc-blueprint-core bundle it depends on, the blueprint binaries with their checksums, the examples archive, the documentation archive and the manual. It is made by .github/workflows/release.yml, run by hand from main with a version. Every pull request runs the same workflow as a dry run, under the version 0.0.1-dry-run, which is never published.

A release candidate reports its own version, so version must be set to X.Y.Z-rc1 for it and to X.Y.Z for the final release: the two are different commits. Both use the notes in docs/releases/X.Y.Z.adoc.

Issue #40 asks for blueprint run on Windows. What needs nothing from upstream is in place: a task whose environment has no Nix tool runs with no provider, from fetched programs, expected tools and Roc packages, and the planner, the store’s location and Recipes.roc_nightly have their Windows forms. The Windows target and release binary are built in CI; the Nix-free smoke test runs on Linux, macOS and Windows.

The upstream prerequisites are now released: basic-cli 0.26.0-rc2 supplies its Windows MSVC host and runtime, the pinned Roc nightly links from listed inputs, and the locked roc-platform-template-zig release supplies this platform’s startup and import libraries.

zig build builds targets/x64win/host.lib; the platform bundle carries it and the verified Windows linker inputs. scripts/build_release.roc builds blueprint-x86_64-windows.exe and its smoke program. The no-nix CI job runs that program on windows-latest, fetching the compiler, updating a lock, reporting requirements and building and running a basic-cli program twice. Windows skips chmod and exposes fetched programs with hard links, falling back to a copy across volumes. Archives use the machine’s bsdtar.

The full Nix suites remain Linux-only. Windows 10 and 11 desktop execution has not been verified here; the CI runner checks Windows Server. Tasks must invoke their interpreter explicitly, for example Run(["roc-stable", "hello.roc"]).

Compile-time configuration lowering is restored with Roc nightly-2026-09-23-c7852fd: roc check Blueprint.roc now rejects whole-config errors, including a missing Name or duplicate shells. Older compilers crashed while bundling a top-level constant dependent on the app’s config; the local-Spec and released-Spec bundle tests guard against that regression. blueprint check retains a compiler check for diagnostics and reuses the Spec already loaded for CLI parsing, rather than running the configuration again. The loaded Spec is still needed for shared semantic validation and provider compatibility checks. Runtime validation also protects consumers from external Spec; it does not make major-1 platforms compatible with the current CLI. Loading the Spec still executes Roc, so retain compiler provisioning in the Nix wrapper and support for the ROC override.

These remaining dependencies and workarounds still apply:

This release makes Nix one source among several. A Blueprint.roc now says where each thing comes from: a program downloaded from a URL and checked against a digest in Blueprint.lock, a tool the machine already has, or a tool from a Nix package source the project declares. blueprint starts Nix only for an environment that has a tool from a Nix source, and for a build. A project that fetches its compiler and expects git runs its tasks with no Nix installed.

That matters most in CI. A job that ran one Roc script through blueprint spent about 40 seconds on Nix before the script started. The same task in a project with no Nix source takes 3 to 7 seconds on an empty cache and under a second after that, measured on x86_64 Linux.

Every Blueprint.roc written for 0.5 must be edited, and its lock resolved again. "If you used 0.5", below, has the steps.

This release puts everything a project needs in one place: the platform, the core package it depends on and the blueprint binaries are now published together under one version. It is also the first release with a manual and an archive of the examples.

A Blueprint.roc written for 0.4 needs only the new platform URL.