Prikk Documentation

Prikk is an experimental, design-first distributed version control system built around block-oriented patch theory. This documentation now covers a full guide and reference section, and continues to grow as new areas land.

About the name. Prikk is the Norwegian word for dot. It was chosen because it opens with the p of patches, and because a patch history is exactly that: dots — patches as nodes — connected into a DAG.

New here? Install, then the Tutorial — a first repository from an empty directory to a sealed, verified commit, key setup included.

For the current architecture and trust boundaries, start with:

• Data Model
• Trust and Threat Model

Install

See the root README for what to run: the shell installer below, cargo binstall prikk, a direct download from the release page, or cargo install prikk from crates.io. This page covers what comes after — the steps a new user usually gets stuck on.

The shell installer

curl -fsSL https://github.com/prikk-vcs/prikk/releases/latest/download/install.sh | sh

What it does, exactly: detects your OS and CPU architecture (uname -s/uname -m); downloads that platform’s release archive and its .sha256 file from the same release page URLs the manual path uses; verifies the checksum with sha256sum -c (or shasum -a 256 -c on macOS, which has no sha256sum by default) and installs nothing if verification fails; extracts the prikk binary to ~/.local/bin (chmod +x); and, if that directory is not already on PATH, appends one clearly marked block to your shell’s startup file so a later uninstall can find and remove exactly that block, and nothing else.

Generated, not hand-maintained. install.sh/uninstall.sh are produced by prikk-release-policy generate-installer and attached as release assets at publish time, the same way the tarballs and their checksums are — never committed to the repository as tracked files. Their source template lives in tools/release-policy/templates/, reviewed like any other change to this project.

What it claims, and what it does not. A passing checksum proves the file you received matches what the release page published; it does not prove who published it. In v0 one maintainer key signs every release tag; release-signers.toml is empty because no multi-signer policy exists yet — see how prikk releases. The script prints this same statement when it finishes, rather than only stating it here.

Supported today: Linux (x86_64, aarch64) and macOS (Apple Silicon only — there is no prebuilt binary for Intel Macs). On Windows, this script refuses — it is a POSIX shell script, unusable there — and points at the Windows installer below, rather than silently doing nothing or guessing.

Version selection: defaults to the latest release. Pin one with sh install.sh --version X.Y.Z or PRIKK_INSTALL_VERSION=X.Y.Z — the form a CI pipeline typically wants, so a workflow does not silently pick up a new release mid-pipeline. Override the install directory with --prefix DIR or PRIKK_INSTALL_DIR.

Read it before you run it, if you prefer: curl -fsSL <url> -o install.sh, open it in an editor, then sh install.sh. It is a single self-contained file — nothing it does is hidden behind a second download.

Re-running is safe. It overwrites the binary with the same (or a newly pinned) version and does not duplicate the marked PATH block if one already exists.

Uninstalling:

curl -fsSL https://github.com/prikk-vcs/prikk/releases/latest/download/uninstall.sh | sh

Removes the binary from its install directory and the marked PATH block from whichever shell startup file has it, and nothing else — an unrelated file in the same directory, or unrelated lines in the same startup file, are left untouched. If you installed with a custom PRIKK_INSTALL_DIR, pass the same value to the uninstaller too, the same way: PRIKK_INSTALL_DIR=/custom/path curl .... Neither script touches any repository’s own .prikk directory — delete those yourself if you no longer want that history tracked.

One real caveat about the PATH edit: macOS Terminal starts a login shell, which reads ~/.bash_profile, not ~/.bashrc, unless your own ~/.bash_profile already sources it. The installer still writes to ~/.bashrc (or ~/.zshrc for zsh) — the file an interactive non-login shell reads on Linux, and the common case this script optimizes for — and says so when it runs; if your ~/.bash_profile does not source ~/.bashrc, add the PATH line manually, or add . ~/.bashrc to ~/.bash_profile yourself.

The Windows installer

irm https://github.com/prikk-vcs/prikk/releases/latest/download/install.ps1 | iex

What it does, exactly: decides the architecture from Windows’ own processor environment variables ($env:PROCESSOR_ARCHITEW6432 when set, else $env:PROCESSOR_ARCHITECTURE — never a .NET API); downloads that platform’s release .zip and its .sha256 from the same release page URLs the manual path uses; verifies the checksum with Get-FileHash and installs nothing if verification fails; extracts prikk.exe to %LOCALAPPDATA%\Programs\prikk; and, if that directory is not already on your user PATH, adds it — see The PATH change, below.

Generated, not hand-maintained. Exactly like install.sh/uninstall.sh above, install.ps1/uninstall.ps1 are produced by prikk-release-policy generate-installer and attached as release assets at publish time — never committed to the repository as tracked files. Their source template lives beside install.sh’s own, in tools/release-policy/templates/.

What it claims, and what it does not. The same statement as the shell installer’s: a passing checksum proves the file you received matches what the release page published; it does not prove who published it. The script prints this itself when it finishes, the same as install.sh does.

prikk.exe is not code-signed, and Windows may warn or block it.

Supported today: x64 Windows installs the x64 build. ARM64 Windows installs the x64 build too, which runs under Windows’ own x64 emulation. Any other architecture refuses with a pointer to the manual .zip download or cargo install prikk, the same way the shell installer refuses an Intel Mac.

Version and install-directory overrides: environment variables only — PRIKK_INSTALL_VERSION=X.Y.Z and PRIKK_INSTALL_DIR=<path>, set before the one-liner above. There are no --version/--prefix flags here, unlike install.sh: the one-line irm | iex form evaluates the downloaded script as if it were typed at the prompt, with no way to forward positional arguments to it the way sh -s -- --version X.Y.Z can.

The PATH change. The installer adds its install directory to your user PATH (never the machine PATH), without asking first — the same no-prompt rule install.sh follows for its own PATH edit. It records in a marker file, inside the install directory, that it made the change; uninstall.ps1 removes the PATH entry only if that marker says this installer added it, so a directory you had already put on PATH yourself beforehand is left alone.

Execution policy. The one-line form above is unaffected by execution policy: code piped into Invoke-Expression runs as if typed at the prompt, which is not the code path execution policy gates. If you instead save the file first (irm <url> -o install.ps1, the same “read it before you run it” option the shell installer offers) and try to run that file directly, PowerShell’s default policy will likely block it — either Unblock-File .\install.ps1 first, or run it as powershell -ExecutionPolicy Bypass -File install.ps1.

Re-running is safe. It overwrites prikk.exe with the same (or a newly pinned) version and does not add a duplicate PATH entry if one is already there.

Uninstalling:

irm https://github.com/prikk-vcs/prikk/releases/latest/download/uninstall.ps1 | iex

Removes prikk.exe, the marker file, and the install directory itself if it is then empty, and the PATH entry — but only if the marker says this installer’s own run added it. If you installed with a custom PRIKK_INSTALL_DIR, set the same value before running the uninstaller too.

Arch Linux (AUR)

Two packages, prikk and prikk-bin, are generated and pushed to the AUR by the release workflow (the aur-build and aur-push jobs) for every tagged release — not hand-maintained. This differs from install.sh/install.ps1 above: those are attached as release assets, while these are pushed straight into each package’s own AUR git repository.

prikk-bin installs the prebuilt binary and needs no key. Its PKGBUILD carries no validpgpkeys — the checksum is all it verifies. As elsewhere on this page: a passing checksum proves the package you received matches what the release published; it does not prove who published it. Before building, paru -G prikk-bin downloads its PKGBUILD for reading: check that its source_x86_64/source_aarch64 URLs point at github.com/prikk-vcs/prikk/releases/download/.

paru -S prikk-bin   # or: yay -S prikk-bin

prikk builds from the signed source tag instead, and needs one step first that prikk-bin does not: import the release key, using the same command Verify the tag below already uses.

curl -fsSL https://github.com/nabbisen.gpg | gpg --import

This step is not optional. AUR helpers cannot fetch the key for you: it is on no public keyserver — neither keys.openpgp.org nor keyserver.ubuntu.com has it. Without the import, makepkg stops with “unknown public key”. Once the key is imported, read the PKGBUILD before building:

paru -G prikk   # downloads the PKGBUILD (and .SRCINFO) for reading; builds nothing

and check that validpgpkeys names 25757DA6CBF7022C4E14CCAC1B3066B87DB99A34 and that the source= line ends in ?signed. Anyone with AUR push access to the prikk package controls its text, and could delete validpgpkeys and the ?signed suffix on source= entirely, leaving no signature check at all. The signature protects the source only for as long as the PKGBUILD is the one the release workflow itself generated and pushed — so check those two fields yourself before every build.

paru -S prikk   # or: yay -S prikk

makepkg verifies the tagged source against the imported key before building; a tag whose signature does not verify never reaches cargo build. That check accepts a signature only from a fingerprint actually listed in the PKGBUILD’s own validpgpkeys — importing the wrong key cannot pass it.

Verify the checksum

Every downloaded release archive ships beside a .sha256 file recording its SHA-256 digest — for example, prikk-x86_64-unknown-linux-gnu.tar.gz ships beside prikk-x86_64-unknown-linux-gnu.tar.gz.sha256. Download both into the same directory, then verify from inside it, substituting the archive name for your platform.

Linux:

sha256sum -c prikk-x86_64-unknown-linux-gnu.tar.gz.sha256

macOS (no sha256sum by default; shasum reads the identical file format):

shasum -a 256 -c prikk-aarch64-apple-darwin.tar.gz.sha256

Both print <archive name>: OK on success and exit non-zero on a mismatch.

Windows (PowerShell):

$expected = (Get-Content prikk-x86_64-pc-windows-msvc.zip.sha256).Split(' ')[0]
$actual = (Get-FileHash prikk-x86_64-pc-windows-msvc.zip -Algorithm SHA256).Hash.ToLower()
$expected -eq $actual

This should print True. Unverified on a Windows machine — this command was derived from how the release build produces the checksum file (a lowercase hex digest, matching sha256sum’s own format), not confirmed by running it.

A passing checksum means the download was not damaged in transit. It does not show that the file is genuine: whoever can replace an asset can replace its checksum too. To check that a release came from the project’s key, see Verify the tag below. The wider caveats are in Release, Versioning, and Compatibility.

Verify the tag

Release tags are signed with the project’s one maintainer key. Its fingerprint is:

25757DA6CBF7022C4E14CCAC1B3066B87DB99A34

Fetch the key, then check the tag of the version you installed. The check runs in a clone of the repository, so you need one (an installed binary has none):

curl -fsSL https://github.com/nabbisen.gpg | gpg --import
git clone https://github.com/prikk-vcs/prikk && cd prikk
git verify-tag --raw 0.48.0 2>&1 | grep VALIDSIG

git verify-tag --raw prints the VALIDSIG line on stderr, hence 2>&1. Its last field must equal the fingerprint above; that is the check. The warning “This key is not certified with a trusted signature” is expected unless you have certified the key yourself (gpg --lsign-key). What matters is the fingerprint match.

What the tag covers: the source at the tagged commit. The release binaries are built from that tag by the release workflow and are not signed, so the tag does not cover them. A checksum (above) detects a damaged download, not a substituted one.

Build from source

Prebuilt archives cover four targets: x86_64 and aarch64 Linux, aarch64 macOS, and x86_64 Windows. Anywhere else, build it yourself — there is no separate porting step:

cargo install prikk            # from crates.io, and puts it on PATH for you

or from a clone, which is also what you want when working on Prikk itself:

git clone https://github.com/prikk-vcs/prikk
cd prikk
cargo build -p prikk --release --locked   # binary at target/release/prikk

Other Linux architectures

Fully supported. Nothing in Prikk is gated on CPU architecture — only on the operating system — so any architecture Rust targets on Linux builds and runs with no reduction in capability.

FreeBSD, OpenBSD, and other platforms

They build, but they are read-only. Prikk compiles for FreeBSD, and nothing in it is OpenBSD-specific, so the same applies there — but repository mutation is refused at runtime on any platform other than Linux, macOS, and Windows:

repository mutation requires Linux, macOS, or Windows root-scoped filesystem capabilities

So init, commit, and seal will not work. Reading an existing repository does — verify, log, status, doctor, and the other read-only commands.

This is a review boundary rather than a technical one. FreeBSD has the filesystem primitives Prikk’s POSIX path uses; what it does not have is a durability implementation anyone has reviewed, or CI that exercises one. Prikk refuses rather than writing history through a path nobody has audited. Support is recorded as a future theme and is not scheduled. Platform Support states what each supported platform guarantees, including two narrower guarantees on Windows.

Put the binary on PATH

cargo binstall/cargo install place the binary in Cargo’s own bin directory (~/.cargo/bin on Linux/macOS), which is normally already on PATH once Rust is installed.

For a direct download, move the extracted prikk (or prikk.exe on Windows) into a directory already on your PATH — ~/.local/bin is a common choice on Linux/macOS if it’s already there — or add the directory you placed it in to PATH yourself.

Confirm it worked

prikk --version

prints the version you installed, in the form:

prikk <version>

Check that <version> matches the release you downloaded — that match is the actual verification, not any particular number this page could show.

If the shell reports “command not found” instead, the binary is not on PATH yet.

Next: Tutorial

Installing the binary configures no signing keys. Continue with the Tutorial — it walks through your first commit and seal, key setup included, using disposable public example keys. Security and Signing Setup covers real key handling once you are past that.

Uninstalling

Prikk places nothing outside its own binary and, inside each repository it manages, a .prikk directory. Delete the binary, and remove .prikk from any repository whose history you no longer want tracked — there is nothing else to clean up.

First Run: Keys and Setup

Read this before Install’s next step, Tutorial — this page is about getting your own signing keys, not the shared example seed the tutorial deliberately reuses so its own walkthrough is reproducible.

Every prikk commit and every prikk seal needs a real Ed25519 key. Before prikk key and prikk setup existed, obtaining one meant inventing 32 bytes by hand and then having no way at all to derive the matching public key — reproduced first-hand while preparing this project’s own release testing, by copying a public key out of a CI configuration file rather than deriving it. That gap is what this page closes.

The fast path: prikk setup

prikk setup composes init, key generation for both roles, and trust maintainer add into one command:

prikk setup ./my-repo

initialized Prikk repository at ./my-repo/.prikk
trusted maintainer key: ed25519-cd1bc694acba34fe
adopted maintainer keys: 1

your keys are in /home/you/.config/prikk
every new shell finds them -- nothing to export

next steps:
  prikk commit -m "<message>"
  prikk seal --allow-no-audit  # no audit trust policy is configured yet; see `prikk seal --help`

There is nothing to export and nothing to copy. Both seeds are written as files in your key directory, and every later prikk run finds them there — this shell, tomorrow’s shell, after a reboot. Commit and seal directly:

echo "hello prikk" > ./my-repo/readme.txt
(cd ./my-repo && prikk commit --from-worktree -m "genesis")
(cd ./my-repo && prikk seal --allow-no-audit)

Each new key gets its own key id. A key id is the name a signature carries. setup names each key it creates ed25519- followed by the first 16 hex characters of its public key, and writes that id beside the seed. Your keys’ ids are therefore yours alone: two people who each ran setup can exchange history, and each adopts the other’s maintainer key under its own id. The id is a name, not a proof. What makes it an identity is that a repository binds one id to one public key. prikk key status shows the id in effect and where it came from.

Neither command names a branch. Every command that takes --ref defaults to the branch named in .prikk/current-branch, which init and setup set to heads/main; --ref given explicitly always wins.

Where your keys live

One directory, per platform, and prikk resolves it itself:

It holds author.seed and maintainer.seed, plus author.key-id and maintainer.key-id, each holding the id of the seed beside it. A key-id file must belong to its seed. If the file does not hold the id derived from the seed in use (a replaced seed, a copied file, or hand-edited content), signing is refused, and prikk key status reports the key unusable, naming the file and both ids. To sign under an id of your choosing, set PRIKK_AUTHOR_KEY_ID / PRIKK_MAINTAINER_KEY_ID; never edit the file. On Unix the directory is mode 0700 and each file 0600; prikk refuses to read a seed file that group or others can read, naming the mode and the chmod that fixes it. On Windows there are no mode bits: the directory relies on %APPDATA% being per-user by platform ACL, which is stated here rather than assumed — it is the one location where prikk accepts inherited permissions, because they are the right ones and they are known.

--author-seed-out <path> / --maintainer-seed-out <path> override the location. A seed written somewhere else is not found automatically, so setup prints the PRIKK_AUTHOR_SEED_FILE / PRIKK_MAINTAINER_SEED_FILE line that points at it, and the key id. The id lives in <path>.key-id, beside the seed, and is found from there. It is printed, not exported: an exported PRIKK_*_KEY_ID would override the file.

The seeds are not recoverable. There is no copy in the repository, no keyring, no escrow. Lose the AUTHOR seed and you can no longer sign patches with that identity; lose the MAINTAINER seed and you can no longer seal to a repository that already trusts it. Back up the key directory the way you back up anything else you cannot regenerate.

The trust decision is always shown, never performed silently. trusted maintainer key: <id> is the same line prikk trust maintainer add itself prints — registering a maintainer key is a trust act, and composing the steps removes the typing, never the seeing.

After a reboot

Nothing to do. Your keys are files in the key directory, so a new shell, a new terminal, a reboot — prikk commit and prikk seal keep working with no setup at all. This section used to explain how to re-export two variables after every reboot; the variables are gone.

If you moved a seed with --*-seed-out, that one is the exception: prikk does not look there on its own, so export its PRIKK_*_SEED_FILE in your shell profile —

export PRIKK_AUTHOR_SEED_FILE="$HOME/keys/author.seed"

— or move the file into the key directory and drop the variable.

PRIKK_AUTHOR_SEED and PRIKK_MAINTAINER_SEED are no longer read

Before prikk 0.40 a seed was passed as an environment variable. That channel is removed: a seed in the environment leaks into process listings, shell history, and any child process, and it silently survived in profiles long after the key had changed.

A stale export is now simply ignored. prikk 0.40 refused while either variable was set — one release wide, so that no automation could quietly start signing with a different key than it thought it was using — and 0.41 stopped doing even that. Either variable may sit in your shell profile indefinitely; prikk does not read it, and does not object to it.

You can still remove it, and should, because it is a secret sitting in a file for no reason. To see which key is actually in effect before you commit anything:

prikk key status

That names the file each role resolves to and whether it is usable — see Can I Sign Here?.

The commands setup composes — and when you’d use them directly

setup is not the only way in. Each step is a first-class, documented command in its own right, and understanding them is what lets you reason about what setup actually did.

prikk key generate — a fresh seed

prikk key generate

seed: ...
note: this seed is now in your terminal scrollback -- treat it as a secret
key id: ed25519-2d353d98420bc75c
public key: ...

next steps:
  recommended: re-run with --out <path>, which writes the seed and its key-id file
  prikk trust maintainer add --key-id ed25519-2d353d98420bc75c --public-key ...
  or save by hand -- both files, mode 0600:
    /home/you/.config/prikk/maintainer.seed  (the seed above and a newline)
    /home/you/.config/prikk/maintainer.key-id  (exactly ed25519-2d353d98420bc75c and a newline)
note: a seed saved without its key-id file signs under the shared legacy id `maintainer`, which other installations may also use
note: the same seed works as an AUTHOR key instead -- name the files author.seed and author.key-id and skip the trust step

Saving by hand needs both files. The key id travels with the seed only through its key-id file; a seed saved alone signs under the legacy id every installation made before 0.45.0 shares.

--out <path> writes the seed instead of printing it — and then it is never printed at all, only the public key and the next steps are:

prikk key generate --out ./maintainer.seed

wrote seed to ./maintainer.seed (mode 0600)
key id: ed25519-2d353d98420bc75c (in ./maintainer.seed.key-id)
public key: ...
...

--out also writes the key’s id to <path>.key-id, and the id is found there whichever role uses the seed. --out refuses to overwrite an existing file (the seed or its key-id file), and refuses any path with a .prikk component — prikk never invents a secret’s location and never manages its lifecycle (writing it once, where you asked, is the entire commitment). On Windows, --out currently refuses outright: Unix file permissions (mode 0600) have no portable equivalent here without unsafe code or a new dependency, and writing a secret at whatever permissions the filesystem happens to inherit, silently, is not acceptable. Print and place the seed yourself instead.

prikk key public — derive a public key you already have

With no arguments it reads your key directory’s author.seed; --role maintainer reads the other one:

prikk key public --role maintainer

public key: ...

--seed-file <path> reads any other seed file instead — one you moved with --*-seed-out, or one from elsewhere entirely.

The seed is read from a file, never from an argument. A --seed <hex> flag would put key material into /proc/<pid>/cmdline (world-readable on Linux) and into shell history; a path is not a secret, and the seed itself never appears on the command line. This replaces the older --seed-env <NAME>, which took the name of an environment variable holding the seed — there is no longer an environment variable to name.

prikk trust maintainer add — the trust act itself

prikk trust maintainer add --key-id <the key id key generate printed> --public-key <the hex key generate printed>

Registering a maintainer key is what lets prikk seal publish — see Security and Signing Setup for the full trust model, revocation, and what is and is not enforced today.

Which key is which

Two independent roles, two independent seeds:

• AUTHOR signs the Patch a commit queues. No trust registration needed for it at all.
• MAINTAINER signs the Block, RefState, and RefUpdate a seal publishes, and must be registered with trust maintainer add first.

Trust is per-repository. The trust policy a maintainer key is adopted into belongs to one repository, so the same maintainer key must be trusted again in every repository you seal in — adoption is a trust act about this repository, not a machine-wide or account-wide setting. An AUTHOR key has no such step anywhere, which is why it travels for free.

setup generates one of each, but a single seed works as either role — key generate prints the maintainer framing because that is the one role requiring a visible trust step, but the same seed saved as author.seed works too, with no trust step at all.

A second project

prikk setup ./second-project

initialized Prikk repository at ./second-project/.prikk
trusted maintainer key: ed25519-cd1bc694acba34fe
adopted maintainer keys: 1

using your keys in /home/you/.config/prikk
every new shell finds them -- nothing to export

using rather than your keys are in is the whole difference. setup found the seeds already in your key directory, so it minted nothing and wrote nothing — it initialized the repository and adopted the maintainer key you already have, which is the one step a new repository genuinely needs. Both projects sign with the same identity, which is usually what you want when it is the same person.

Pointed at a directory that already holds a repository, setup refuses before doing anything at all:

error: precondition not met: ./second-project already holds a repository; to use your existing keys
here run `prikk trust maintainer add` (see `prikk key public`), or pick a different directory for a
new project

If you want the second project to have its own identity, give the new seeds their own paths:

prikk setup ./second-project \
  --author-seed-out ~/keys/second-author.seed \
  --maintainer-seed-out ~/keys/second-maintainer.seed

setup prints the PRIKK_*_SEED_FILE lines for them, since prikk will not find them on its own.

The same thing by hand

setup composes it; these are the steps if you would rather run them yourself:

cd ./second-project
prikk init .
prikk key status --role maintainer        # the key id line names the id to adopt
prikk trust maintainer add --key-id <that key id> --public-key "$(prikk key public --role maintainer | sed 's/^public key: //')"

prikk commit needs nothing extra — an AUTHOR key is registered nowhere, so it needs nothing from any repository. Only seal needs the trust act above; without it:

error: precondition not met: no maintainer key is adopted in this repository yet; run `prikk trust maintainer add` (a trust policy container that replays empty reads the same way -- run `prikk doctor` if a key was adopted here before)

That is the state every new repository starts in, not a fault. Adopt the key, deriving the public half from the seed you already hold:

prikk key public --role maintainer

public key: 27b081593fa86489f9356ef4bc0cbf5f4a5a5b708aa1a10f1a8187fd56a34801

prikk trust maintainer add --key-id ed25519-27b081593fa86489 --public-key 27b081593fa86489f9356ef4bc0cbf5f4a5a5b708aa1a10f1a8187fd56a34801
prikk seal --allow-no-audit

trusted maintainer key: ed25519-27b081593fa86489
adopted maintainer keys: 1
sealed active WAL into block

The --key-id must be the id seal signs under, which prikk key status --role maintainer reports; seal checks the signer against what this repository trusts under that id.

Keys made before 0.45.0

A seed with no key-id file beside it signs under the legacy id: author or maintainer, the role word. Keys made by setup before 0.45.0 look like that, and keep that id. Nothing about an existing installation changes, and its repositories keep committing, sealing and verifying. setup reusing such a key says so:

note: your author key uses the shared legacy key id `author`, which other installations may also use; for a distinct one, set PRIKK_AUTHOR_KEY_ID and adopt the key under that id in each repository

Every such installation shares those ids, so two of them collide. One key id binds to one public key in a repository, so:

• history one installation signed under author cannot be imported into a repository where author is already bound to the other’s key;
• a maintainer key cannot be adopted under maintainer beside a different one.

Both refusals name the route that works: sign new history under a distinct id, either a key made by prikk key generate --out <path> (pointed at by PRIKK_*_SEED_FILE) or an id set with PRIKK_*_KEY_ID, and adopt the maintainer key under that id. History already signed under the shared id keeps it; there is no command that re-signs it.

Claim-to-Source Anchors

Provenance

Written for RFC 135 §9, which measured the unfamiliar-step count to a first sealed commit at eleven, with the third step (deriving a maintainer public key) impossible before this page’s own commands existed. See Git → prikk for how prikk’s commands relate to Git’s, including git config’s row, which is where this page is cross-linked from.

Tutorial

This is the first thing to read after Install — one continuous path from an empty directory to a sealed, verified repository: create it, make a commit, seal it, then look at what you built. It confronts key setup directly, because commit and seal both need one and a tutorial that hides that fails at your second command.

Prikk is early implementation software and is not a production Git replacement. Work through this tutorial with throwaway content — nothing here is a claim that Prikk is ready to hold history you care about yet.

Create a repository

mkdir sample-repo && cd sample-repo
prikk init

initialized Prikk repository at /path/to/sample-repo/.prikk

.prikk is the only thing Prikk ever creates. There is no separate config step.

Your first commit — and why it needs a key

Add a file and commit it:

echo "hello prikk" > readme.txt
prikk commit -m "genesis"

error: author signing is required: no seed at /home/you/.config/prikk/author.seed. Create one with `prikk key generate --out /home/you/.config/prikk/author.seed`, run `prikk setup` in a new project directory, or set PRIKK_AUTHOR_SEED_FILE to an existing seed file

This refusal is the point, not a mistake in this tutorial. Every commit in Prikk produces a signed Patch — there is no unsigned-commit mode to fall back to. The refusal names the file prikk looked for; create it and try again:

prikk key generate --out ~/.config/prikk/author.seed
prikk commit -m "genesis"

recorded worktree patch in active WAL
baseline ref: heads/main
patch id: ...
WAL sequence: 1
operations: 1
referenced blobs: 1
  create-file readme.txt

The seed above is a public example, shown in this documentation and in the project’s README — never use it, or any seed you have shown anyone else, for real signing. See First Run for how to generate your own, and Security and Signing Setup for how real key material is meant to be handled; this tutorial only needs you to get past the refusal, not to understand key management yet.

The commit is recorded, but nothing has been published — readme.txt’s patch sits in the active write-ahead log until you seal it. You can commit again before sealing; Prikk queues patches and seals them together. This tutorial seals right away.

Sealing — and the second key

prikk seal --allow-no-audit

error: maintainer signing is required: no seed at /home/you/.config/prikk/maintainer.seed. Create one with `prikk key generate --out /home/you/.config/prikk/maintainer.seed`, run `prikk setup` in a new project directory, or set PRIKK_MAINTAINER_SEED_FILE to an existing seed file

A different role, a different key. commit signs as the author of a change; seal signs as the maintainer who publishes it — Prikk keeps the two separate even when one person holds both roles, because the trust boundary they express is different (see Trust and Threat Model for why). Set the maintainer key and try again:

prikk key generate --out ~/.config/prikk/maintainer.seed
prikk seal --allow-no-audit

error: precondition not met: no maintainer key is adopted in this repository yet; run `prikk trust maintainer add` (a trust policy container that replays empty reads the same way -- run `prikk doctor` if a key was adopted here before)

One more refusal, and it is also expected. Having a maintainer key configured is not the same as Prikk trusting it — a repository only publishes under keys it has been told to trust, explicitly, once:

prikk trust maintainer add \
  --key-id "dev-maintainer" \
  --public-key "a00899dfd3357aee69729405913f9324dfc033cec04a2215239eda64ae6d9d91"

trusted maintainer key: dev-maintainer
adopted maintainer keys: 1

The public key above is the matching half of the example seed — trust-on-first-use means whichever public key you adopt for a key id here is the one Prikk holds that id to from now on. Now seal succeeds:

prikk seal --allow-no-audit

sealed active WAL into block
patches: 1
block id: ...
heads/main RefState: ...

Your commit is now published: a sealed Block on heads/main, with a RefState recording exactly which block that ref points at.

Look at what you built

prikk log

ref: heads/main
block ...
  update-seq: 1
  kind: Root
  parents: 0
  patches: 1

Root means this is the first block on this ref — nothing came before it.

Check its integrity

prikk verify

verified repository: /path/to/sample-repo/.prikk
...
checked blocks: 1
...
issue summary: errors=0, warnings=0, info=1

verify re-derives every check from the objects on disk — signatures, structural links, WAL replay — rather than trusting any cached summary. A clean repository still prints one info line; that is not a problem, only a note.

Doctor

prikk doctor

doctor repository: /path/to/sample-repo/.prikk
...
issue summary: errors=0, warnings=0, info=1

doctor runs the same structural checks as verify and adds repair-oriented diagnostics — this is the command to reach for when something looks wrong, not verify again. On a healthy repository the two report the same thing.

Where to go next

• Hit a refusal this tutorial didn’t cover? See Troubleshooting.
• Wondering why Prikk works this way rather than how to make it work? See the FAQ.
• Ready for the real key-handling story — not the public example seeds above? See Security and Signing Setup.
• Want the full command reference? The rest of this guide is organized one page per command.

This tutorial’s own command sequence is exercised by an automated test (crates/prikk-cli/tests/installers_and_help/beginners_tutorial.rs), which runs every command above, in order, against the compiled binary, and asserts on the same output lines quoted here — including both refusals. A change to the CLI that alters any of them fails that test, not just this page.

Troubleshooting

Refusals a newcomer actually hits, in the Tutorial’s own sequence, each quoted verbatim from the CLI. If a message here reads as confusing, that is worth reporting — this page explains what exists today; it does not change any wording.

For the three key-material refusals below — a missing seed, a seed others can read, and an undecodable one — prikk key status reports the same state without needing a commit to provoke it, and exits 0 while doing so. It names the file in effect, whether it is usable, and why not. See Can I Sign Here?.

error: author signing is required: no seed at <path>

prikk looked for your AUTHOR seed and did not find it. Every commit produces a signed Patch; there is no unsigned path. The message names the exact file and three ways to get one — create it with prikk key generate --out <that path>, run prikk setup in a new project directory, or point PRIKK_AUTHOR_SEED_FILE at a seed file you already have. seal says the same for the MAINTAINER seed. See First Run for where the key directory is on each platform.

prikk key status --role author shows which of the two inputs it is resolving and to which path — useful when the file you created is not the file it is looking for. An override that is set and points at nothing reports reason: override-missing, which distinguishes “you have no key” from “your PRIKK_AUTHOR_SEED_FILE is wrong”.

prikk 0.40 also reported error: precondition not met: PRIKK_AUTHOR_SEED is no longer read when a seed was still exported as an environment variable. That refusal was deliberately one release wide and is gone as of 0.41: a stale PRIKK_AUTHOR_SEED or PRIKK_MAINTAINER_SEED is now simply unread, and prikk key status is where you check which key is in effect instead.

error: <path> is readable by group or other (mode 0644); run chmod 600 ``

A seed file anyone but you can read is refused before signing. Run the chmod the message names. (Unix only — on Windows the key directory relies on %APPDATA%’s per-user ACL instead.) prikk key status reports the same file as usable: false with the mode in its reason, and running it again is how you confirm the chmod took.

error: <path> must be 64 hex characters, got 8

A seed file must hold exactly 64 lowercase hex characters (32 raw bytes) — the number after got reports how many your file actually had, so it will differ from the 8 shown here. A shorter, longer, or non-hex value is rejected before anything is signed; nothing is written to the repository when this fires. prikk key status reports such a file as reason: undecodable.

error: invalid name: worktree has no node-addressed changes to commit

You ran commit with nothing changed since the last commit or seal — no new, edited, or deleted files for Prikk to record. Change something first.

error: maintainer signing is required: no seed at <path>

seal needs a maintainer key, distinct from the author key commit used — see why the tutorial needs a second key. Same three routes as the AUTHOR case above, with maintainer.seed in place of author.seed.

error: precondition not met: no maintainer key is adopted in this repository yet

Your maintainer key is configured but not yet trusted by this repository. Run prikk trust maintainer add --key-id ID --public-key HEX with your maintainer key’s id and public half (prikk key status --role maintainer reports the id; prikk key public --role maintainer derives the public key), then seal again. This is a repository-local, trust-on-first-use step — every fresh repository needs it once, even with a key you have used elsewhere.

The message’s parenthetical names the one other way this refusal can be reached: a trust policy container damaged so badly it replays as empty is indistinguishable, at this read, from one never written. If you know a key was adopted here before, run prikk doctor.

Earlier releases reported this same refusal as error: integrity error: publication trust policy is missing or unreadable, which sent readers looking for corruption that was not there.

error: precondition not met: <path>: worktree symlink authoring is out of scope

commit found a symlink where it needs a regular file — an untracked symlink in the worktree, or a tracked file that has been replaced by one, including a dangling symlink whose target does not exist. Symlink authoring is not implemented yet, so the commit refuses rather than authoring something it cannot faithfully replay. Replace the symlink with a regular file, or move it outside the repository (or add it to .prikkignore if it is not meant to be tracked), then commit again.

You do not have to run commit to find these. prikk worktree-status reports the same paths, with the same reason, under refused paths: — see Worktree Status.

Earlier releases reported this as error: integrity error: worktree authoring: unsupported symlink authoring: ..., which sent readers looking for repository corruption. Nothing is damaged.

error: precondition not met: <path>: existing TextFile cannot accept non-UTF-8 content

A path tracked as a text node now holds bytes that are not valid UTF-8. Changing a node’s kind from text to binary (or back) is out of scope, so the commit refuses rather than silently changing what the node is. Restore valid UTF-8 content at that path, or delete the path and add it again as a new node, then commit again.

Earlier releases reported this as error: integrity error: worktree authoring: unsupported kind transition: .... Same refusal, correct class: it is a state you fix, not damage.

error: precondition not met: --target names a tag (tags/<t>); pass the block id it points at, or a branch ref

You ran prikk tag create --target against another tag. A tag ref is one hop from its Block — ref → tag object → block — and a tag of a tag is outside that model, so Prikk refuses rather than quietly tagging the Block instead: that would make “tag this tag” and “tag this block” produce identical history. Pass the block id (prikk tag list shows each tag’s target block) or a branch ref.

prikk branch create --from is the other way round: it does dereference a tag, because --from means “at the block this ref names”.

Earlier releases reported this as error: object type mismatch: expected block, got tag, which read as repository damage rather than as a correctable argument.

error: precondition not met: <path> already holds a repository

You ran prikk setup on a directory that already has a .prikk in it. setup is the first-run command: it initializes a repository and mints a fresh key pair, so there is nothing sensible for it to do on a repository that already has adopted keys. It refuses before doing anything — no init, no keys minted, no seed file written, even when you passed --author-seed-out or --maintainer-seed-out.

Two ways on, both named in the message: to work in the existing repository with keys you already hold, run prikk trust maintainer add --key-id ID --public-key HEX (prikk key status --role maintainer reports the id, and prikk key public --role maintainer derives the public half); to start a new project, point setup at a different directory.

Earlier releases got further before failing: they printed initialized Prikk repository at …, minted two keys, wrote any --*-seed-out file, and only then reported maintainer key id maintainer is already adopted with a different public key. If you hit that version, the seed files it left behind belong to keys no repository adopted — they are not your keys, and can be deleted.

error: integrity error: index entry for <id> resolves to an envelope with computed id <other>

The object index points at the wrong record: the entry claims an object lives at a location that actually holds a different one. Your objects are intact — the containers are self-describing and carry every byte needed — it is only the index that is wrong. Run

prikk doctor --repair-index

which rebuilds the index by scanning the containers, touches no container bytes, and reports how many entries it moved. Then prikk verify again.

This happened when two commands that both write objects ran at the same moment — for example a prikk commit and a prikk tag create. Since prikk 0.40 that is prevented: the second command is refused with lock conflict instead, so a repository cannot reach this state any more. The repair exists for repositories damaged before that.

error: integrity error: active WAL has a damaged record (damaged record at byte offset N; K sound record(s) follow it); …

A record in the queue of unsealed commits is damaged, and K intact records stand behind it. prikk verify and prikk doctor name it and exit non-zero. prikk doctor --repair-wal-tail will refuse and leave the file exactly as it is: that switch truncates only a torn tail, the incomplete last record left by an interrupted commit, and this is not one (a sound record follows the damage). Keep the repository as it is and copy .prikk/active/ aside before doing anything else: the intact records can still be read. A torn tail, by contrast, shows as trailing partial WAL bytes: N and a PRIKK-DOCTOR-WAL-TRAILING-PARTIAL warning, and --repair-wal-tail is the right answer to it. (Before 0.48.0 a damaged length was mistaken for a torn tail and the repair deleted the intact records after it.)

error: ... the bytes after byte offset N look like many frame headers; …

0.49.0 (RFC 167). A torn or invalid frame’s own resynchronisation scan — checking whether a sound frame is hidden somewhere later in the file, before concluding this is an ordinary crash tail — gave up after reading 8 times the file’s own size without finishing (the message’s own words: this binary “stopped checking … and treats this as damage, not a torn tail”). This is not a torn tail: the scan could not rule one out, and ambiguity always resolves to damage, never silently to a tail. In practice this needs a file deliberately packed with fake frame headers; an honest crash does not produce it (random bytes following an accidental magic match almost never also claim a plausible length).

A scan this long is damage, not a torn tail, and the tail repairs refuse damage. For a WAL, prikk doctor reports a failed record and recommends “preserve the repository and inspect the failing WAL record before attempting repair” (doctor.rs, PRIKK-DOCTOR-VERIFY-WAL-RECORD-INCOMPLETE). No command repairs this in 0.49.0, so restore the repository from a backup or a clone. For the other files, the diagnosis is again prikk doctor:

• the pointer index: diagnose with prikk doctor; --repair-pointer-index-tail refuses damage;
• trust policy or the received index: diagnose with prikk doctor; --repair-tails refuses damage;
• an object container or the ref log container: no automated repair. If doctor also reports it as an unreferenced remnant, nothing needs the frame and no action is required; otherwise the way out is a copy of a sound repository, the same as any other damaged record in these two files.

error: N queued commit(s) have lost the record of which branch they belong to

Affects 0.20.0 through 0.48.0 (the stranding itself); 0.49.0 adds the way out. A crash during a commit after the first one in a session could leave .prikk/active/default/ref-name empty while the queue of unsealed commits (the active WAL) still held one or more records — because every commit, not only the first, used to rewrite this file by a durable truncate then a durable append, and a crash landing between the two left it empty. 0.49.0 also closes the same condition reached a second way: the file present but naming a different ref than the session’s own commit witness does (RFC 166 D6) — both read identically, since a session cannot have two owners. Either way, the commit itself is not lost (its bytes are durably queued), but nothing can tell which ref it belongs to, so the way through is blocked:

• prikk status shows queued patches: N targeting <missing metadata>, with a warning naming the exact text below;

• prikk verify and prikk doctor both exit 1;

• prikk commit, prikk seal and prikk rollback-draft all refuse with the same text, naming a concrete command to run. When this session’s own commit record (its “witness”) is still readable, it names the branch that record remembers:

  error: 2 queued commits have lost the record of which branch they belong to. This session's own
  commit record names heads/main. Check with: `prikk doctor --restore-queue-target --ref heads/main
  --plan-only`
  

  Without one (the record itself is gone, or this is a session a pre-0.49.0 binary left behind), it names your current branch instead, as a plain assumption:

  error: 1 queued commit has lost the record of which branch it belongs to. Your current branch is
  heads/main. Check with: `prikk doctor --restore-queue-target --ref heads/main --plan-only`
  

  (commit’s own text is prefixed integrity error:; the others are not, otherwise identical.)

• prikk doctor --repair-wal-tail and prikk doctor --repair-tails do not help: there is no torn tail here for either of them to repair.

The ref always comes from you — --restore-queue-target never reads it from the witness, even when the refusal shows one as a hint. With a readable commit record, --ref must match it — a mismatch refuses, rather than silently preferring one source over the other. Without one, --ref must be your current branch (prikk status’s own current branch: <ref> line, which reads a different, unaffected file and so stays right even while ref-name itself is empty or disagrees) unless you pass --not-current-branch — for example, if you made these commits with commit --ref <other> while sitting on a different branch. A current branch that cannot be resolved at all needs the same flag, fail closed, since there is then nothing to compare --ref against.

The way out, run end to end against a real killed repository:

# If a previous run was interrupted mid-write, its lock may still be on disk:
prikk unlock --lock .prikk/active/default/active.lock --yes

# See what this would do first, without writing anything -- the plan shows each queued commit's own
# message and the paths it touches, and the target branch's latest sealed commit, never a bare hash:
prikk doctor --restore-queue-target --ref heads/main --plan-only

# Then do it:
prikk doctor --restore-queue-target --ref heads/main

prikk verify   # now exits 0
prikk seal --allow-no-audit   # the queued commit(s) seal normally, as the restore's own output says

$ prikk doctor --restore-queue-target --ref heads/main --plan-only
doctor repository: /path/to/.prikk
restoring 2 queued commits to heads/main:
  1. add a (a.txt)
  2. add b (b.txt)
heads/main has never been published -- these would be its first commits
plan only -- nothing written

$ prikk doctor --restore-queue-target --ref heads/main
doctor repository: /path/to/.prikk
restoring 2 queued commits to heads/main:
  1. add a (a.txt)
  2. add b (b.txt)
heads/main has never been published -- these would be its first commits
the 2 queued commits now belong to heads/main; publish them with `prikk seal --allow-no-audit`

When there is no commit record to defer to, the plan says so once, honestly, rather than guessing silently: “prikk cannot tell which branch these commits were made on; your current branch is assumed. If you made them with --ref, restore to that branch.”

Restoring to a branch other than your current one needs --not-current-branch, and the refusal without it names both branches:

$ prikk doctor --restore-queue-target --ref heads/other
error: your current branch is heads/main, but you asked to restore to heads/other; if these commits
were made with `commit --ref heads/other` (or `rollback-draft` on it), pass --not-current-branch to
confirm that; otherwise restore to heads/main instead

Nothing about the queued commits’ own content is at risk at any point in this sequence — only the small metadata file naming which ref owns it, rewritten in place (truncated, then appended). 0.49.0 also writes this file once per session instead of once per commit, closing the window for every commit going forward; see current limitations for the status of that fix.

A restored owner is final for this verb: once ownership is present, a second restore refuses the same way a healthy session does, even to a different ref and even with --not-current-branch — a wrong restore is undone by prikk doctor --recovery-restore <run id>, the run its output names, not by a second call.

error: a queued commit you were told had succeeded disagrees with the WAL in a way the WAL's own sound prefix cannot explain (RFC 166)

Affects every prikk before 0.49.0, which could not report this at all. A single flipped byte in the body of a queued commit’s own last frame reads, by itself, exactly like an interrupted write: the checksum it carries no longer matches, and nothing past it decodes either, so the reader cannot tell “a process was killed mid-write” from “this byte changed after the commit already finished.” Before 0.49.0 that ambiguity resolved in favor of the crash reading — doctor --repair-wal-tail treated it as a torn tail and deleted it, silently, even though the commit had already succeeded.

0.49.0 keeps a small acknowledgment record (one per active session, .prikk/active/<name>/witness) and checks it against the queue before answering. When the queue it names no longer matches, it says so instead of guessing:

$ prikk verify
...
trailing partial WAL bytes: 713
...
acknowledged commits: sequence 1 is damaged
...
error: a queued commit you were told had succeeded disagrees with the WAL in a way the WAL's own sound
prefix cannot explain (RFC 166)

(exit 1; before 0.49.0 this exited 0, with trailing partial WAL bytes: 713 the only hint, read as a harmless tail.)

$ prikk doctor
...
error [PRIKK-DOCTOR-COMMIT-WITNESS-ACKNOWLEDGED-DAMAGE]: a queued commit you were told had succeeded
(sequence 1) is damaged
  recommendation: run `prikk doctor --discard-damaged-commits` to remove it; it was already
  acknowledged, so it cannot be removed as a crash leftover
...
error: doctor found repository health errors

$ prikk doctor --repair-wal-tail
...
active session "default": skipped -- this active session has its own blocking issue: a queued commit
you were told had succeeded (sequence 1) is damaged
...
error: doctor repair skipped one or more active sessions; see the per-active outcomes above for which
and why

The way out, run end to end against a real killed repository:

# See what this would remove first, without writing anything:
prikk doctor --discard-damaged-commits --plan-only

# Then do it -- the removed bytes are saved to the recovery log first, all-or-nothing:
prikk doctor --discard-damaged-commits

$ prikk doctor --discard-damaged-commits --plan-only
doctor repository: /path/to/.prikk
acknowledged commit at sequence 1 (patch 01157f0c...)
340 bytes saved to recovery/log (planned, nothing written) before truncation
plan only -- nothing written

$ prikk doctor --discard-damaged-commits
doctor repository: /path/to/.prikk
acknowledged commit at sequence 1 (patch 01157f0c...)
340 bytes saved to recovery/log (planned, nothing written) before truncation
damaged commit discarded

After it, prikk verify exits 0 again. The removed bytes are kept until prikk doctor --recovery-clear removes them. They are saved under the run the output names. prikk doctor --recovery-list groups the saved entries by run, and prikk doctor --recovery-restore <run id> undoes the whole discard when its conditions hold: the WAL and the commit witness come back byte-for-byte, and the run’s files are checked first, so a later repair that changed one of them is named (restore run <later id> first). The content is read back by restoring the run (the queued commit’s own content, not just its presence, since the WAL body is the signed Patch envelope itself). Rows 5 (the record no longer present at all) and 7 (the acknowledgment history itself unreadable) are the same verb’s job too, with no sequence or Patch id to name in row 7’s case — the plan still says so, honestly, rather than guessing one.

If the acknowledgment record itself is what’s damaged, not the queue: doctor reports a warning (PRIKK-DOCTOR-COMMIT-WITNESS-DAMAGED) instead of an error, and does not refuse — nothing acknowledged is at risk when the queue itself is sound. doctor --repair-tails rebuilds it from the sound queue.

error: integrity error: the ref pointer index has an incomplete tail at byte offset N (M byte(s) follow); …

seal, branch create, tag create and merge each refuse before appending to the pointer index itself — the file this refusal protects is always untouched by it. From 0.49.0 (RFC 164 Rule D) they also refuse before writing any object of their own: seal, tag create and merge run this check at the start of the command, before their patch, block or tag object is written, and branch create writes no content object before its own pointer-index append. A refusal therefore leaves nothing new behind. (A refused attempt made by a binary older than 0.49.0 may have left ordinary, content-addressed objects that nothing references; verify still exits 0, and a retry after the repair below reuses them.)

prikk compact --pointer-index refuses the identical way, before touching anything (RFC 164 round 2, carried to 0.49.0 release prep): the live slot it is about to read and reduce ending in a torn tail is the same unclean-tail refusal, the same advice, just reached from a different writer — --plan-only is unaffected, since a plan-only run never writes behind the tail it would otherwise refuse over.

This file also has its own narrower doctor verb, which repairs only this file. The entries below use prikk doctor --repair-tails, which covers this file too (args.rs:101):

prikk doctor --repair-pointer-index-tail

which truncates the incomplete trailing record under the pointer-index lock, saving the removed bytes to recovery/log, the same way --repair-wal-tail does for the WAL. After it, prikk verify should exit 0, and the publication that refused can be retried.

error: integrity error: the trust key container has an incomplete tail at byte offset N (M byte(s) follow); …

trust maintainer add refuses before writing anything, but only when adding this key would actually append to the file — a new key id, or an existing one under a different (conflicting) public key. Both have to write to .prikk/trust/keys.container, and its own last write was interrupted (a crash mid-append); this command would otherwise append behind that torn tail, blind. Re-adding a key id already adopted with the same public key is unaffected: it appends nothing, so it succeeds regardless of the tail. Fixed in 0.49.0 (RFC 164 Rule A): the tail is defined by position here now, the same way it already was for the WAL and the pointer index — a torn prefix, zeros, or garbage all count, whatever the shape. Run:

prikk doctor --repair-tails

which truncates the incomplete trailing record under this file’s own lock, saving the removed bytes to recovery/log first. After it, prikk verify should exit 0, and trust maintainer add can be retried.

error: integrity error: the trust policy container has an incomplete tail at byte offset N (M byte(s) follow); …

The same refusal as the trust-key one above, for the trust-policy container instead (.prikk/trust/policy-a.container or -b.container, whichever prikk verify’s own report names as live) — trust maintainer add and trust maintainer remove both read this container, and both refuse here only when they are about to append their own new snapshot: add of a key id not yet in the policy, or remove of one that is (and is not the last one). Re-adding an already-adopted key, or removing one that was never adopted, appends nothing and is unaffected by a tail here. The way out is the same: prikk doctor --repair-tails, then retry.

error: integrity error: the author key container has an incomplete tail at byte offset N (M byte(s) follow); …

A commit, a rollback draft, or a bundle import/sync accept refuses here only for an author key id this repository has not recorded material for yet — recording it would append to .prikk/trust/author-keys.container, and its own last write was interrupted (a crash mid-append); the same shape as the two trust-store refusals above, for the file that records AUTHOR (not MAINTAINER) key material. A commit (or import) by an author key id this repository has already recorded material for is unaffected: it appends nothing to this file, so it succeeds regardless of the tail. For a commit, this check runs before any of the commit’s own writes (RFC 164 Rule D, 0.49.0): it sits ahead of the blob, object-index and commit-index writes, so a refused commit by a new author key leaves none of them behind. The check runs again immediately before the WAL append that would queue the commit. (A refusal made by a binary older than 0.49.0 may have left an unreferenced blob and index entry; they are ordinary content-addressed objects, and a retry after prikk doctor --repair-tails reuses them.)

error: integrity error: the received index has an incomplete tail at byte offset N (M byte(s) follow); …

bundle import refuses before writing anything at all — not only leaving the received-ref index’s own live slot (.prikk/refs/containers/received-index-a.container or -b.container) untouched, but also the bundle’s own objects and any author-key material it carries: the check runs before the first object write, the same as every other decision an import makes. (sync accept never writes to this file; a received/remotes/* ref is only ever created by bundle import.) Run prikk doctor --repair-tails, then retry the import.

error: integrity error: the <container>'s generation log has an incomplete tail at byte offset N (M byte(s) follow); …

prikk compact refuses before writing anything at all — before the retired slot is truncated, not only before the new generation record — when the container’s own generation log (<container> is “ref pointer index”, “received index”, or “trust policy container”, whichever compact flag you ran) ends in a torn tail from an interrupted compact. This is the same rule as the four container refusals above, one layer up: compact already reads the generation log to pick the live slot, and this check rides that same read rather than performing a new one. compact --plan-only is unaffected: a plan-only run writes nothing, so it never refuses over a tail it would never write behind. Run prikk doctor --repair-tails, then retry compact.

error: integrity error: <container> has a damaged entry; … (seen for a damaged generation-log record, not a slot)

Seen from any command that reads a generation log’s live slot — status, log, branch list, seal, commit, verify, doctor, and compact itself for that container — for either of two reasons (RFC 164 Rule A, §9 and §9.2): a sound record follows damaged bytes further into the file, or the last record is itself complete — its checksum verifies, recomputed with this format’s own real magic and version, over either the claimed length or the length to the end of the file — but its envelope still fails, or its checksum itself is wrong. Neither is a tail: a tail is what a crash leaves, and a crash can only leave something incomplete — a torn prefix, or zeros/garbage with nothing sound after them at the very end. A complete record was fully written, whatever its own stored magic, version, or length field says (one of those three can itself be the single corrupted byte, with the checksum and body untouched — §9.2); a failing checksum or envelope on it is corruption after the fact, not a crash, so RFC 164 §9/ §9.2 treats it exactly like interior damage, never as a tail to be repaired away (repairing it away would silently revert whichever slot it names to the previous one — measured, and closed, on a real build; a corrupted header field did so even before any repair ran, until §9.2 closed that too). On the ref pointer index’s own generation log, this stops every command that resolves a ref, since every one of them reads it; on the received-index and trust-policy generation logs, only compact is affected. Trailing bytes that do not form a complete record (a torn tail) are truncated by --repair-tails, as for every covered file; the removed bytes are saved to recovery/log first. Damage in the middle of the file, or a complete but corrupt last record, has no repair: --repair-tails refuses it, rather than guessing which bytes are safe to remove, or silently undoing the decision the damaged record carried. This entry gives no truncation advice: whether the damage sits before a sound record or is the complete-but-corrupt last record itself, no offset here is one a repair can safely remove.

Handoff 165 Q1b: doctor has nothing of its own for a damaged generation-log record (unlike a damaged slot, generation logs are not among the files check_appended_file_tails reports), so the message names the way out directly instead of sending you to doctor: the ref pointer index names the rebuild (prikk doctor --rebuild-pointer-index --plan-only, then the real run — the remedy is the same as a damaged slot’s, since the rebuild reads neither); the received index and the trust policy container name a copy of this repository’s whole .prikk/ directory from a backup taken before the damage (the trust policy text also says to re-apply every trust change made since).

warning: <container>'s generation log names no live slot; slot <X> was deduced from the entries (…)

0.50.0 step 1 Part E4, corrected by handoff 165 (019 §5.7; 020 §3.1). Seen from prikk verify or prikk doctor, when a compacting container’s generation log reads as empty or absent — not damaged, not a tail, genuinely nothing — while the other slot (b) holds real data. Slot b is never written except alongside the one generation record that names it live, so this shape can only mean a compaction (or, for the ref pointer index, prikk doctor --rebuild-pointer-index’s own rebuild) genuinely happened and the record of it was lost afterward — an accidental deletion, or a partial restore from backup.

This is a warning, not a refusal, when content can decide: every ordinary command already resolves it correctly. Content is tested in both directions (handoff 165 corrected Part E4’s own rule, which tested only one): slot a is stale beside b — or b stale beside a — when either slot equals, or is a prefix of, a compaction of some earlier prefix of the other’s own history (a crash before a switch was recorded, or a write cut short), or when the other slot starts with a full compaction of it and simply kept taking writes after. Whichever one direction holds names the live slot — covering a crash between a compaction’s own new-slot write and its generation record, a partly written slot, and a crash that leaves a slot live but still taking ordinary writes afterward (a new branch, a revocation), without losing those writes or reinstating what they revoked the way comparing only against the stale slot’s current content (an earlier version of this rule) could. Both directions holding and the two slots folding to the same entries means either reading is correct (reported as “both slots agree”). Only when neither direction holds, or both hold while the folds disagree, does the deduction genuinely fail — see the next entry; this is distinct from one of the two slots being damaged, which refuses too but for an unrelated reason (the container’s own damage text, not this one). A restore from the recovery log refuses outright in this ambiguous-or- damaged state instead of deducing, since it is a deliberate writer and a stale meaning file could otherwise compare unchanged and pass.

The way out, named in the warning itself. For the received index and the trust policy container: run the exact command it names — prikk compact --received-index or --trust-policy. It resolves the identical way, saves the slot it is about to overwrite and the generation log as one recovery run first (both saves landing before either file is written), then writes a fresh generation record, ending the deduced state for good. For the ref pointer index, compact --pointer-index instead refuses outright here (Q2 review): the warning names prikk doctor --rebuild-pointer-index --plan-only, then the real run, which re-derives the whole index from the ref log directly, without reading either slot as live — this is the pointer index’s only way out of this state now, not merely one option among others.

error: ambiguous generation log: <container>'s generation log is lost, and its two slots fit two different histories; …

Handoff 165 Q1b (020 §3.1, Q1 review). Seen from the same commands as the warning above, when content genuinely cannot decide: either neither of the two slots relates to the other at all (not a shape any real compaction sequence produces), or both relate and their folds disagree. The Q1 review proved this is not a gap in the rule but a real property of the state: two equally honest command histories — add a key, compact, remove it; or compact again, then add the key back — can leave byte-identical slot files with opposite answers on whether that key is trusted. Once the generation log that would have told them apart is lost, no rule that reads only the slots can be right in both histories, so refusing is the only honest answer. This is a distinct, typed error (PrikkError::AmbiguousGenerationLog, not Integrity) — nothing here is corrupt. doctor raises PRIKK-DOCTOR-GENERATION-LOG-AMBIGUOUS, printed first, before the current-branch warning and any PRIKK-DOCTOR-VERIFY-STAGE-INCOMPLETE error the same ambiguity also causes.

The way out, named in the message itself: for the ref pointer index, run prikk doctor --rebuild-pointer-index --plan-only, then the real run — it re-derives the index from the ref log, never reading either slot, so the ambiguity does not touch it. For the received index and the trust policy container, 0.51.0 adds a second way out, named first: prikk compact --received-index --keep-slot a|b --plan-only (or --trust-policy) prints each slot’s own entry count and folded state — for the trust policy, the keys trusted in one slot and not the other, by name — and which slot content would deduce, or “ambiguous: prikk will not choose,” before anything is written. The user knows which history is theirs; running the real command (without --plan-only) saves the slot it overwrites and the generation log, as one recovery run, before writing anything. A whole- .prikk/ backup taken before the generation log was lost stays the second way out (the trust policy text also says to re-apply every trust change made since that backup) — and the only one left for either container once the generation log is lost and the chosen slot does not decode cleanly (--keep-slot refuses on a damaged chosen slot, naming that fact, rather than guessing).

error: integrity error: the ref pointer index's live slot is not recorded; run \prikk doctor –rebuild-pointer-index –plan-only`, then `prikk doctor –rebuild-pointer-index` first`

0.50.0 step 1 Part E3/E4 (019 §5.7), corrected by Q2b (H1 ruling item 2). Seen from prikk doctor --recovery-restore (plan or run), when the entry being restored names a meaning file in the ref pointer index or the ref log, and the pointer index’s own generation log names no live slot (deduced or ambiguous alike). Unlike an ordinary read, a restore does not deduce here: it is a deliberate writer, checking that a meaning file’s state still matches what the entry recorded before trusting it, and a stale meaning file in this exact state could compare unchanged and let a restore through that should not proceed. The message used to name prikk compact --pointer-index as the way out; that command now refuses outright in this exact state, so it would just hand back a second refusal — the rebuild is named instead, for either sub-case. Run it, as the message says, then retry the restore.

error: integrity error: <container> has a damaged entry; run doctor before reading

Seen from trust maintainer add or a commit, naming the trust-key or author-key container, for either of two reasons (RFC 164 Rule A, §9 and §9.2): a sound record follows damaged bytes further into the file, or the last record is itself complete (its checksum verifies against this format’s own real magic and version, whatever its own stored header fields say) but its envelope or checksum still fails. Neither is a tail — see the generation-log entry above for why a complete record is never one, whatever its position; a genuine tail (trailing zeros, garbage, or a torn prefix at the end of the file, with nothing sound after it, and not itself a complete record) reads as one of the four “incomplete tail” entries above instead, repaired by prikk doctor --repair-tails. doctor has nothing that repairs interior damage in either container — --repair-tails refuses on it, the same way every other covered file’s own repair does, rather than guessing which bytes are safe to remove, or silently reverting the decision (a trust adoption, a revocation) the damaged record carried. This entry gives no truncation advice: there is no offset here promised to be safe to remove. If you believe the bytes after some offset really are nothing but trailing garbage from an interrupted append (not a complete, corrupted record), run prikk verify first and read its own report carefully before deciding to truncate anything by hand; when in doubt, back the file up and ask before changing it.

error: integrity error: ref pointer index has a damaged entry; run \prikk doctor –rebuild-pointer-index –plan-only`, then `prikk doctor –rebuild-pointer-index``

0.50.0 P3c (019 §2.2, §4.4). Seen from verify, doctor, branch list, or anything that resolves the current branch, for the identical two reasons the entry above names, but for the ref pointer index specifically — which, unlike the trust-key and author-key containers, does have a way out: the plan, then the rebuild for real, re-derives the index from the ref log directly, never reading the damaged slot at all. Before 0.50.0 the message said only “run doctor before reading,” which reads this exact container the exact same way and so answers with the identical failure again — the rebuild is what actually clears it. doctor’s own PRIKK-DOCTOR-POINTER-INDEX-INTERIOR-DAMAGE issue prints first, before the current-branch warning and any PRIKK-DOCTOR-VERIFY-STAGE-INCOMPLETE error the identical damage also causes — each of those now names this issue instead of the generic “inspect the failing stage.”

error: integrity error: received-ref index has a damaged entry; no repair exists -- preserve the repository; the way out is a copy of this repository's own \.prikk/` directory from a backup taken before the damage` (or the identical shape for the trust policy container, which adds re-applying every trust change made since)

0.50.0 P3c (019 §2.2, §4.4). Seen from a bundle import, sync accept, or trust maintainer add/remove, for the identical two reasons as the entry above. Unlike the ref pointer index, there is no rebuild for either of these: neither container is re-derivable from anything else this repository holds (the received index is the only record of what was received; the trust policy container’s own history is not reconstructable from the keys alone). The message says this plainly and names a copy of the whole .prikk/ directory, never a single file, as the way out: the two slots and the generation log are one set, and restoring the slots alone could leave a log naming a slot the restored copy disagrees with. For the trust policy container specifically, an older copy could re-trust a key that was revoked since — the message also says to re-apply every trust change made since that backup. Both replace the same circular “run doctor before reading” the pointer index used to share with them, and doctor’s own dedicated issue for each prints first, the same as the pointer index’s own.

error: integrity error: object <id> references missing <role> <id>

Seen from verify (and anything that calls it, such as doctor) after a bundle import was interrupted by a crash partway through, when the object making the dangling reference is itself reachable from committed state (an unreachable one is a harmless remnant instead — see PRIKK-DOCTOR-UNREFERENCED-REMNANT below, which now uses the same canonical form). Exact wording varies with what was missing when the crash landed, but the shape is always object <owner> references missing <role> <id>:

• object <id> references missing snapshot blob <id>
• object <id> references missing block patch <id>
• object <id> references missing parent block <id>
• snapshot of Block <id> names Blob <id> for <path>, which is missing
• lifecycle replay: blob <id> required for a state effect is missing

An unreachable owner producing the identical dangling reference is not an error at all, just a warning naming the same two objects in the same form:

warning [PRIKK-DOCTOR-UNREFERENCED-REMNANT]: object <owner> references missing <role> <id>

In 0.48.0 and earlier, bundle import wrote the objects it carried in the bundle’s own order, not in dependency order — across object types, and, within the same type, a child block could be listed before its own parent — so a crash partway through could leave a Block durable while something it names is not. None of doctor’s three repairs (--repair-wal-tail, --repair-index, --repair-pointer-index-tail) clears this — they do not know this shape. The way out is to run the same bundle import again, with the same input: every object it carries is content-addressed, so the retry only writes what is still missing, and this cleared the state in every case reproduced (25 of 25). Fixed in 0.49.0: bundle import now writes objects in full dependency order (across and within kinds), so an interrupted write can no longer produce this shape. sync accept is ordered the same way now, for the same reason.

0.49.0: this error now fires only when the Block making the dangling reference is itself reachable from committed state — a ref, a received pointer, a queued patch, or a sealed block reached from them (RFC 164 Rule E). A Block nothing reaches this way is an unreferenced remnant, reported as a warning instead — see the next entry.

If this came from prikk show on a sealed block, under 0.52.0 or 0.53.0, specifically on the second (or a later) consecutive EditText of the same file — lifecycle replay: blob <id> required for a state effect is missing, from show alone, in either its text or --format json output — this is not the interrupted-import damage the rest of this entry describes. It is a read bug in show’s own sealed-block fold, fixed in 0.54.0 (CHANGELOG, ### Fixed): the stored history is sound, prikk verify exits 0 the whole time, and no repair is needed or possible for it. The way out is to upgrade to 0.54.0 or later; running any of this entry’s repair steps on a repository that only has this symptom fixes nothing, because nothing is actually damaged.

warning: <owner type> <id> references missing <missing type> <id> (<role>) -- re-run the import if you still have the bundle; otherwise it is harmless

Seen from verify and doctor (as PRIKK-DOCTOR-UNREFERENCED-REMNANT) for a stored object’s own dangling reference when nothing committed still needs it — not reached by any ref, received pointer, queued patch, or sealed block reached from them (RFC 164 Rule E, 0.49.0). The same underlying shape as the previous entry’s error, told apart by reachability: a Block left behind by an interrupted bundle import/sync accept that nothing in this repository was ever going to use is harmless debris, not damage, and verify exits 0 over it. No command removes a remnant in 0.49.0; if the bundle that produced it is still available, re-running the same import is still the way to make it whole, exactly as the previous entry describes — this warning simply means doing so is optional, not required for verify to pass. A remnant that later becomes reachable (a new branch created over it, say) is reclassified as damage — the previous entry’s error — on the very next run: reachability is always recomputed fresh, never cached.

error: repository has interrupted or divergent ref publication state

Seen from verify after branch create, tag create, sync adopt-tag, merge, or seal was interrupted by a crash partway through publishing a ref: the ref’s pointer names a RefState the ref log has not yet confirmed (a “pointer lead”). --format json and doctor name one of two codes, and they mean different things.

PRIKK-VERIFY-REF-POINTER-LEADS-LOG — the lead is completable (RFC 165 R4): the leading RefState verifies under the current trust policy, chains cleanly to the log’s own tip, names a target that exists, and, if the interrupted publication consumed the active WAL (seal/sync seal), the retained WAL evidence still matches it. verify’s own detail line names the way out directly (019 §5.2: verify prints only its own message, never a separate recommendation the way doctor’s issues do), with and without a tail on the ref log container itself:

ref-publication [PRIKK-VERIFY-REF-POINTER-LEADS-LOG]: authoritative pointer leads committed ref log by one transition; run `prikk ref complete <ref>`
ref-publication [PRIKK-VERIFY-REF-POINTER-LEADS-LOG]: authoritative pointer leads ref log by one transition with <N> incomplete trailing byte(s); run `prikk ref complete <ref>`

doctor recommends the same thing, prikk ref complete <ref>. Retrying the same command does not finish it: branch create/tag create still answer “already exists” (the ref was durably created — unless the pointer itself also reports a completable lead, in which case the refusal itself now names ref complete), and merge refuses before gathering evidence rather than building on a pointer its own log has not caught up to.

PRIKK-VERIFY-REF-DIVERGENCE — the lead fails one of those conditions (an untrusted or revoked signer, a broken chain, a missing or wrong-kind target, mismatched WAL evidence, or damage elsewhere in the ref log or pointer index). Three distinct shapes land on this one code, each with its own detail line:

ref-publication [PRIKK-VERIFY-REF-DIVERGENCE]: format-2 ref log leads the authoritative pointer
ref-publication [PRIKK-VERIFY-REF-DIVERGENCE]: format-2 ref pointer is missing while committed log history exists
ref-publication [PRIKK-VERIFY-REF-DIVERGENCE]: ref-log chain or sequence diverges for <ref>

The first two are legacy format-2 shapes (format 6/7 repositories cannot produce them through any normal command — pointer-then-log write order makes them unreachable); the third is a genuinely broken chain. doctor recommends manual recovery only; preserve the repository and ask before changing anything.

prikk ref complete <ref> finishes a completable lead: it appends one more signed RefUpdate record to the ref log, matching the state the pointer already carries, through the exact same write seal’s own DC-38 retry uses (never a new code path for the append). Any adopted maintainer key may complete it, not only the one that started it — the leading RefState is already signed by an adopted maintainer; the completer’s own key only signs the log record, so a different operator can finish a crash another operator’s command left behind. --plan-only prints what it would do (the leading state, its target, the log sequence it would append at, and which key would sign it) without writing anything. seal’s own retry of the same ref is unaffected — DC-38’s natural-retry mechanism still completes a seal-shaped crash through its own existing path, and ref complete refuses a ref that is not actually a pending completion (already caught up, or not published at all) the same way. Measured for merge: 10 of 300 kills on 0.48.0, 16 of 300 on the build carrying 0.49.0’s own dependency-order fix (the two are unrelated defects reached through different commands); every one of those crash states is now either completable (ref complete) or named as a genuine divergence.

A complete damaged ref-log record (never a tail, RFC 164 §9.2) refuses any of seal/branch create/ tag create/sync adopt-tag/merge/ref complete/the rebuild below, identically:

error: integrity error: the ref log has a damaged record at byte offset <N>: <checksum/decode detail>; this is not an incomplete publication and no seal retry resolves it -- the way out is a copy of a sound repository, not a repair

prikk doctor --rebuild-pointer-index (RFC 165 R5)

The other way out: re-derives the ref-pointer index from the ref log directly, structural and never trust-filtered (no signature is re-checked for a record already durable in the log — only a current lead re-enters trust, exactly as above). Where ref complete finishes one ref’s own pending transition, the rebuild recovers the whole pointer index when it — not the ref log — is what is damaged or untrustworthy: a flipped byte in a pointer record, a stale fallback behind the log, or a lead that turns out not to verify at all.

--plan-only prints the same plan a real run writes from (K1), per ref: its state before and after, and every lead it would drop or restore:

heads/main: <before> -> <after>
restored from the log: heads/main (RefState <id> was stale, behind the log)
dropped lead: heads/topic (RefState <id>) -- the leading RefState's signature does not verify under the current trust policy: <detail>

“Restored” and “dropped lead” are never the same claim. A pointer behind the log — commonly a damaged newest pointer-index record, read as an older, already-log-confirmed entry instead — is restored: nothing authorized is discarded, the ref simply ends where the log already soundly confirms. A pointer genuinely ahead of the log that fails RFC 165 R4’s own rule is a dropped lead: a real, signed transition the rebuild refuses to carry forward, because it cannot verify.

It refuses, writing nothing, over the same ref-log damage/tail shown above, or over any completable lead anywhere in the repository (complete it first — overwriting it would drop an authorized transition, the one thing this verb must never do):

error: precondition not met: <N> ref(s) have a completable lead; run `prikk ref complete <ref>` first -- a rebuild would drop an authorized transition: <ref list>

A damaged pointer-index record is not a refusal reason — serving past it is the rebuild’s own purpose. Structural, no signing: a history entirely signed by a key later revoked is unaffected (the rebuild moves no ref on trust grounds alone), but a lead signed by a revoked key is dropped, named, same as any other failed condition.

error: precondition not met: checkout target for <ref> is not a checkpoint, so it carries no snapshot …

The block you asked to check out has no snapshot, which is the normal state of most blocks: seal writes one only at a ref’s first block and every 64 blocks after it. Use the patch-replay route the message names, which does not need a snapshot:

prikk checkout --patch-plan --ref <ref>

Releases before 0.43 reported this as checkout target for <ref> does not contain a snapshot blob, and earlier ones still under error: integrity error:, which read as damage. Nothing is damaged, and nothing was ever missing.

error: precondition not met: no prikk repository at <path>

The directory you ran the command in — or the path you passed — has no .prikk directory. Run the command inside a repository, pass the repository root as the path argument, or create one with prikk setup <path>.

Before 0.45 this was error: i/o error: No such file or directory (os error 2), which did not say which file, or that the repository itself was absent. A real I/O failure inside a repository is still error: i/o error:.

error: precondition not met: ref <ref> does not exist in this repository

A command that reads or advances a ref was given one that is not there — usually a typo, or a branch not created yet (prikk branch list shows what exists). If the message goes on to say remotes/<ref> exists, the name you gave belongs to a received ref: pass it as remotes/<ref> to a command that reads received refs (log, merge-evidence, merge-plan, bundle preview), or take it into a local branch with prikk merge --from remotes/<ref>.

Before 0.45, prikk log --ref on an absent ref reported an empty history with exit 0 and prikk worktree-status --ref reported changes; other commands said ref <ref> is not published (as error: integrity error: or error: invalid name:), does not exist, nothing to export, does not resolve to a published ref, or a false “not a checkpoint”. Scripts that treated an empty log as “no history yet” now see exit 1.

This refusal never applies to the repository’s own current branch (prikk status names it), published or not: log, worktree-status, tree, cat --path, a bare diff/diff --from (the worktree’s baseline), and checkout --plan-only answer for it exactly the same way whether it is named with --ref/--from or left off. 0.45.0 and 0.46.0 refused a fresh repository’s own current branch when it was named explicitly — the one ref this message was never meant to name — which is fixed in 0.47.0; see the CHANGELOG. Every other name, published or not, still refuses exactly as this section describes — including the current branch named as one side of diff --from … --to ….

error: precondition not met: remotes/<ref> is a received ref, and this command does not accept received refs; …

Received refs (remotes/…, from prikk bundle import or prikk sync accept) are untrusted pointers: they can be read and merged from, but checkout, inverse-plan, rollback-preview, bundle export, branch create --from and tag create --target do not accept them. The rest of the message names the commands that do read them. To work on the received history, merge it into a local branch with prikk merge --from remotes/<ref>.

error: integrity error: existing container record for <id> differs from candidate -- this repository is format 6, …

Someone sent you an object you already hold, carrying signatures yours does not — a second signer of the same patch or block. A format-6 repository holds one record per object, so it cannot keep both; format 7 merges the signatures into one object. Check that every prikk that opens this repository is 0.45 or newer (older binaries refuse a format-7 repository at open), then:

prikk format upgrade

and repeat the import or accept. format upgrade verifies the repository first and changes only the FORMAT marker; running it on a format-7 repository changes nothing.

error: precondition not met: <type> <id> would carry at least 5 counted signatures, above the limit of 4 per object …

An import or accept would put more than four counted signatures on one object. The operation is refused whole and nothing is written. A MAINTAINER signature by a key adopted in this repository is not counted, so the limit only bites on signatures this repository has no reason to trust. Ask the sender which signatures the object is meant to carry.

error: author signing refused: <path> holds key id <id>, but the seed at <path> derives <other> …

The key-id file beside your seed (author.key-id or maintainer.key-id) names a different key than the seed derives: the seed was replaced, or the file was copied or edited. Restore the seed the file belongs to, or remove the file so the id is derived again. A custom key id is set with PRIKK_AUTHOR_KEY_ID or PRIKK_MAINTAINER_KEY_ID, never by editing the file. prikk key status reports this state as reason: key-id-file-mismatch; the same refusal reads maintainer signing refused: for the maintainer key.

error: precondition not met: the worktree was materialized from the snapshot of Block <block> on <ref> and is not replay-verified; run prikk verify …

You ran checkout --snapshot-materialize, and the worktree it wrote is the block’s signed state rather than a replay of its history. Until the repository has been replayed, commit, mv, seal, merge, sync accept, sync seal, rollback-draft --append-inverse and branch switch refuse, so nothing derived from an unverified worktree becomes history. Run:

prikk verify

When verify finds nothing about objects, the WAL, refs or block state, it prints provisional worktree: replay-verified; marker cleared and the commands work again. If it prints provisional worktree: kept, fix what verify reported first. See snapshot materialization.

error: precondition not met: <old> -> <new>: the source is present in the worktree again, …

A prikk mv declaration says <old> became <new>, and the worktree says otherwise — most often because the move was undone with a shell mv rather than with prikk mv. The commit refuses rather than guess which one is the tracked node, and the worktree still reads clean: nothing is missing, modified or untracked, so worktree-status reports it as refused declarations: 1 instead.

The refusal names the way out for the state you are actually in, and each command was measured:

prikk mv <new> <old>    # drop the declaration: it nets to no move and is removed
prikk mv <old> <new>    # or make the move again, and commit authors the rename

A shell mv back is not one of them: it recreates the state that produced this refusal.

If both paths exist, prikk mv refuses in either direction until one copy is set aside — delete <old> and commit to author the rename, or delete <new> and then run prikk mv <new> <old>. If the destination is another tracked node this commit does not also move or delete, prikk mv <new> <old> drops the declaration; <old> keeps its content and <new> stays deleted, so the commit authors that deletion. See Declared Moves and Worktree Status.

warning: the snapshot of Block <block> failed validation (…); this report replayed the whole history instead -- run prikk verify``

checkout --patch-plan, --patch-delete-plan or bundle preview tried to start at a snapshot, and the snapshot did not validate. The report did not use it: it replayed the whole history, and its output and exit code are what they would have been with no snapshot. The warning is a sign of a damaged or tampered snapshot object. Run prikk verify, which names the block and the finding.

error: active WAL has no patch records to seal

You ran seal with nothing queued — every commit since the last seal has already been published. There is nothing to fix; commit something before sealing again.

error: invalid name: ref topic is not a local branch ref; expected heads/<name>

You passed a bare name (topic) where Prikk expects a fully-qualified ref (heads/topic). branch create, branch close, tag create, and any --ref flag all take the qualified form — see why refs are fully qualified for the reasoning. Re-run the same command with heads/ (or tags/ for a tag) in front of the name.

error: i/o error: repository mutation requires Linux, macOS, or Windows root-scoped filesystem capabilities

You are running init, commit, or seal on a platform other than Linux, macOS, or Windows. Reading commands (verify, log, status, doctor) work anywhere Prikk builds; mutation does not, by design — see Platform Support.

error: precondition not met: heads/<name> does not exist; run prikk branch create heads/ first

prikk branch switch only moves to a branch that already exists. Create it from the branch you are on with prikk branch create heads/<name>, then switch. The same command says heads/<name> is closed for a closed branch: prikk branch list shows the open ones.

error: precondition not met: the active WAL holds unsealed work for heads/<name>; seal it …

You committed on one branch and have not sealed, and are switching to another. Unsealed work belongs to the branch it was committed on, so the switch refuses rather than leave it stranded. Seal it (prikk seal --allow-no-audit --ref heads/<name>, exactly as the message prints), then switch.

error: precondition not met: the worktree is not clean against heads/<name>: <path> (modified), …

The switch replaces the worktree’s tracked files with the other branch’s, so it refuses while any of them differs from the branch you are on — it would otherwise overwrite or delete your edits. The message lists each path and whether it is modified, missing or an unsupported-path; prikk worktree-status shows the same list. Commit the changes, or restore the files, and switch again. Untracked files do not count and are never touched.

After a power loss on Windows, following a completed branch switch or checkout (RFC 168 residual (a)). The rewritten files can hold their old contents, deleted files can come back, and created files can be lost. Nothing in the repository is damaged. prikk worktree-status lists what differs. The route, run in this order:

1. Move each file it lists as modified out of the worktree. The moved copy is yours: keep it or delete it.
2. For a file it lists as missing, do nothing: the checkout writes it.
3. For a file it lists as untracked that you deleted on the branch, a file that came back, delete it.
4. Run prikk checkout --patch-materialize --ref <the current branch>. It writes the branch’s files into the paths that are now free.

prikk worktree-status should then list nothing for those paths.

error: precondition not met: refusing to switch to heads/<name>: <n> in the way of its files: …

A file the other branch has would land on a path that already holds something that is not part of the branch you are on — usually an untracked file with the same name. Nothing was written. Move the listed paths aside and switch again.

If a switch was interrupted (a crash, a full disk), no file is torn and the current branch is still the old one; commit then refuses with worktree materialization was interrupted (below). Run the same prikk branch switch heads/<name> again: it recognises the half-switched files and completes.

error: precondition not met: refusing to materialize: <n> path(s) in the way: …

checkout --patch-materialize, --patch-materialize-delete or --snapshot-materialize found files that would have to be overwritten: each is listed with why, such as an existing file with different content or not a regular file. Nothing was written. This is the ordinary result of checking out another branch’s files over your own: move the listed paths aside, or commit them, and run the checkout again. Earlier releases wrote every file before the first conflict, left the worktree part-written and reported integrity error: refusing to overwrite existing file with different content.

error: precondition not met: refusing checkout deletion because <n> candidate(s) are unsafe: …

--patch-materialize-delete would delete files that no longer match what history deleted; each is named with the reason. Nothing was written. Earlier releases reported this as an integrity error: without the paths.

error: precondition not met: <path> changed during the checkout, so the worktree is partly written; …

A file the checkout had checked changed before it was written, usually because another program wrote it at the same moment. The checkout stopped part-way and the worktree is marked as interrupted. Move that file aside, then run one of the two routes below.

error: precondition not met: worktree materialization was interrupted, …

A checkout or branch switch stopped part-way: a crash, or the change above. prikk status prints interrupted materialization: … naming your current branch, status --format json carries interrupted_materialization with the two routes, and prikk doctor warns PRIKK-DOCTOR-INTERRUPTED-MATERIALIZATION. Until it is cleared, commit refuses, because it cannot tell a file you deleted from one the stopped checkout never wrote. Move aside any file the stopped checkout named, then run either prikk checkout --patch-materialize --ref heads/<current branch> or prikk branch switch heads/<current branch>; both write the branch’s files again and clear it. A file the stopped checkout had already written stays in the worktree as an untracked file, and commit authors the whole worktree as it always does. Earlier releases reported this as an integrity error: whose suggested route could refuse again.

error: precondition not met: no object <id> in the object store or the active WAL; …

prikk show was given an id that names nothing here — usually a typo, or an id from another repository. Sealed patch and block ids are listed by prikk log; queued (committed, not yet sealed) patch ids by prikk status --format json, and show accepts both. Earlier releases reported this as error: integrity error: no object <id>, which read as repository damage; nothing is damaged.

error: precondition not met: .prikk/current-branch names heads/<name>, which does not exist; …

A command whose --ref you did not give defaults to the current branch, and .prikk/current-branch names a branch that is not there. The same message says which is closed for a closed branch, and .prikk/current-branch is malformed (…) when the file does not hold exactly one heads/<name> line. Nothing is damaged, and both prikk doctor (the warning PRIKK-DOCTOR-CURRENT-BRANCH) and prikk verify report it, as a warning that never changes either command’s exit status. Either run prikk branch switch heads/<name> to an existing, open branch — with an unusable pointer the switch writes only what is absent and deletes nothing — or prikk branch create the branch the file names. Any command still works with --ref given explicitly meanwhile.

error: invalid name: backslashes are not allowed in repository paths

A file in the worktree has a name no repository path can hold — here a backslash; a name that is not UTF-8 says worktree path is not valid UTF-8: <name> instead. prikk commit refuses the whole commit rather than skip the file silently. prikk worktree-status lists it as an unsupported-path entry with this same reason. Rename the file, or exclude it with a .prikkignore rule (Ignoring Worktree Paths).

Something not listed here

Run prikk doctor — it is the diagnostic-first command, and its recommendation lines usually name the next step. If it does not, the message is real (Prikk does not invent placeholder diagnostics) but this page has not caught up with it yet.

FAQ

The conceptual questions the Tutorial raises but does not stop to answer, and the ones that decide whether a first repository becomes a second one.

What do I run first?

prikk init, then work through the Tutorial — it is the shortest path from an empty directory to a sealed, verified repository, and it is exercised by an automated test, so it will not silently go stale.

What is sealing, and do I have to do it?

Yes, if you want the commit to count as history. commit only appends a signed Patch to a local, per-session write-ahead log — nothing is published yet, and nothing else can see it. seal is the step that turns everything queued in that log into a signed Block, publishes a RefState pointing at it, and makes it part of the ref’s real history. You can commit many times before sealing (they queue), but until you seal, there is no history to check out, verify against, or share — only a pending queue status can show you.

There is no auto-seal. A workflow that only commits and never seals is a workflow that never publishes anything.

How many commits can I queue before sealing?

Two environment variables bound the queue, both fail-closed on a malformed value:

• PRIKK_ACTIVE_PATCH_WARN — warn at this many queued patches (default 800)
• PRIKK_ACTIVE_PATCH_LIMIT — refuse further commits at this many (default 1000)

The limit is checked before any write, so a refused commit leaves no partial state. Committing and sealing one-for-one still works exactly as before; nothing forces accumulation.

Why does this need keys at all?

Every commit and every seal in Prikk is a signed object, not a plain record — there is no unsigned mode. Two different roles sign two different things:

• Author — signs the Patch a commit produces. Identifies who authored a change.
• Maintainer — signs the Block/RefState a seal produces, and must be a key the repository has been told to trust first (trust maintainer add). Identifies who published it.

Prikk keeps these separate even for a single-person repository, because the two signatures answer different questions later: who wrote this content and who decided it should become history. See Trust and Threat Model for what each signature is actually checked against, and Security and Signing Setup for how key material is currently supplied — environment variables, not a keychain or config file, and intentionally minimal at this stage.

Why is it heads/topic and not topic?

Every ref name is fully qualified: branches are heads/<name>, tags are tags/<name>. A bare name is refused:

error: invalid name: ref topic is not a local branch ref; expected heads/<name>

The qualification exists so a ref’s kind is legible from its own name, without needing to look anywhere else to know whether v1 names a branch or a tag. There is currently no default or implicit prefix — every command that names a ref (branch create, tag create, --ref) takes the qualified form.

How do I switch branches?

prikk branch switch heads/<name>

.prikk/current-branch names the current branch (heads/main in a new repository), and every command that takes --ref defaults to it. branch switch changes the worktree to the other branch’s files and then moves the pointer. It refuses, and writes nothing, when the branch does not exist or is closed, when unsealed work belongs to another branch (seal first), or when the worktree has changes against the branch you are on (prikk worktree-status lists them). Untracked files are never touched; a file of the old branch is deleted only when it is unchanged. Switching to the branch you are already on is always a no-op — including when it has never been sealed, which just says so rather than claiming the branch does not exist.

An explicit --ref still works on every command without switching. prikk branch list shows what exists and marks the current branch with *. A fresh repository’s current branch, before its first seal, is not one of those rows — it has no published history to list — but is still named: prose prints one line below no branches (current branch heads/main has no published history yet; the first prikk seal publishes it), and --format json carries it as a top-level "unpublished_current_branch" field, null once it has been sealed.

Is my data safe in a Prikk repository right now?

Prikk is early implementation software and is not a production Git replacement. Nothing in this tutorial, FAQ, or troubleshooting page is a claim otherwise — work through them with content you can afford to lose, and see Platform Support and Non-Goals for what is and is not currently guaranteed.

Something else?

If a real refusal sent you here and this page does not answer it, check Troubleshooting first — it is organized by the exact message you saw, not by concept.

Security and Signing Setup

This guide describes the current operator setup for Prikk signing and repository-local maintainer trust. For the full security model, see the trust and threat model. For verification diagnostics after setup, see integrity and recovery diagnostics. For the physical trust-store paths, see repository layout and authority.

Core Caveats

• Prikk is early implementation software and is not a production Git replacement.

• Key input is a seed file per role — a path you name, or the role’s file in your key directory — and intentionally minimal. prikk key status reports what is in effect.

• Seeds are secret key material. Prikk does not store, encrypt, rotate, revoke, expire, or back up private keys — prikk key generate --out writes one, once, to a path you name, and never reads it back or manages it afterward (see First Run).

• prikk key generate draws a fresh seed from the OS CSPRNG; prikk key public derives a public key from a seed you already hold; prikk setup composes both roles plus trust maintainer add into one command. External tooling is no longer required, though nothing stops you from bringing your own matched seed/public-key pair instead.

• Maintainer trust is repository-local, held as a set of adopted MAINTAINER keys with required = 1 (any one adopted key’s signature suffices), and enforces trust-on-first-use per key id.

• AUTHOR signatures are real Ed25519 signatures, and there is no AUTHOR trust policy: no list of adopted author keys, and nothing to adopt one into. A patch signed by an author key this repository has never seen commits, seals, and passes verify — verified by doing it, not inferred.

• What is enforced for AUTHOR keys is one key id, one public key. Committing under a key id the repository has already recorded, with different key material, is refused:

  error: integrity error: author key_id alice already has a different recorded public key (…); one
  key_id binds to one public key -- this looks like a key-rotation attempt, which is not supported and
  is indistinguishable from impersonation
  

  When the id is the legacy default author, which every installation made before 0.45.0 shares, the refusal says that instead. It explains that history signed under author by another key cannot enter this repository, and names the route: sign new history under a distinct id, from a key made by prikk key generate --out or with PRIKK_AUTHOR_KEY_ID.

  That is an impersonation guard, not a trust decision: it stops one identity being silently reused by a different key, and says nothing about whether that identity is trusted. verify reports unverifiable author signatures: 0 when every author signature checks out against the material recorded for its key id.

• MAINTAINER key revocation exists (prikk trust maintainer remove); there is no key rotation, hardware signing, remote trust, sync trust, hosted identity, multi-maintainer threshold policy, or stable migration policy yet.

Current Signing Roles

Prikk currently uses role-bound Ed25519 signatures.

AUTHOR signing is used for Patch envelopes produced by commit and rollback-draft authoring paths. The AUTHOR signature identifies the key used by the authoring path, but it is not checked against a repository-wide AUTHOR trust store.

MAINTAINER signing is used for publication objects. Seal signs Block, RefState, and RefUpdate envelopes with the configured MAINTAINER signer and verifies that signer against the repository-local maintainer trust policy before publishing.

The signature preimage binds the signature algorithm, object type, object id, signer role, and key id.

Current Key Inputs

The CLI reads each role’s seed from a file, in exactly two places and no third:

1. PRIKK_AUTHOR_SEED_FILE / PRIKK_MAINTAINER_SEED_FILE, if set — a path;
2. otherwise <key directory>/author.seed / <key directory>/maintainer.seed.

The key directory is $XDG_CONFIG_HOME/prikk (else $HOME/.config/prikk) on Unix and %APPDATA%\prikk on Windows. The key id recorded in signatures is resolved in one place, in this order:

1. PRIKK_AUTHOR_KEY_ID / PRIKK_MAINTAINER_KEY_ID, if set;
2. the key-id file beside the seed: author.key-id / maintainer.key-id in the key directory, or <seed path>.key-id, which prikk setup and prikk key generate --out write when they create a seed (the id is ed25519- and the first 16 hex characters of the public key);
3. otherwise the legacy role word, author / maintainer, for a seed made before 0.45.0.

A key-id file must hold the id derived from its seed; otherwise signing is refused.

A seed never travels through the environment. PRIKK_AUTHOR_SEED and PRIKK_MAINTAINER_SEED carried one until prikk 0.40. An environment variable is readable by every child process, survives in shell profiles long after the key changed, and lands in process listings — none of which is true of a file the operator places.

0.40 refused while either variable was set, for exactly one release, so that no automation could quietly start signing with a different key than it thought it was using; 0.41 removed that refusal and the variables are now simply unread. prikk key status answers the question the refusal was standing in for — which key will actually sign here — without needing a signing attempt to provoke it.

Each seed file holds a 32-byte Ed25519 secret seed as 64 hex characters. A missing file, a file readable by group or others (Unix), an empty key id, wrong-length seed hex, and non-hex bytes all fail closed before signing.

prikk key public --role maintainer derives the matching public key directly — see First Run. Nothing computes it automatically; deriving it is a separate, explicit step.

Can I Sign Here?

prikk key status answers that question without signing anything, and without printing a seed:

prikk key status [path] [--role author|maintainer] [--format json]

It reports, per role, which of the two inputs above is in effect (source), the file it resolves to, whether that file is usable and if not why (reason — missing, an override that names a file which is not there, readable by group or others, undecodable, or key-id-file-mismatch for a key-id file that does not belong to its seed, with the file and both ids named), the key id and where it came from (key_id_source: environment, key-file or default), and how that key id relates to what this repository has already recorded (binding): unrecorded, matches, mismatch, or — for MAINTAINER — not-adopted.

It answers the same question commit and seal answer when they refuse, from the same computation, so a usable: true here is a prediction of what the signing path will do rather than a second opinion. Not-ready is an answer, not a failure: every state above exits 0. A non-zero exit is reserved for a repository that cannot be read at all.

prikk key status --role author --format json

--format json emits a key-status-v1 document and is the form front-ends should read; it carries public material only.

Maintainer Trust Store Setup

The current commands for repository-local MAINTAINER trust are:

prikk trust maintainer add --key-id ID --public-key HEX
prikk trust maintainer remove --key-id ID

ID must be the key id the MAINTAINER signer signs under, which prikk key status --role maintainer reports. If ID is already adopted with a different public key, add is refused. Adopting under another local id would not help, because the id travels in every signature: the other maintainer must sign under a distinct id. HEX must be the lowercase 64-hex-character Ed25519 public key that matches the MAINTAINER seed file.

add writes the trusted public key and adds it to the repository’s adopted-key set, with required = 1 continuing to mean any one adopted key’s signature suffices. Adopting a key id already in the set with the same public key succeeds idempotently; adopting it again with a different public key is refused. This refusal is Prikk’s trust-on-first-use enforcement: the first public key seen for a key id is the one trusted for that id, permanently, even after removal — remove takes a key id out of the adopted set, but re-adding the same id later with a different public key is still refused. There is still no remote trust distribution.

Minimal Local Workflow

The shortest path is one command — see First Run for the full walkthrough and output:

prikk setup ./sample-repo

setup prints the exports to run next, having already run init, generated both an AUTHOR and a MAINTAINER seed, and registered the MAINTAINER key. If you would rather bring your own matched seed/public-key pair instead of a generated one, or understand each step separately, the same result composed by hand:

prikk init ./sample-repo

export PRIKK_AUTHOR_KEY_ID="author-key-id"
export PRIKK_AUTHOR_SEED_FILE="$AUTHOR_SEED_FILE"
export PRIKK_MAINTAINER_KEY_ID="maintainer-key-id"
export PRIKK_MAINTAINER_SEED_FILE="$MAINTAINER_SEED_FILE"

(cd ./sample-repo && prikk trust maintainer add \
  --key-id "$PRIKK_MAINTAINER_KEY_ID" \
  --public-key "$MAINTAINER_PUBLIC_KEY_64_HEX")

echo "hello prikk" > ./sample-repo/readme.txt
(cd ./sample-repo && prikk commit -m "genesis")
(cd ./sample-repo && prikk seal --allow-no-audit)
(cd ./sample-repo && prikk verify)

AUTHOR_SEED_FILE and MAINTAINER_SEED_FILE are paths to mode-0600 seed files you supply, and MAINTAINER_PUBLIC_KEY_64_HEX a value you supply — prikk key generate --out <path> and prikk key public --seed-file <path> produce them if you do not already have your own. Leave both _FILE variables unset to use the key directory, which is what prikk setup writes.

The MAINTAINER seed and public key above must be matched private/public halves of one Ed25519 keypair. If they do not match, seal fails because the configured signer is not trusted by the repository-local policy.

Seed Handling Warnings

Any seed or key values published in Prikk’s README, quick start, docs, tests, review packages, or issue comments are public examples. They are compromised by publication and must never be used for real signing.

Do not commit real seeds, paste them into issues, store them in shell history, print them in CI logs, or put them in release artifacts. Prikk does not currently provide a secret-storage boundary; the operator owns secret generation, storage, backup, rotation, and destruction outside Prikk.

Failure and Diagnostic Hints

A missing AUTHOR seed file prevents commands that need AUTHOR signing from creating signed Patch envelopes; the refusal names the path it looked for and the command that creates it.

A missing MAINTAINER seed file prevents seal from creating signed publication objects, the same way.

A seed file that group or others can read is refused before signing, naming the mode and the chmod that fixes it.

Malformed seed hex is rejected before signing. Empty key ids and unsafe key ids are rejected by shared signature validation.

An untrusted MAINTAINER signer prevents seal from publishing. A repository with publication objects that do not verify against the local trust policy reports publication-trust issues through verify and doctor.

The current CLI wording is human diagnostic output, not a stable machine-readable key-management contract.

Deferred Work

Key generation and public-key derivation shipped — see First Run. Still deferred: a general configuration command and every durable, non-secret policy setting (no beneficiary yet — a first real adopter is the named trigger); a credential-helper boundary (refused deliberately, git/ssh-style, in favor of the write-once-where-you-name-it model key generate --out already uses); local secret storage beyond that single named write, keychain integration, passphrase handling, key rotation, key expiration, compromise recovery, hardware signing, multi-maintainer thresholds, repository-wide AUTHOR trust policy (including AUTHOR-identity revocation — only MAINTAINER key revocation is supported), remote trust, hosted identity, JSON key-management output, stable trust-policy migration, stable repository-format migration, and production readiness.

Claim-to-Source Anchors

Provenance

This guide implements DC-30. It is documentation-only and does not change signing, trust, CLI, object schema, repository format, verification, seal, or repository behavior.

History Inspection

PR-014 added a small read-only history view for early sealed repositories. PR-030 extends that view with rollback block classification.

prikk log [path] [--limit N] [--ref REF] [--format json]

The command follows the current RefState chain from newest to oldest and validates that each entry resolves to a persisted Block object.

--ref takes any published ref, not only a branch. A tag ref resolves through its tag object to the Block that object names — so prikk log --ref tags/v1 reports the tagged Block, which need not be the branch tip.

For each entry, the CLI reports:

• the target Block ID;
• RefState ID and update sequence;
• Block kind;
• parent and Patch counts;
• rollback block classification;
• rollback-marked Patch count;
• required attestation count;
• previous RefState ID.

A Block is classified as a rollback Block when it references at least one Patch envelope carrying the current development rollback marker and that Patch payload decodes under the supported replay subset.

History inspection does not yet perform full block-DAG traversal, path-aware history queries, rollback authorization checks, or patch algebra.

Repository Status

prikk status

Unlike most other commands, status takes no path or --ref argument: it always reports on the repository rooted at the current working directory, using its default active-session WAL.

For each invocation, the CLI reports:

• the repository’s .prikk directory path;
• the number of active (unsealed) WAL records, and any trailing partial bytes from an interrupted append;
• heads/main’s current RefState ID, specifically — not whichever ref the active queue is targeting, which is reported separately;
• the queued-patch count and the ref it targets, when the queue is non-empty;
• when the worktree was written by checkout --snapshot-materialize and prikk verify has not replayed the repository since, provisional worktree: materialized from the snapshot of <block> on <ref>; not replay-verified — run prikk verify (provisional_worktree in --format json, null otherwise; see snapshot materialization);
• when a checkout or branch switch stopped part-way (a crash, or a file changed during it), interrupted materialization: a checkout or branch switch stopped part-way; move aside any file it named, then run prikk checkout --patch-materialize --ref <branch> or prikk branch switch <branch>, naming the current branch (interrupted_materialization in --format json, holding those two routes, null otherwise; see troubleshooting);
• a warning once the queued-patch count reaches the recommended threshold or the configured hard limit (PRIKK_ACTIVE_PATCH_WARN/PRIKK_ACTIVE_PATCH_LIMIT; see NFR-PERF-02), the same thresholds prikk commit enforces on the write path.
• when the next commit or seal would refuse, warning: the next commit or seal will refuse: <reason>, where the reason is the one that write would give;
• otherwise, when a queued commit was written durably but never confirmed (a previous command was interrupted after its own write, or an older prikk wrote it), note: a queued commit was already written but not confirmed; the two cases cannot be told apart (crates/prikk-cli/src/main.rs:624-641).

status does not run verify’s integrity checks, and does not report the worktree’s own divergence from the replay baseline — that is worktree-status. Multi-operation text diff minimization and audit plugins are not yet implemented; the command’s own trailing line notes this.

Worktree Status

prikk worktree-status reports read-only worktree status against the same replay-derived baseline prikk commit would author against (RFC 122, replay-baseline-handoff-v1.md): the sealed node-addressed lineage for the selected ref, with any already-queued (unsealed) patches folded on top. It answers “what would the next commit author?”, not merely “what differs from the last seal.”

prikk worktree-status [path] [--ref REF] [--format json]

It reports missing, modified, untracked, and unsupported paths. It does not write the worktree. Patch generation is handled separately by prikk commit --from-worktree. To see the content of what commit would author, use prikk diff: a file this command calls untracked is an added entry there.

What the next commit would refuse

Answering “what would the next commit author?” includes the paths it would not author. Every change entry carries an authoring verdict alongside its change kind, and a refused entry carries the reason prikk commit would print for it:

modified files: 1
unsupported paths: 0
refused paths: 1
worktree: changed against baseline
  modified a.txt — tracked path is not a regular file [refused: precondition not met: a.txt: worktree symlink authoring is out of scope]

Three things about that line are deliberate:

• refused is not a change kind. The entry is modified and refused. The refusal is a bracketed suffix, so the first word of an entry line is still the change kind — a reader that splits on it sees exactly what it saw before this field existed.
• refused paths is not unsupported paths. An unsupported path is an unrepresentable name; a refused path is a representable name whose worktree entry cannot be authored. The example above is one without being the other, which is why the two counters sit side by side.
• The reason is commit’s own. Both commands ask one shared classifier, so the string here is the string prikk commit prints, not a paraphrase of it.

In --format json the same facts are a top-level refused_count and, on each change, "authoring": "authored" | "refused" with "refusal": null or the reason string. The fields are additive within worktree-status-report-v1: a consumer written against the older field set reads these documents unchanged.

A dangling symlink — one whose target does not exist — is refused here too. Presence is checked without following the link, so the path reports as modified and refused rather than as missing, which is what prikk commit has always seen. A path that is genuinely absent is still missing, with no refusal.

An unrepresentable name is refused too. A file whose name no repository path can hold — a backslash in it, or bytes that are not UTF-8 — stays an unsupported-path entry, and carries the refusal prikk commit gives that name. In --format json, path is repo-relative for every kind except unsupported-path, where it is the file’s OS name relative to the worktree root, rendered lossily (an invalid byte becomes U+FFFD): no repository path exists for it, and the absolute path on this machine does not belong in a repository-scoped report.

Every live declaration says what the commit will do with it. A prikk mv declaration is not a property of any single path’s entry, so it is reported on its own line, with the resolution the next prikk commit will reach:

live rename declarations: 1
  notes.md -> docs/notes.md [refused: notes.md -> docs/notes.md: the source is present in the worktree again, so the declared move is not what the worktree holds. Run `prikk mv docs/notes.md notes.md` to drop the declaration, or `prikk mv notes.md docs/notes.md` to make the move again]
refused declarations: 1

The resolution is one of rename (authored as a rename, and the line says whether content or mode also changed), deletion (the destination is gone, or a directory stands there — either way it is no longer a file, so the source is authored as a deletion), deletion-ignored (.prikkignore excludes the destination — decided from the rules, whatever kind of entry is there), never-tracked (the source was never a node, so the declaration is dropped), or refused (the whole commit is refused, with that message). A rename line also says (content also changes) or (mode also changes) when the destination differs from the source node’s baseline, because commit authors those beside the rename.

In --format json each declaration carries resolution, refusal, content_changed and mode_changed, and the top level carries refused_declaration_count. These are additions within worktree-status-report-v1: against 0.42.0’s output for the same repository, the only differences are the new keys — no field was removed, renamed, or given a different value.

content_changed and mode_changed are booleans only when the destination is a regular file. They are null when the resolution is not a rename, and when the destination is a symlink, a FIFO or a socket: such a destination is never opened — reading a FIFO would wait forever — so there is no difference to report, and prikk commit refuses over that path anyway (worktree symlink authoring is out of scope, or worktree entry is not a regular file). A symlink is not followed to compare its target.

refused_count and refused_declaration_count are separate on purpose, and clean can be true while a declaration is refused. A worktree whose declared move was undone with a shell mv matches its baseline byte for byte — nothing is missing, modified or untracked — and prikk commit still refuses, because the declaration contradicts what the worktree holds. So read the commit’s prospects as “refused paths: 0 and refused declarations: 0”; either one alone is only half the answer. The resolution comes from the same classifier prikk commit obeys, so the two commands cannot disagree about a declaration — see Declared Moves.

The scanner is intentionally conservative:

• .prikk/ metadata is ignored;
• existing path-safety validation is reused;
• non-ASCII paths remain unsupported until Unicode NFC normalization is implemented;
• no writes are performed in the worktree. Under .prikk/, the baseline derivation this command shares with prikk commit refreshes the rebuildable cache (cache/lifecycle-state.v1), which is best-effort and never authoritative. prikk diff uses the same derivation with that refresh switched off, and writes nothing at all.

For the exact repository path validator rules, see path and worktree safety. A path matched by a .prikkignore rule at the repository root never appears in the untracked list at all — see Ignoring Worktree Paths.

Claim-to-Source Anchors

Provenance

This guide covers RFC 122’s rewire onto the replay baseline, RFC 147 §2e’s per-entry authoring verdict, and RFC 147 §2f’s per-declaration resolution. It does not change repository state, signing, trust, or the bundle/sync formats.

Ignoring Worktree Paths

.prikkignore (since 0.29.0) is a plain file at the repository root. Each non-blank line is one rule: a literal repository-relative path prefix.

target
build/output

target matches target itself and everything under target/ — never target2 or targetfoo. Matching is by whole path component, not by string prefix, so a rule can never accidentally cover a differently-named sibling.

What the syntax deliberately does not have

No globbing, no negation, no comments, no per-directory files. *.log does not work. This is a stated limit, not a first step toward gitignore compatibility — RFC 124’s own reasoning is that a syntax which nearly matches gitignore’s semantics would be worse than one that obviously does not attempt to.

Where it binds

.prikkignore is consulted in exactly three places: prikk commit’s worktree walk, prikk worktree-status’s untracked-path scan, and the worktree side of prikk diff, which reads the worktree the way commit does. A rule that matches keeps a path out of discovery in all three.

Nowhere else. Applying a patch, replaying history, verifying a repository, and materializing a checkout all ignore .prikkignore entirely. This is deliberate: if those steps consulted it, two repositories holding the same signed history but different .prikkignore files could disagree about what that history means — the ignore file governs what gets proposed for authoring, never what already-sealed history is.

A rule can never hide an already-tracked path, or a path lying under one. Adding a line to .prikkignore cannot make commit read an existing file as missing and author a deletion for it — only untracked, undiscovered paths are affected.

One practical consequence worth stating: an ignored directory is skipped without being opened or descended into. That is not only a speed benefit. commit’s own worktree walk fails closed on any symlink or unsupported entry it encounters, and a real node_modules/-style directory is typically full of exactly those — without skipping the whole directory rather than each file inside it, ignoring it would not actually let such a worktree commit at all.

A malformed file refuses; an absent one does not

A .prikkignore that is not valid UTF-8, or contains a line that is not a valid repository-relative path once a trailing / is stripped, is refused outright — commit and worktree-status both fail closed rather than silently treating it as empty. No .prikkignore at all is not malformed: it means no rules, and every repository created before 0.29.0 behaves exactly as it always has.

It is an ordinary tracked file, not configuration

There is no separate configuration mechanism for it. prikk config (since 0.47.0) exists, but its one key bounds the size of incoming objects and has nothing to do with exclusion; a general configuration file remains a deliberately deferred, future increment. .prikkignore is committed and signed like any other worktree file, and it travels through bundle export/import and sync the same way. A repository you receive carries the sender’s own rules, and those rules shape your future commits from that point on — they say nothing about, and change nothing in, the patches you already received.

Limits

• No globbing, negation, or per-directory files. One flat list of literal path prefixes at the repository root is the whole mechanism.
• A file swept into history by mistake still cannot be removed later. .prikkignore prevents future capture; it does nothing about what a worktree already committed before the rule existed.

Claim-to-Source Anchors

Provenance

This guide documents RFC 124’s worktree ignore mechanism (rfcs/done/124-worktree-ignore-mechanism.md), shipped in 0.29.0. It is documentation-only and adds no behavior: .prikkignore’s syntax, binding sites, and limits are exactly as ignore.rs’s own module doc records them.

Show

prikk show reports what one sealed block or one patch changed: each operation, its kind, the path(s) it affects, and the content it changed (RFC 142).

prikk show <block-id|patch-id> [--format json]

A patch is self-describing — the content is already in it. EditText carries the exact bytes replaced and their replacement; CreateFile/DeleteNode carry (or point to) the file’s content; RenamePath/ChangePerm/CreateSymlink carry everything they need inline. Nothing is replayed to find what changed.

A RenamePath also reports the AUTHOR key id that signed the patch asserting it — the signer is recoverable in the same answer as the rename itself, never a fact a caller has to look up separately. This is structural, not a rendering choice: show’s own read type cannot represent a rename without it, so a patch whose AUTHOR signature is missing fails the command rather than rendering a rename with no signer.

Three operation kinds — EditText, ChangePerm, ReplaceBinary — are node-addressed rather than path-addressed, so finding where they apply needs one replay of some lifecycle state — which state depends on what the target is (below). show pays that cost once per invocation, not once per operation, and there is no flag to skip it: a surface that named a 32-byte node id where a path belongs would have failed at the one thing it exists to do. If the state a node-addressed operation resolves against no longer has that node live — one patch that edits a node and then deletes it — the edit’s own path reports as unresolved rather than failing the command; every other operation still renders.

Which forms resolve a node-addressed path:

A block’s output is the union of its patches, in the block’s own canonical order.

Truncation matters, for a block’s own patches too, not only a queue. Every patch resolves against the state at that patch, not its block’s end: if a later patch in the same block renames a path an earlier one edited, or deletes the node an earlier one edited, the earlier patch’s own edit-text still names the path (or node) it had at the time — never the later name, and never unresolved_node_id just because a later patch in the same block went on to delete it. The block form folds a block’s own patches onto its parent’s state, and the queued form folds the active queue onto the sealed tip, through two different drivers — but both apply the same per-operation fold to resolve a path, so the answer is identical before and after seal by construction: sealing does not change what came before a given patch, only what comes after it.

show renders EditText’s own before/after span — it does not synthesize a unified diff. prikk’s edits are content-anchored spans, not line ranges, and a line-oriented rendering would assert a structure the format does not have.

ReplaceBinary and any binary-kind blob report their object id and declared size, never content — nobody has asked to see binary bytes in a terminal.

A content reference is an id, not a guarantee. CreateFile, DeleteNode’s file preimage, and both sides of ReplaceBinary name a blob by content-addressed id — and once a text file has been edited, its pre-edit identity is deliberately never written back to the object store (the content is reconstructed by replay instead). The exception is a checkpoint — a ref’s first sealed block, and every 64th block after it along its history — which stores the content of every file live at that block, edited or not, so content that was live at a checkpoint reports normally. If a referenced blob is simply absent from the object store, that one piece of content reports as unavailable — a named state carrying the blob id, distinct from real empty content — rather than failing the command. Every other operation in the block still renders, and the command still exits 0. This is not evidence of a damaged repository: the overwhelmingly common cause is a deleted file whose most recent edit made its old identity unbacked by design, and show cannot tell that specific case apart from any other blob that simply never made it into the store; a doctor-level surface wanting to would need to check independently whether the node’s own history includes an edit since that blob was last live.

Damage is different, and fails the command. If the object store reports something more specific than absence for a referenced blob — a content-hash mismatch, a stored type disagreement, a malformed payload, or a SNAPSHOT-kind blob named where file content belongs — that is the object store affirmatively reporting a problem, not an ordinary, by-design gap. show propagates it: the command fails (exit 1) with a message naming the integrity problem, rather than rendering the affected content as unavailable and exiting 0. Absence is ambiguous enough to degrade; a reported error is not.

show never fails because there was nothing notable to report: exit 0 covers every case the target resolves to, whether or not anything is unresolved or an absent content reference reports as unavailable. A malformed or missing id is a usage error (exit 2), a well-formed id naming no real block or patch is a failure (exit 1), and so is a referenced object the store reports as damaged rather than merely absent — an unavailable content reference never softens any of those, which stay what they were.

A queued patch can be shown before it is sealed. An id prikk status --format json lists under the queue — committed, not yet sealed — is looked up in the active WAL when the object store does not hold it, and renders exactly as it will once sealed — node-addressed paths resolved, from the folded baseline truncated at that patch (the table above) — plus a queued: yes line in prose and "queued": true on the patch in JSON (false for everything read from the object store, block or sealed patch alike). An id found in neither place is a precondition (exit 1) that names both places and where each kind of id is listed; it is not reported as damage.

Three things are easy to conflate, and show only ever speaks to the first: queued here means committed to this repository’s own local active WAL — not yet sealed, and never anything received from elsewhere; sync pending means a patch sync accept has already verified and stored from an exchange artifact, but not yet sealed into a block; and log means sealed, permanent history. All three are distinct states a patch passes through, never the same thing twice.

A rename names every signer. A patch may carry several AUTHOR signatures (format 7: another signer’s copy of the same patch merges in). A rename reports every one: prose lists them all on its asserted by line, and JSON carries author_key_ids, every signer in canonical order (key id bytes). author_key_id keeps its meaning — the first signer in that order — so a patch with one signer reports exactly as before.

--format json carries the same content as the prose form, as show-report-v1. It settles the format for show and nothing else.

Comparing two arbitrary points in history — not just one block or patch — means reconstructing both and comparing them, a materially more expensive operation show’s own cost model does not cover. That is a separate command: prikk diff replays both points (or one point and the worktree) and shows the difference as unified hunks. show still answers “what did this block or patch change”, from the patch’s own record.

Claim-to-Source Anchors

Provenance

This guide covers RFC 142’s show command. Comparing two arbitrary points in history, or a point with the worktree, is RFC 153’s prikk diff, a separate command with a materially different cost.

Reading a Point

A point is a place in history: a ref (heads/main, tags/v1, remotes/heads/main) or a bare block id, 64 lowercase hex characters, as prikk log prints it. Any block the repository holds is a point, including an older block on a branch and a block only received history reaches. Reading a point adopts nothing and trusts nothing (RFC 157).

prikk tree — the files at a point

prikk tree [path] [--ref <ref|block-id>] [--prefix <p>] [--format json]

tree lists every file present at the point, in canonical path order (byte order of the path). There are no directory entries: prikk records paths, not directories, so a directory is just the shared leading components of the paths under it.

tree repository: /path/to/repo/.prikk
ref: heads/main
target block: 7c1e…
entries: 3
  100755 text 18 run.sh
  100644 binary 240128 src/big.bin
  100644 text 1834 src/main.rs

Each line is the file’s mode (octal), its encoding, its exact size in bytes, and its path. With a block id the header reads block: <id> instead of ref: <name>.

• Encoding. text or binary, by the same classification checkout --patch-plan --format json --content-path reports. A file is text when it was committed as text.

• The mode is one number, shown two ways. The prose prints it octal, as ls -l and git ls-tree do (100644, 100755); the JSON prints the same number in decimal, as checkout already reports it (33188, 33261). 100644 octal is 33188 decimal — the two forms never disagree:

  file	prose	JSON mode
  an ordinary file	100644	33188
  an executable	100755	33261

  On Windows, expect 100644 for files committed there. Windows has no executable bit, so prikk cannot observe one: a file first committed on Windows is recorded 100644, and committing on Windows never changes a mode that history already records. That is a platform limit, not lost data. History committed on Linux or macOS still carries 100755 for its executables, and tree shows every recorded mode on every platform, so a Windows reader of that history sees 100755 where it was recorded. See Platform Support.

• Size is exact: a text file’s content is reconstructed by replay, and its length is counted, not estimated.

• --prefix <p> keeps the paths at or under p, by whole path components: --prefix src/ (or src) lists src/main.rs and never srcx/a.txt or src.rs. The replay is whole-tree either way, so a prefix shortens the output, not the work.

• Without --ref it lists the current branch. In a fresh repository whose branch has never been sealed, that is an empty listing with exit 0 — and naming that same branch explicitly with --ref answers exactly the same way, since the current branch is never absent, published or not. An explicit --ref naming any other absent name refuses with ref <name> does not exist in this repository.

• A received ref (remotes/…) lists like any other.

• Cost. One replay of the point, anchored at its nearest checkpoint, like checkout --patch-plan.

--format json: tree-listing-v1

{
  "schema_version": "tree-listing-v1",
  "point": "heads/main",
  "target_block_id": "7c1e…",
  "prefix": "src/",
  "entries": [
    {"path": "src/big.bin", "kind": "file", "encoding": "binary", "mode": 33188, "size": 240128, "content_id": "9f02…"},
    {"path": "src/main.rs", "kind": "file", "encoding": "text", "mode": 33188, "size": 1834}
  ]
}

• point is the point exactly as given; target_block_id is the block it resolved to, so a consumer can cache by block. For an unpublished current branch it is null, with no entries.
• prefix is --prefix exactly as given, or null.
• kind is file. (symlink is reserved for when replay supports symlinks; until then a history holding a symlink operation fails the whole call rather than listing part of the tree.)
• mode is the full file mode, the same number checkout reports (33188 is 100644, 33261 is 100755).
• content_id is present only for a binary file: its stored blob id. A text file never has one, even when a checkpoint happens to store its content, so a listing does not change with checkpoint cadence. Treat it as a cache hint, not as a way to fetch content.

prikk cat — one file’s bytes at a point

prikk cat --path <p> [--ref <ref|block-id>] [--output <file> [--force]] [--max-bytes <N>] [--format json]

cat writes the file’s bytes at the point — text and binary alike — to stdout, or to --output. It is the one command whose job is bytes: diff never prints binary content, and checkout --content-path reports text inside a plan.

prikk cat --path src/main.rs                      # to stdout
prikk cat --path src/big.bin --output ./big.bin   # to a file
prikk cat --path src/main.rs --ref <block-id>     # at an older block

• All or nothing. The content is resolved in full before one byte is written. A failure anywhere — an unsupported operation, damage, a bound — writes nothing at all.
• --max-bytes <N> refuses content larger than N, naming the size and the bound, and writes nothing, not even a partial file. Read exactly what it promises:
  • It bounds what is written — exactly, and all or nothing. When it refuses, nothing reaches stdout and no file is created or replaced.
  • It does not bound memory. cat reads the point through the same replay checkout --patch-plan uses, which holds every file’s content while it builds the tree, so a large file is already in memory when the bound is compared. Peak memory is that replay’s own cost, proportional to the size of the whole tree at the point, and --max-bytes does not lower it. A caller bounding hostile input gets a bound on the output, not on the process. A memory bound would need the replay to stream, which is planned separately (RFC 158) and not something cat can add on its own.
• --output <file> refuses an existing file unless you pass --force (bundle export’s own rule), and refuses any path inside .prikk/. The write goes to a temporary file beside the destination and is renamed into place, so a failed or interrupted write leaves the destination untouched rather than half written.
• Binary content never reaches a terminal. With stdout on a terminal, a binary file refuses and names --output; nothing is written. History from someone else must not be able to drive your terminal by being printed. Text goes to a terminal as-is, exactly as checkout would materialize it. Redirecting or piping stdout is not a terminal, so prikk cat --path src/big.bin > big.bin writes the bytes.
• A path that is not a file at that point — never existed, deleted by then, or a directory prefix like src — refuses with path <p> does not exist at <point>.

--format json: path-content-v1

{
  "schema_version": "path-content-v1",
  "point": "heads/main",
  "target_block_id": "7c1e…",
  "path": "src/big.bin", "kind": "file", "encoding": "binary", "mode": 33188, "size": 240128,
  "content_id": "9f02…"
}

No bytes. The fields are the same as one tree-listing-v1 entry, computed by the same code, so a consumer can decide between rendering inline and downloading — and show a size — before fetching anything.

When tree and cat refuse

• An absent ref (never the current branch, which is never absent, published or not), a block id the repository does not hold, or an id naming another kind of object: the point resolver’s preconditions, exit 1 — see Commands.
• A --ref value that is neither a ref name nor a block id, or a --prefix that is not a repository-relative path: usage, exit 2.
• An operation replay does not support, anywhere in the history: the whole call fails, and nothing is listed.
• Damage the store reports: integrity error. A binary file whose blob is missing or no longer recomputes fails the whole call, for tree and for cat alike: a state with a hole is not a state, so no entry is listed as unavailable and no partial listing is printed (RFC 157 §5a).

cat refuses the same things, plus a path that is not a file at the point, a --max-bytes bound the content exceeds, an existing --output without --force, an --output inside .prikk/, and binary content to a terminal.

Comparing: prikk diff

prikk diff shows what changed between two states, where a state is a point in history (a ref or a bare block id — see Reading a Point) or the worktree. It shows content: every text change as unified hunks, the way diff -u prints them.

prikk diff                                      # the worktree against the current branch: what `commit` would author
prikk diff --from <ref|block-id>                # the worktree against that point
prikk diff --from <ref|block-id> --to <ref|block-id>   # two points
prikk diff --path src/main.rs --path README.md  # only these paths in the output
prikk diff --format json                        # diff-report-v1

There is no fourth shape: a lone --to is a usage error (exit 2), because it names a right side and no left one. Compare two points with --from and --to, or a point with the worktree with --from alone.

What each side is

• A point is a ref — a received ref (remotes/…) too, read and not adopted — or a bare block id. --from heads/main --to <block-id> and --from <block-id> --to <block-id> are both fine, and a ref and the block it points at give the same answer.
• The worktree is what prikk commit would author, and the report is built from commit’s own rules so that it cannot disagree with the commit it predicts. Run prikk commit and then prikk diff: it is empty again.

That has consequences worth knowing:

• A new file is added, with its content. prikk has no index, and commit authors every worktree file .prikkignore does not exclude, so there is no separate “untracked” list here. A file that prikk worktree-status calls untracked is an added entry in prikk diff.
• Ignored paths never appear — as an entry or as anything else — and an ignore rule cannot hide a path that is already tracked: a tracked file that a later rule covers still shows its edits (Ignoring Worktree Paths).
• The left side of a bare diff is the current branch’s tip with its queued commits folded on top, because that is what commit authors against. The from: line says so when commits are queued and not yet sealed: from: heads/main (block 7c1e…, plus 2 queued commits not yet sealed). In JSON the left side carries queued_patches. --from <point> compares against that point exactly, queue or no queue.
• A fresh repository — a current branch that has never been sealed — has the empty state on the left: every file commit would author is added, and the exit code is 0 (from: heads/main (not published: the empty state)) — the current branch is never absent, published or not, so naming it explicitly with --from refuses no more than leaving --from off does. A queued, unsealed commit is where the two forms part ways, by the same rule as the previous bullet: the bare left side folds the queue on top of the empty state (a queued file reads as already there, unchanged); --from heads/main compares against the empty state exactly, queue or no queue, so a queued file reads as added there instead. --from naming any other ref that does not exist refuses.
• It writes nothing. No lock, no cache, no index, no marker: prikk diff reads. It works while another process holds the active lock, and while the worktree is provisional (materialized from a snapshot and not yet verified) or an interrupted materialization left its marker — states in which commit refuses. It does not clear either marker. In an interrupted-materialization state, a file the interrupted write never created reads as deleted, which is what commit would have signed; that is the reason commit refuses there.

Statuses

Each differing path has one status, in canonical path order. A path that is the same on both sides is not listed.

diff repository: /path/to/repo/.prikk
from: heads/main (block 7c1e…)
to: worktree
entries: 3
modified src/main.rs
--- a/src/main.rs
+++ b/src/main.rs
@@ -10,7 +10,7 @@
 …three lines of context…
-    let old = 1;
+    let new = 2;
 …three lines of context…
renamed docs/old.md -> docs/new.md
added notes.txt
--- /dev/null
+++ b/notes.txt
@@ -0,0 +1 @@
+a new file

Hunks, and patch

Text changes are unified hunks with 3 lines of context, headed by the ---/+++ lines patch(1) reads (/dev/null on the side that has no file). A last line without a newline is marked \ No newline at end of file, exactly as diff -u marks it, and a line ending in \r\n is a different line from one ending in \n. Applying an entry’s hunks to its left content reproduces its right content byte for byte, on Windows as everywhere; patch on Unix applies the printed text.

Renames are declared, never guessed

A renamed entry exists only where history (or a live prikk mv on the worktree side) declares a rename. Deleting a file and creating another with the same bytes is a deleted and an added, never a rename: nothing here infers one from similar content. A rename is the same file at a new path, so:

• a chain of renames a → b → c is one renamed entry from a to c, whatever the two points are;
• a file deleted and then created again — at its old path or at another — is a different file, so it is never renamed: at a new path it is deleted plus added, at the same path it is modified;
• a rename that also changes the content shows its hunks.

--path selects a renamed entry by either its old or its new path.

With --from <a point on another branch>, the worktree side takes node identity from the current branch’s baseline, so a rename is paired only where the two agree: across branches, read a deleted plus an added as “these two paths were not paired here”, not as “no rename was declared”.

Binary files

A binary entry shows the size of each side and an id — and never a byte. The prose names prikk cat for reading a side, with the block each side resolved to rather than the name you gave (a ref may move before you run the command). The worktree side has no block: it is the file itself. The left side of a bare diff with queued, unsealed commits has no block either — it is the sealed tip plus that queue, a state no block names — so no --ref line is printed for it; the prose instead says the side “can be read only after prikk seal”. For a binary file on the worktree side, the id is the one the file would have once committed. content_id exists for binary files only, exactly as it does in prikk tree: a text file is its own content.

Paths commit refuses

Some worktree entries commit cannot author: a symlink (Unix), a FIFO or socket, a name that is not a safe repository path, an existing text file whose content is no longer valid UTF-8. prikk diff names each one, once, with the refusal commit prints for it, and shows no content:

unsupported paths: 1
  link: precondition not met: link: worktree symlink authoring is out of scope

A tracked file replaced by a symlink is named here and is not also reported deleted. The rest of the diff is still shown. unsupported_paths is always empty between two points; only the worktree form fills it.

A live prikk mv that commit would refuse (both paths present, say) refuses the diff too, with commit’s own message and nothing on stdout: there is no honest answer to what a commit that cannot happen would author.

The cost, and the bound on the line diff

Two points cost two anchored replays, as checkout --patch-plan does. The worktree costs one read of the baseline plus a read of every worktree file, as worktree-status does, and materializes the baseline text of the files that changed only. --path filters the output; it does not shrink the work.

The line diff finds the shortest edit script within a work bound: 45,000,000 search steps for one file (a step is one diagonal visited or one line followed inside the search, so the bound counts work, never time, and is the same on every machine). Almost every diff finishes far inside it. Two large files that share many lines in very different orders — a file with its lines reversed, say — can reach it; the search then stops and the region it had not resolved is shown as deleted and re-added. The hunks are larger than the shortest, and they still apply: applying them reproduces the right side byte for byte.

You are always told. Every entry in --format json has a minimal boolean — true when its script is the shortest, false when the bound engaged — and the prose puts a note: not the shortest edit script line under that entry’s header. The same two inputs give the same output on every run and every machine.

--format json: diff-report-v1

{
  "schema_version": "diff-report-v1",
  "from": {"point": "heads/main", "target_block_id": "7c1e…", "queued_patches": 0},
  "to": {"point": "worktree", "target_block_id": "worktree"},
  "entries": [
    {
      "path": "docs/new.md",
      "status": "renamed",
      "from_path": "docs/old.md",
      "from": {"kind": "file", "encoding": "text", "mode": 33188, "size": 812},
      "to": {"kind": "file", "encoding": "text", "mode": 33188, "size": 830},
      "minimal": true,
      "hunks": ["@@ -3 +3 @@\n-old\n+new\n"]
    }
  ],
  "unsupported_paths": [{"path": "link", "refusal": "precondition not met: link: worktree symlink authoring is out of scope"}]
}

• from / to — point is how the side was named: a ref, a block id, or worktree. target_block_id is the block it resolved to; for the worktree it is the string "worktree"; for the current branch of a fresh repository (the empty state) it is null. queued_patches appears only on the implicit left side of a bare diff: how many unsealed commits were folded on top of that block.
• entries — canonical path order. path is the right side’s path (the left’s for a deletion); from_path is present for a rename only. from and to are the fields a tree-listing-v1 entry carries (kind, encoding, mode, size, and content_id for binary), emitted by the same code; the path is the entry’s own. A side is absent when the path is not there (added has no from, deleted no to). content_id appears for binary sides only. hunks is a list of strings, each starting at its @@ line and ending in a newline; empty for a binary, mode-only or content-identical entry. minimal is always present.
• unsupported_paths — objects with path and refusal, in path order; empty between two points.
• No untracked list. A new worktree file is an added entry.

diff-report-v1 settles the format for diff and nothing else.

When diff refuses

• An absent ref, or a block id the repository does not hold — precondition, exit 1: ref heads/x does not exist in this repository, block <id> is not in this repository. An id naming a patch, not a block, refuses too. The current branch is never absent when it is the worktree’s baseline (--from alone, or left off); named as one side of two points with --to, it refuses exactly like any other unpublished ref.
• A value that is neither a ref name nor a block id, a --path that is not a repository-relative path, a lone --to, a repeated flag — usage, exit 2.
• An operation replay does not support, anywhere in either history — the whole call fails, and nothing is printed.
• A blob that is missing or no longer recomputes — fails the whole call as integrity error: a comparison with a hole in it is not a comparison, so no entry is shown as unavailable (RFC 157 §5a).
• A live rename declaration commit would refuse — the same message commit prints.

Claim-to-Source Anchors

Checkout Planning

PR-017 includes a read-only checkout plan:

prikk checkout --plan-only [path] [--ref heads/main]

The command resolves the current RefState to its Block and reports whether checkout would need snapshot materialization or patch application.

--ref takes any published ref, not only a branch: a tag ref resolves through its tag object to the Block that object names, so --ref tags/v1 plans against the tagged Block rather than the branch tip. That applies to --patch-plan and its --content-path reporting too.

The read-only modes — --plan-only, --snapshot-plan, --patch-plan (with or without --content-path) and --patch-delete-plan — also take a bare block id, as log prints it. Any block the repository holds resolves, including an older block on a branch, so two blocks on one ref can be read side by side:

prikk checkout --patch-plan --format json --content-path a.txt --ref <block-id>

A block id replays exactly as a ref naming the same block does, from the same checkpoint. The prose header then reads block: <id> instead of ref: <name>. An id the repository does not hold refuses with block <id> is not in this repository; an id naming another kind of object refuses naming its type, for example object <id> is a patch, not a block. The modes that write the worktree refuse a block id, because the next commit authors against a branch and a block id names none.

For snapshot-backed blocks, first validate the snapshot manifest:

prikk checkout --snapshot-plan [path] [--ref heads/main]

Then explicitly materialize validated snapshot files:

prikk checkout --snapshot-materialize [path] [--ref heads/main]

A refused checkout writes nothing

--patch-materialize, --patch-materialize-delete and --snapshot-materialize check every file they would write before writing any. An existing file with different content, a directory or other non-file at a path, or a symlinked parent directory is a conflict, and a conflict refuses the whole checkout:

error: precondition not met: refusing to materialize: 2 path(s) in the way: dev-only.txt (an existing file with different content), shared.txt (an existing file with different content); move them aside, or commit them on their own branch, and run the checkout again (nothing was written)

Every conflicting path is named, not only the first. Nothing is written, no marker is set, and commit keeps working. --patch-materialize-delete likewise refuses, naming each file, when a file it would delete has changed. See troubleshooting for the one case that still leaves a worktree part-written.

Snapshot materialization writes only validated regular files. Supported patch replay and materialization are available through --patch-plan, --patch-materialize, and --patch-materialize-delete, but full patch algebra remains deferred. For the shared path and worktree safety boundary, see the path and worktree safety reference.

Snapshot Checkout Planning

PR-017 keeps a read-only snapshot checkout planning path.

The command:

prikk checkout --snapshot-plan [path] [--ref <ref|block-id>]

validates the current ref, target block, snapshot Blob object, and snapshot manifest paths. It does not write the worktree.

The current path-safety scaffold is deliberately conservative. It rejects:

• absolute paths
• . and .. components
• empty components
• backslashes and colon characters
• control characters
• Windows reserved names such as CON, NUL, COM1, and LPT1
• non-ASCII paths until Unicode NFC normalization is implemented
• duplicate paths and case-insensitive collisions

Use prikk checkout --snapshot-materialize to write validated snapshot files. Supported patch replay is available separately, while full patch algebra remains deferred. For exact validator rules, see path and worktree safety.

Snapshot Materialization

PR-017 adds an explicit, opt-in snapshot materialization path:

prikk checkout --snapshot-materialize [path] [--ref REF]

The command writes files only from a validated snapshot manifest. It does not apply patch algebra and does not remove extra files. Before writing anything it checks every file it would write: an existing file with different content, a non-file at a path, a symlink target or a symlinked parent directory is a conflict, and any conflict refuses the whole checkout with every such path named and nothing written (see checkout). So snapshot checkout cannot be used to write outside the repository worktree.

A snapshot worktree is provisional until prikk verify

A snapshot proves only that its files match the state root its block signs. It does not prove that replaying the history before that block produces the same files: only replay proves that, and only prikk verify replays the whole repository. So a worktree written from a snapshot is provisional.

• The marker. Before its first write, checkout --snapshot-materialize records the ref and the snapshot’s block in .prikk/worktree.provisional. A crash after that point leaves the marker set.
• The derivation gate. While the marker is set, every command that would turn the worktree, or the repository’s current state, into history refuses as a precondition and names the route: commit, mv, seal, merge, sync accept, sync seal, rollback-draft --append-inverse and branch switch. Reading commands, checkout --patch-*, tag create, branch create/close, trust and bundle stay available.
• Clearing it. Run prikk verify. The marker clears when verify finds nothing about objects, the WAL, refs or block state. A publication-trust finding alone does not keep it: who signed a block says nothing about whether replay reproduces the snapshot. A materialization that runs while verify is running keeps its marker, and verify says so.
• When no marker is written. If this repository has already confirmed the block’s state by replay and an adopted maintainer signed the block, the snapshot’s files are exactly what replay gives, so --snapshot-materialize writes no marker and prints provisional: no. Otherwise it prints provisional: yes and the marker applies. A block is confirmed when seal, merge or sync seal sealed it or replayed it as part of its parent history, or when prikk verify replay-verified it. Receiving a block (bundle import, sync accept) never confirms it. “Adopted” means a signature by a key in prikk trust maintainer list that verifies: a block signed by a key this repository has not adopted is provisional however the record came to list it. If a recorded block’s manifest fails validation, or its signature does not verify against an adopted key, the command also says so on stderr, naming the block.
• The record. Those confirmed block ids live in .prikk/cache/replay-verified-blocks.v1. It is a cache, never authoritative, and never enough by itself: a damaged, truncated or other-version file reads as empty, deleting it is always safe, and a line written into it by hand makes no snapshot trusted, because a block must also carry a verifying signature by an adopted key. Without it, every snapshot materialization is provisional and every worktree write replays from genesis, until seal or verify records the blocks again. verify adds every block its own replay confirmed to this record regardless of what else that run found — even a run that exits 1 on a publication-trust failure still records what it replayed. So adopting the maintainer key afterward is enough on its own: the record already has the block, the adopted-key check beside it is re-evaluated fresh every time rather than frozen into what was recorded, and no second verify run is needed before the checkpoint becomes usable. The record is keyed to the repository’s own relative layout, not to an absolute path, so moving the repository’s directory leaves it intact. A fresh receive or a freshly restored repository has simply never had seal or verify run against it locally, so the file starts empty rather than resetting — neither operation clears it.
• Where it shows. prikk status prints provisional worktree: materialized from the snapshot of <block> on <ref>; not replay-verified — run prikk verify, status --format json carries provisional_worktree, and prikk doctor lists PRIKK-DOCTOR-PROVISIONAL-WORKTREE.

Reports that start at a snapshot

checkout --patch-plan (prose and --format json, including --content-path), checkout --patch-delete-plan and bundle preview only read, so they may start at the nearest valid snapshot on the ref’s history instead of genesis. Their output is byte-identical either way: the file manifest comes from the snapshot, and everything about history — patch and operation counts, coverage, files history deleted — is still computed over the whole chain. A snapshot that fails validation is never used: the report replays from genesis, prints the same output, exits 0, and adds one line on stderr naming the block and prikk verify.

Commands that write the worktree — checkout --patch-materialize, --patch-materialize-delete and branch switch — start at a snapshot only when its block is in the record above, carries a maintainer signature by an adopted key that verifies, is at most 63 blocks back from the tip, and the snapshot passes validation; otherwise they replay the whole history. A received block’s snapshot is never a starting point for a worktree write. The written files are identical either way. rollback-preview always replays the whole history.

The path validator remains conservative: non-ASCII paths are deferred until Unicode NFC normalization is implemented, and paths targeting .prikk/ are rejected. For the exact validator and write-safety caveats, see path and worktree safety.

Worktree Patch Authoring

prikk commit authors the current worktree into a node-addressed patch and appends it to the active WAL. The patch carries a real role-bound Ed25519 AUTHOR signature.

# Key material is supplied via the environment (a minimal key-input mechanism, not a trust store):
export PRIKK_AUTHOR_KEY_ID="dev-author"
export PRIKK_AUTHOR_SEED_FILE="<path to a 0600 seed file>"   # or leave unset to use ~/.config/prikk/author.seed

prikk commit -m "record changes"
# --text-edits is accepted for compatibility; text nodes author EditText either way:
prikk commit --text-edits -m "record text changes"
# Explicit unborn local branch genesis:
prikk commit --ref heads/topic -m "start topic"

--from-worktree is still accepted for backward compatibility but is now the only behavior, so it can be omitted.

Baseline

Authoring compares the worktree against a baseline node lifecycle state:

• Published ref: the baseline is reconstructed from authoritative node-addressed replay of the heads/main (or --ref) lineage — never from a snapshot manifest.
• Genesis (fresh local branch): when a valid heads/* target ref has never been published, the first commit authors against an empty baseline, so every worktree file becomes a CreateFile. The following seal --ref heads/<branch> publishes the first block as a Root block.

commit --ref heads/topic on an unborn ref creates an independent Root history from the current worktree. It does not copy/fork heads/main, switch the checkout branch, or create a merge base.

The active WAL queues commits until seal, up to the queue limit described in the FAQ. The active WAL records the one ref it belongs to, and a commit for a different ref is refused while the queue is non-empty, so seal --ref heads/main cannot publish a patch authored for heads/topic (crates/prikk-store/src/commit_boundary/active.rs:301-314).

Operation mapping

Existing-node kind is authoritative:

• new file → CreateFile (fresh CSPRNG-minted node_id, normalized mode)
• removed tracked file → DeleteNode
• modified text file → deterministic arbitrary-span EditText
• modified binary file → ReplaceBinary
• permission-only change → ChangePerm

Path handling is strict: non-UTF-8 worktree paths fail closed, and traversal/reserved-name/collision rules apply as elsewhere. For the exact repository path and worktree scanner boundary, see path and worktree safety. A path matched by a .prikkignore rule at the repository root is skipped by this scan entirely — never authored, never reported — see Ignoring Worktree Paths.

Out of scope (this stage)

• symlink authoring (fails closed on all symlinks)
• text↔binary kind transitions (fail closed)
• rename detection (a move is a DeleteNode + CreateFile)
• branch switching or branch copy/fork from an existing tip
• multi-commit queued active sessions or per-ref active WALs
• multi-operation text diff minimization, commutation, conflict witnesses

Signature scope: worktree commits are role-bound Ed25519 AUTHOR-signed. This does not imply trust-store enforcement, key management, MAINTAINER/publication signing, rollback authorization, or publication-grade repository trust.

Content-Anchored Text Edits

DC-12 supports deterministic arbitrary-span EditText generation and replay for existing text-file nodes. A modified text file is represented as one enclosing span selected by byte LCP/LCS and widened to UTF-8 character boundaries. The record remains the FDD-03 node-addressed, span-anchored EditText shape; no offsets or new identity fields are added.

Author text edits from worktree changes with:

prikk commit --from-worktree --text-edits -m "record text changes"

--text-edits is retained for compatibility. Existing-node kind is authoritative, so text-file modifications author EditText and binary-file modifications author ReplaceBinary.

Generation and replay remain conservative:

• Only modified tracked files are candidates.
• Both baseline and current bytes must be valid UTF-8.
• Text edits use a single deterministic enclosing span; multi-operation diff minimization is deferred.
• Byte-level differences that split a multibyte character are widened to the enclosing UTF-8 character.
• Binary or invalid UTF-8 modifications fail closed for text nodes; they do not become ReplaceBinary.
• Replay localizes by old_span_text, left/right anchor hashes, and span_id, then splices exactly.

This deliberately avoids byte offsets and line offsets. Presentation offsets may be derived later, but they are not part of patch identity or replay preconditions.

Current validation rules:

• old_span_hash is exactly 32 bytes.
• old_span_hash must equal text_span_hash(old_span_text).
• old_span_text and replacement_text must be well-formed UTF-8.
• The target node_id must name a live TextFile during replay.

Deferred work:

• multi-operation text diff minimization
• direct inverse and rollback extension for arbitrary spans
• commutation and conflict witnesses

Declared Move and Rename Authoring

prikk mv <old> <new> is the first prikk command that authors a RenamePath operation. Renames are never inferred from content — comparing bytes to guess “this looks like that file, renamed” is not something prikk does. A rename only ever comes from an explicit declaration.

prikk mv old-name.txt new-name.txt

This both performs the move on disk and records a declaration. The declaration is durable, kept alongside the active queue, and is authored into the next prikk commit — not immediately.

The four worktree states

prikk mv keys its behavior on existence only, never on content:

The second row is what makes the command useful for the ordinary flow of running a shell mv and only afterward remembering to tell prikk about it:

mv old-name.txt new-name.txt   # already moved by hand
prikk mv old-name.txt new-name.txt   # records the declaration; touches no bytes

Reviewing a live declaration before committing

A declaration made and forgotten becomes permanent history at the next commit. prikk worktree-status shows every live declaration, in prose and in --format json:

prikk worktree-status

live rename declarations: 1
  old-name.txt -> new-name.txt [rename]
refused declarations: 0

Each line says what the next commit will do with that declaration, from the same classifier commit obeys — rename, deletion, deletion-ignored, never-tracked, or refused with commit’s own message. A rename also says when content or mode changes alongside it ([rename] (content also changes)), because commit authors those in the same patch. In --format json the fields are resolution, refusal, content_changed and mode_changed, plus a top-level refused_declaration_count. See Worktree Status.

What a commit does with a live declaration

prikk commit consumes every live declaration against the worktree at commit time:

• Confirmed (old path absent, new path present): authors a RenamePath. Any simultaneous content or mode change on the same node is authored alongside it in the same patch.
• Nets to deletion: if the declared destination is no longer a file at commit time — deleted, replaced by a directory, or excluded by .prikkignore — the declaration is dropped and a plain deletion is authored instead, never a rename to nowhere. The disclosure names which: destination is gone, destination is a directory, or destination is ignored. A directory is only ever reported as ignored when .prikkignore really excludes it.
• Not a regular file: a symlink, FIFO or socket at the destination still resolves rename — and commit refuses over that path, as it does for any such entry in the worktree. worktree-status never opens it, so content_changed and mode_changed are null for it.
• Never tracked: if the declared source was never a sealed node (an untracked file, moved with prikk mv before its first commit), there is no node to rename.
• Contradicted: if the worktree disagrees with the declaration (the source path is back on disk), the whole commit is refused, naming the declaration. Nothing is silently dropped. The refusal names the way out for the state the worktree is actually in, and every route it names was measured:
  • the source is back and the destination is gone (a shell mv undid the move): prikk mv <new> <old> nets the declaration to no move and drops it, or prikk mv <old> <new> makes the move again. Undoing it with a shell mv is what produced this state, so repeating that is the one thing that does not help.
  • both paths exist: prikk mv itself refuses while both are there, so set one copy aside first — delete the old path and commit to author the rename, or delete the new path and then run prikk mv <new> <old> to drop the declaration.
  • the destination is another tracked node this commit does not also move: prikk mv <new> <old> drops the declaration; the old path keeps its content and the destination stays deleted in the worktree, so the commit authors that deletion.

Every one of these outcomes is correct on its own — a deletion really is the honest record for a file moved into an ignored directory, for instance. What would be wrong is doing this silently: a user who asserted a move deserves to see what actually happened to it. So prikk commit names every declaration that did not become the rename it asserted, one line each, alongside the operations it authors:

$ prikk mv a.txt build/a.txt        # build/ is excluded by .prikkignore
moved a.txt -> build/a.txt
$ prikk commit -m moved
  delete-file a.txt
  declaration a.txt -> build/a.txt: destination is ignored; recorded as a deletion, not a rename

Renaming a node more than once before a commit collapses to the net move: prikk mv a b followed by prikk mv b c authors exactly one RenamePath, a -> c — never two hops. A declaration that returns to its starting point (prikk mv a b then prikk mv b a) is dropped entirely; nothing is authored — and prikk mv says so immediately, since the round trip is resolved right there, not at the next commit:

$ prikk mv a.txt b.txt
moved a.txt -> b.txt
note: this declaration is authored into the next `prikk commit`; see `prikk worktree-status` to review it first
$ prikk mv b.txt a.txt
moved b.txt -> a.txt
declaration a.txt -> b.txt -> a.txt: nets to no move, dropped

The commit-time hint — a suggestion about what you didn’t declare

If you move a file with a plain shell mv and never tell prikk, commit sees an ordinary delete and an ordinary create — nothing tells you identity could have been preserved. commit may print a hint for that:

$ mv old-name.txt new-name.txt      # a shell mv, not prikk mv -- never declared
$ prikk commit -m moved
  delete-file old-name.txt
  create-file new-name.txt
hint: looks like old-name.txt moved to new-name.txt; `prikk mv` would have preserved its identity

The hint and a disclosure line look deliberately different, on purpose, because they mean opposite things — one is a fact about something you asserted, the other is a guess about something you didn’t:

  declaration a.txt -> build/a.txt: destination is ignored; recorded as a deletion, not a rename
hint: looks like old-name.txt moved to new-name.txt; `prikk mv` would have preserved its identity

A disclosure line is indented like the operations above it, past tense, and says what did happen to something you declared. A hint is unindented, conditional (“would have”), and says what might have been true of something you never declared at all — the same shape as this guide’s own “note:” lines, not the operation list.

The hint authors nothing. It costs a line of output, never a fact in history, which is exactly why it is allowed to be wrong. It never prompts and never blocks, and there is no flag to make it a default — the machine suggests, you assert, always with prikk mv itself.

The signal is exact content equality only — never similarity scoring, and never anything cleverer. A few cases the signal alone would get wrong are handled directly:

• A declared move never triggers it. prikk mv already authored a RenamePath; there is nothing left to suggest.
• An ambiguous set prints no hint. Two deleted files and two created files sharing identical content — which moved to which is unknowable, and a wrong guess is worse than silence.
• A mass reorganisation prints one summary line, not a wall of hints, once a commit’s own unambiguous candidates pass a small threshold.

Two nodes can be swapped in one commit by chaining declarations through a temporary name:

prikk mv a.txt tmp.txt
prikk mv b.txt a.txt
prikk mv tmp.txt b.txt
prikk commit --from-worktree -m "swap a.txt and b.txt"

What this does not do (yet)

• No similarity scoring in the commit-time hint above — exact content equality only, and nothing cleverer.
• No conflict witness for two declarations naming the same destination.
• Symlink renaming is out of scope, the same as symlink authoring generally.

Supported Patch Replay Planning

Read-only patch replay handles the current conservative operation subset, including DC-12 arbitrary-span text edits.

The command is:

prikk checkout --patch-plan [path] [--ref <ref|block-id>]

It walks the single-parent block chain from oldest to newest, loads any snapshot Blob attached to a block, and applies supported Patch operations in block patch order.

Supported operations:

• CreateFile
• DeleteFile
• EditText for deterministic content-anchored arbitrary spans
• ReplaceBinary (DC-73)
• ChangePerm (DC-73)
• RenamePath, authored by commit from a prikk mv declaration; one patch’s consecutive renames replay as one batch

Unsupported operations still fail the plan clearly:

• CreateSymlink — not a node-model gap: symlink authoring is refused outright
• merge/conflict algebra

This command does not write the worktree. It only proves that the current sealed history can be replayed into an in-memory snapshot manifest using the operation subset implemented so far.

Content at a point (RFC 143)

The replay above already reconstructs every file’s bytes internally, then discards them once the plan is proven. --format json exposes those bytes instead, for exactly the paths you name:

prikk checkout --patch-plan --format json --content-path <repo-relative path> [--ref <ref|block-id>]

--content-path is repeatable and required for --format json to report anything — there is no whole-tree default. A requested path that never resolved in the replay degrades to not_found (not an error); an unsupported operation anywhere in the walked chain still fails the whole call, never folds into a partial-but-successful response. A bare --format json with no --content-path reports metadata only — an empty content and not_found, a populated coverage — since there is nothing to scope content to and nothing to guess at.

patch-plan-content-v1’s coverage field is not a completeness promise: it names which operation kinds this specific replay actually applied (create-file, delete-file, edit-text, replace-binary, change-perm) and that the walk was single-parent — the same conservative subset --patch-plan supports above, not a claim that every operation kind in history is covered. RenamePath and CreateSymlink still fail the call outright, exactly as they fail the read-only replay itself.

Binary content is never emitted as bytes: a BinaryFile node reports its current blob id and declared size only. A path that a snapshot seeded but the replayed chain never subsequently touched has no way to know its own text-vs-binary kind — snapshots carry no kind field — so it reports as opaque (size only) rather than guessing.

This surface exists to let another tool compare two replayed points without prikk owning comparison semantics itself — prikk still has no diff, and this does not add one. See show for the sibling case: one block or patch’s own recorded content, no replay needed for path-addressed operations.

Supported Patch Materialization

PR-021 added an explicit materialization command for the supported patch replay result:

prikk checkout --patch-materialize [path] [--ref REF]

This command reuses the read-only replay support from checkout --patch-plan and writes the resulting file manifest into the worktree through a conservative, mode-aware materializer. It is a separate code path from snapshot checkout’s materializer (DC-73): the replayed manifest carries mode bits derived from CreateFile/ChangePerm history, which the snapshot-blob wire format does not encode, so the two are deliberately not unified.

PR-022 adds deletion-aware materialization as a separate opt-in command:

prikk checkout --patch-materialize-delete [path] [--ref REF]

Supported operation subset:

• CreateFile
• DeleteFile
• deterministic arbitrary-span EditText
• ReplaceBinary (DC-73)
• ChangePerm (DC-73) — the mode bit is written, not only the content
• RenamePath (RFC 144 increment 1) — the node’s content is written at its new path; a rename in one patch that swaps two files is applied as one step

Safety boundaries:

• Existing files with identical bytes and mode are left unchanged.
• Existing files with different bytes are refused.
• Existing files with identical bytes but a different mode have their mode corrected in place.
• --patch-materialize never deletes files.
• --patch-materialize-delete deletes only files explicitly removed by replayed DeleteFile operations.
• Deletion is refused unless the current worktree bytes still match the old Blob precondition.
• Extra untracked files are never deleted.
• Symlinked parents, symlink targets, non-file targets, and .prikk/ metadata paths remain refused.
• Neither mode removes a renamed file’s old path from the worktree: --patch-materialize never deletes, and --patch-materialize-delete removes only files a DeleteFile removed.
• Symlinks, merge conflicts, and full patch algebra remain later increments. commit refuses a symlink outright, so there is nothing in ordinary history for materialization to act on (DC-73).

This command is useful for exercising the current Prikk object/WAL/ref/block pipeline end-to-end, but it is not yet a complete checkout implementation. For the shared write-safety boundary and its race caveats, see path and worktree safety.

Supported Patch Deletions

PR-022 adds an explicit deletion plan for the supported patch replay result:

prikk checkout --patch-delete-plan [path] [--ref <ref|block-id>]

It also adds an opt-in materialization mode that removes eligible files:

prikk checkout --patch-materialize-delete [path] [--ref REF]

Deletion is intentionally narrow. Prikk deletes only files that the replayed patch chain removed with a DeleteFile operation. Before removing a worktree file, Prikk checks that the current file bytes still match the operation’s old Blob precondition.

Safety boundaries:

• Arbitrary untracked files are never deleted.
• Modified deleted files are refused.
• Symlink targets and non-file targets are refused.
• General checkout pruning remains deferred.
• The replay this plan reads applies text edits, renames and mode changes, as --patch-materialize does, but only a DeleteFile makes a file eligible for deletion: a renamed file’s old path is never deleted.
• Symlinks, merge conflicts, inverse logic, and full patch algebra remain later increments.

For exact deletion and materialization safety boundaries, see path and worktree safety.

Supported Patch Inverse Planning

PR-026 adds read-only inverse planning for the supported patch-operation subset.

prikk inverse-plan [path] [--ref REF]

--ref takes any published ref, not only a branch. A tag ref resolves through its tag object to the Block that object names, so prikk inverse-plan --ref tags/v1 plans the inverse of the tagged Block’s patch, which need not be the branch tip. The same is true of prikk rollback-preview and prikk rollback-draft-verify, which reach the same resolution. prikk rollback-draft --append-inverse still requires a branch ref: it appends to that ref’s active WAL, and a tag names no WAL.

The command walks the same single-parent sealed block chain used by supported patch replay. While validating and replaying the chain, Prikk derives an unsigned inverse Patch payload in reverse application order.

Supported inverse shapes in PR-026:

• CreateFile → inverse DeleteFile
• DeleteFile → inverse CreateFile

Safety boundaries:

• The command is read-only.
• The inverse Patch is not written to the object store.
• The reported inverse Patch ID is only an unsigned deterministic planning hint.
• EditText direct inverse for arbitrary spans remains deferred until the required round-trip vectors land.
• Rollback refs, authorization policy, conflict witnesses, commutation, and confluence remain later increments.

Rollback Preview

PR-027 adds a non-mutating rollback preview for the supported patch-operation subset.

The command is:

prikk rollback-preview [path] [--ref REF]

--ref takes any published ref, not only a branch — a tag ref resolves through its tag object to the Block it names, so --ref tags/v1 previews the rollback of the tagged Block. See inverse planning, which shares the resolution.

The preview performs two read-only validations:

1. derive the unsigned inverse Patch payload for the supported operation subset;
2. replay the current target state from the supported single-parent block chain.

It then compares the current replayed state with the empty state before the replayed chain: rollback reaches back to the chain’s first block, and a checkpoint snapshot never moves that target. The result is a file-level preview of what rollback would need to create, delete, or replace.

No repository state is changed. The command does not write objects, append WAL records, publish refs, or modify the worktree.

Supported operation subset:

• CreateFile
• DeleteFile
• deterministic arbitrary-span EditText
• ReplaceBinary (DC-73)
• ChangePerm (DC-73)

Deferred:

• mutating rollback commands
• rollback ref publication policy
• authorization and audit policy for rollback
• commutation, confluence, and conflict witnesses
• plugin execution and remote sync

Rollback Draft

prikk rollback-draft appends an explicit rollback-draft Patch for the supported patch-operation subset.

The command is:

prikk rollback-draft --append-inverse [path] [--ref REF] -m "rollback message"

The command performs the same supported inverse validation used by inverse-plan and rollback-preview, marks the inverse Patch payload as PatchPurpose::RollbackDraft, signs it with a real role-bound Ed25519 AUTHOR signature, then appends the Patch envelope to the active WAL. Key material uses the same key material as prikk commit: the AUTHOR seed from your key directory (or PRIKK_AUTHOR_SEED_FILE), with PRIKK_AUTHOR_KEY_ID naming the key id.

Safety rules:

• --append-inverse is required.
• -m <message> is required and must not be empty.
• the target ref must be published and must resolve to a supported single-parent block chain.
• the supported replay/inverse subset must validate successfully.
• the active WAL must be empty.
• the active WAL must not contain a trailing partial record.

What it mutates:

• appends one AUTHOR-signed rollback-draft Patch envelope to .prikk/active/default/queue.wal.

What it does not mutate:

• it does not write object files directly.
• it does not publish refs.
• it does not modify the worktree.
• it does not authorize rollback by policy.

PR-029 adds a pre-seal verification command:

prikk rollback-draft-verify [path] [--ref REF]

After reviewing and verifying the draft, the existing local seal scaffold can publish it:

prikk seal --allow-no-audit

The seal path is unchanged, but prikk log and prikk verify classify the sealed Block as a rollback Block when it contains Patch objects with PatchPurpose::RollbackDraft.

Supported inverse operation subset:

• CreateFile -> DeleteFile
• DeleteFile -> CreateFile
• deterministic arbitrary-span EditText -> EditText
• ReplaceBinary -> ReplaceBinary (old/new blob swapped; DC-73)
• ChangePerm -> ChangePerm (old/new mode swapped; DC-73)

Deferred:

• RenamePath inverse — commit authors RenamePath from a prikk mv declaration, but inverse planning for it is not implemented: rollback-preview and rollback-draft on a ref whose tip patch is a rename refuse with error: unsupported object type: inverse planning for RenamePath awaits a rename authoring path (DC-73)
• CreateSymlink inverse — not a node-model gap, an authoring one: symlink authoring is refused outright, so there is nothing in ordinary history for it to act on (DC-73)
• rollback-specific ref publication policy
• authorization and audit policy for rollback
• rollback branch/reflog semantics
• worktree rollback materialization policy
• commutation, confluence, and conflict witnesses
• plugin execution and remote sync

Rollback Draft Verification

prikk rollback-draft-verify is a non-mutating verification step for rollback drafts that are waiting in the active WAL.

prikk rollback-draft-verify [path] [--ref REF]

The command verifies that:

• the active WAL has no trailing partial record;
• the active WAL contains exactly one record;
• the record is a Patch envelope;
• the Patch payload carries PatchPurpose::RollbackDraft;
• the Patch carries an AUTHOR signature and reports its real key id;
• the Patch payload decodes under the currently supported replay subset;
• the Patch payload exactly matches the inverse Patch currently derived from the selected ref.

This makes the rollback draft path easier to audit before seal --allow-no-audit publishes the active WAL into a block.

Repository verification integration

prikk verify also counts active WAL records classified as rollback drafts. For those records, verification decodes the Patch payload purpose and the supported replay subset. This check is intentionally weaker than rollback-draft-verify because repository-level verification has no selected ref target.

prikk verify also counts sealed rollback Blocks and sealed rollback Patch references after a rollback draft has been sealed through the existing seal path. The broader repository verification and doctor diagnostic boundary is described in the integrity and recovery diagnostics reference.

Current limits

Rollback draft verification still does not implement:

• rollback-specific ref publication;
• rollback authorization policy;
• audit-plugin approval;
• rollback worktree mutation;
• arbitrary-span text rollback;
• commutation, confluence, or conflict witnesses.

Sealed Rollback History

Prikk provides read-only classification for rollback Patch objects after they are sealed into a normal Block by the existing seal path.

Rollback identity lives in the Patch payload as PatchPurpose::RollbackDraft; it is not encoded in an AUTHOR key id. When a sealed Block references such a Patch, Prikk verifies that the Patch payload decodes under the supported replay subset and then classifies the Block as a rollback Block for history and verification output.

Pre-DC-10 rollback drafts that used the old development key-id marker are pre-stability artifacts. Current classification does not recognize that marker in production logic.

CLI

prikk log [path] [--ref REF]
prikk verify [path]

prikk log reports, per history entry:

rollback-block: true|false
rollback-patches: N

prikk verify reports repository-wide counts:

checked rollback blocks: N
checked sealed rollback patches: N
checked rollback draft WAL records: N

The sealed counts cover persisted Blocks and Patch objects. The active draft count covers the active WAL before seal.

Scope

PR-030 is intentionally classification-only. It does not introduce rollback-specific refs, rollback authorization, rollback worktree writes, or rollback-specific seal semantics.

Deferred work remains:

• rollback-specific ref policy
• rollback authorization and audit policy
• worktree rollback writes
• arbitrary-span text rollback
• commutation / confluence / conflict witnesses
• audit plugins and sync

Merge Evidence

DC-22 (0.15.0) adds prikk merge-evidence, the first public read-only UX over the DC-21 merge/conflict evidence vocabulary. DC-23 (0.16.0) stabilizes its text output.

For the current concepts behind operation ordering, commutation, confluence, evidence outcomes, reason codes, and proof phases, see Patch Algebra and Merge Evidence.

For the planning classification layer over the same explicit-input evidence, see Merge Plan. Neither command executes a merge — for that, see Merge (DC-74), which reuses this same evidence to decide whether to seal.

prikk merge-evidence \
  --baseline-block BLOCK \
  (--left-block BLOCK | --left-ref REF) \
  (--right-block BLOCK | --right-ref REF) \
  [path]

The command derives the single-parent candidate sequences from an explicit sealed baseline to two explicit left/right targets, runs the read-only merge/conflict evidence analysis, and prints the resulting report.

Selector rules:

• --baseline-block is required and names the sealed baseline block.
• Each side must choose exactly one selector: --left-block or --left-ref, and --right-block or --right-ref.
• A --left-ref/--right-ref value may name a received ref (remotes/<name>, DC-85), previewing evidence against imported history exactly as it would for a local branch. This is read-only, so a preview can name a remotes/ ref on either side even though prikk merge itself never accepts one as --into — the preview does not claim the plan it shows is executable as-is.
• The optional positional argument is the repository root, as with other commands. It is not a path filter.

The command is read-only. It does not infer merge bases, execute merges, publish merge commits, write refs or WAL records, materialize worktree conflicts, or persist proof/witness objects.

Output

Output is text-only and intended for human diagnostics. It is not a durable machine-readable schema. DC-23 makes the shape easier to scan:

merge evidence
baseline block: <block-id>
left selector: ref heads/topic-a
left target block: <block-id>
left operations: 3
right selector: block <block-id>
right target block: <block-id>
right operations: 2
outcome: Conflict
reason: pair_conflict
items: 1 displayed of 1

cross:
  left[0] op_seq=1 ChangePerm src/lib.rs
  right[0] op_seq=1 ChangePerm src/lib.rs
  outcome: Conflict
  reason: pair_conflict
  phase: classification

note: read-only evidence; no merge commit, ref update, WAL write, or worktree change was performed

Reading the output:

• both sides show the submitted selector text and the resolved target block identity;
• left and right operation counts are shown separately;
• the full-report outcome and reason are shown before item details, and are computed over the full candidate sequences;
• items: N displayed of N reports the displayed and total item counts (equal in this release; DC-23 adds no display filtering);
• cross-side items render as a cross: block with separate left[...] and right[...] operation lines, rather than an ambiguous one-line form;
• when a side changes one file more than once (any mix of edits, permission changes and binary replacements, optionally ending in a delete, or a new text file followed by edits), the evidence judges that run by its net effect from the baseline, and uses it only when replaying it reproduces the side exactly. An operation line for such a run names its first operation and adds folded-through=left[N] op_seq=M for its last; a run whose net effect is a mode change and an edit shows both operations with the same range. Indices and counts are always those of the original sequence;
• report-level items render as report: without a fake operation label;
• DC-21 outcome and reason-code names are preserved exactly;
• a RenamePath operand’s line also carries asserted-by=<key-id> — the patch’s AUTHOR signature key id. This is structural, not a rendering choice: the underlying read type cannot represent a rename without its asserting signer, so a patch whose AUTHOR signature is missing fails the command rather than showing a rename with no signer.

Privacy: the output never includes raw text spans, replacement text, blob bytes, absolute host paths, .prikk private paths, signer secrets, key material, or arbitrary object debug dumps. Displayed paths are repository-relative.

Exit Status

Process success is independent of the evidence outcome: a produced report exits 0 even when the outcome is Conflict.

Deferred

prikk merge (DC-74) executes confluent merges — see the merge guide; this command stays read-only regardless. Still deferred:

• conflict resolution;
• automatic merge-base discovery;
• branch merge semantics beyond a two-sided confluent merge;
• display-path filtering and scoped/path-limited merge analysis;
• persisted proof/witness/merge-evidence objects;
• JSON or other machine-readable output;
• public prikk-replay API stabilization.

Merge Plan

DC-25 (0.17.0) adds prikk merge-plan, a read-only planning classification over the existing merge evidence report. It answers what Prikk can say about the selected explicit inputs today; it does not execute or prepare a merge commit.

For the current concepts behind evidence outcomes, reason codes, proof phases, and the ConfluentSubset mapping, see Patch Algebra and Merge Evidence.

prikk merge-plan \
  --baseline-block BLOCK \
  (--left-block BLOCK | --left-ref REF) \
  (--right-block BLOCK | --right-ref REF) \
  [path]

Selector rules:

• --baseline-block is required and names the sealed baseline block.
• Each side must choose exactly one selector: --left-block or --left-ref, and --right-block or --right-ref.
• A ref selector resolves through the current local branch target block, or, for a remotes/<name> value (DC-85), through the received ref it names — read-only, so either side may preview a received ref even though prikk merge itself never accepts one as --into.
• The optional positional argument is the repository root. It is not a path filter.

The command is read-only. It does not infer merge bases, execute merges, publish merge commits, write objects, refs or WAL records, materialize worktree conflicts, or persist proof/witness/plan objects.

Output

Output is text-only and intended for human planning diagnostics. It is not a durable machine-readable schema.

merge plan
baseline block: <block-id>
left selector: ref heads/topic-a
left target block: <block-id>
left operations: 3
right selector: block <block-id>
right target block: <block-id>
right operations: 2
status: BlockedConflict
evidence outcome: Conflict
reason: pair_conflict
action: inspect evidence; conflict resolution is not implemented
items: 1 displayed of 1

cross:
  left[0] op_seq=1 ChangePerm src/lib.rs
  right[0] op_seq=1 ChangePerm src/lib.rs
  outcome: Conflict
  reason: pair_conflict
  phase: classification

note: read-only plan; no merge commit, ref update, WAL write, object write, or worktree change was performed

Plan status maps the underlying evidence outcome to a non-executable classification:

ConfluentSubset means the selected candidates are proven confluent only for the currently supported operation subset. It is not a whole-merge guarantee and does not mean Prikk can create a merge commit.

Exit Status

Process success is independent of plan status: a produced BlockedConflict plan exits 0.

Deferred

• Conflict resolution — prikk merge (DC-74) executes confluent merges, but detection only, same as this command;
• automatic merge-base discovery;
• multi-parent blocks and the structural merge record they would provide (DC-75, proposed);
• active-WAL merge drafts and worktree conflict materialization;
• display-path filtering and scoped/path-limited merge analysis;
• persisted proof/witness/merge-plan objects;
• JSON or other machine-readable output;
• public prikk-replay API stabilization.

Merge

DC-74 adds prikk merge, the first command that executes a merge rather than only reporting on one. It builds on the same read-only evidence merge evidence and merge plan already report — see those pages, and Patch Algebra and Merge Evidence, for the underlying confluence concepts.

prikk merge --allow-no-audit \
  --baseline-block BLOCK \
  --into REF \
  --from REF \
  [path]

• --baseline-block is required and names the sealed baseline block confluence is proven against.
• --into is the ref the merge advances. It must currently be published and must be the branch the caller has maintainer signing authority to seal.
• --from is the ref merged in. Its patches since the baseline are what get adopted. It may be a local branch, or a received ref (remotes/<name>, DC-85) imported by prikk bundle import — see Merging from a received ref below.
• --allow-no-audit is required, matching seal’s own flag: this command signs and publishes new sealed history, and audit plugins are not implemented.
• The optional positional argument is the repository root.

What a merge does — and does not do

A merge authors nothing. --from’s patches since the baseline are adopted verbatim: the exact same canonical bytes, the exact same ObjectId, the exact same author signature as when they were originally sealed. prikk merge never decodes, re-derives, or re-signs a patch. Only the new Block, RefState, and RefUpdate are signed — with the maintainer key, exactly as an ordinary seal signs them.

The two sides must be proven confluent from the given baseline — the same evidence merge-evidence/merge-plan already compute, reused rather than duplicated. Any outcome other than Confluent (Conflict, Deferred, NotConfluent, Unsupported, OrderedDependency, EvidenceFailure, InvalidCandidate) refuses the merge. Refusal writes nothing: no object, WAL record, or ref update of any kind is created until confluence is confirmed, so a refused merge leaves --into exactly where it was.

What cannot be merged yet. The confluence proof judges each side’s changes against the baseline. Several changes to one file on one side are judged together by their net effect: any mix of edits, permission changes and binary replacements, optionally ending in a delete, and a new text file followed by edits. A no-op run (a change and its undo) is set aside only when the other side does not touch that file; the merge replays each side’s original patches onto the other side’s tip, so the proof never claims what that replay could not do. Some ordinary histories still refuse:

• Renames that meet. A rename (prikk mv) merges like any other change, whether or not either side edits the renamed file: an edit, a permission change or a binary replacement names the file by its identity, not its path, so it lands on the renamed file. What refuses, as a conflict:

  • the same rename on both sides — both sides changing the same thing is a conflict, as it is for the same edit on both sides;
  • one file renamed to two different paths, or two files renamed onto one path;
  • a rename on one side and a delete of that file on the other;
  • a rename onto a path the other side frees, or a swap or chain split across the two sides. Each side’s rename was made against that side’s history, so one side’s rename cannot rely on a path only the other side vacated.

  A swap of two files made in one commit merges only when the other side changes nothing. Beside any change on the other side it is refused as unsupported_operation: the proof compares the two sides one operation at a time, and half of a swap cannot be replayed alone. The same two renames in separate commits never merge, because between them both files would hold one path.

• A side containing a symlink (created or deleted) is not merged yet. The proof cannot replay a symlink, so it refuses as unsupported_operation rather than guess.

• A side that creates a file and then deletes it, or changes its mode, and a side that deletes a file and creates another at the same path, refuse as sequence_internal_dependency_deferred. A file created and deleted on one side held its path for part of that side’s history, so treating it as nothing could hide a clash with the other side.

• A side that changes a word and then restores it, while the other side edits the same file, refuses as sequence_internal_dependency_deferred.

None of these is damage: the repository verifies clean, and the refusal is a precondition.

What gets recorded

Merge blocks are BlockKind::Merge, naming both parents (DC-75). parent_block_ids holds --into’s prior tip and --from’s adopted tip, sorted per the format’s uniqueness invariant. A separate mainline_parent_id field names which one is --into’s side, since sorted order carries no positional meaning. State derivation and replay follow the mainline parent only — the same shape as an ordinary single-parent block — while the secondary parent’s own chain is verified independently by the ordinary full-object-store scan every other block already gets.

The baseline is recorded, and independently re-derived. merge_baseline_block_id states what --baseline-block was at seal time — a claim, not a trust boundary: ordinary verify computes the true merge base itself (a full-parent reachability walk) and reports disagreement if the recorded baseline is not it. Authorship is unaffected (the adopted patches still carry their original author’s signature).

This discharges the release condition DC-74 attached to this command: sealed history now structurally records a merge, re-checkable by a later verifier from sealed history alone.

Merging from a received ref

--from accepts remotes/<name> — a ref imported by prikk bundle import --input FILE (produced on the other side by prikk bundle export --ref REF --output FILE) — exactly as it accepts a local branch. --into never does: it must always be a genuine local branch, since publishing a ref only ever writes the local ref store.

Adopting content from a received ref requires the maintainer key that sealed it to already be trusted here. Received content arrives via import_bundle with no trust check at all — deliberate, per DC-78 Stage 3: importing is not trusting. A local-to-local merge needs no equivalent check, because every block reachable from a local ref was itself created through this repository’s own seal/merge path, each already gated by trust at creation. A received ref’s blocks were never gated on the way in, so prikk merge checks them itself, before --into advances: every block it would adopt must carry a signature from a currently-adopted maintainer key, or the merge is refused with no trusted MAINTAINER signature and writes nothing.

If you meet that refusal, do not treat it as an error to clear. Running prikk trust maintainer add for whatever key the bundle happened to carry is exactly the decision this check exists to make you take deliberately, not by reflex. Trusting a maintainer key means trusting every block that key has ever sealed or ever will — confirm you mean to extend that trust to this specific origin before adding it, the same judgment call trust maintainer add already asks of a purely local setup.

Conflicts

Detection only. A resolution is itself a signed patch — a trust question prikk merge does not decide. patch_algebra’s conservative subset (DC-16, DC-18) governs what can be proven confluent at all; if it is too narrow to merge something that should be mergeable, that is its own finding, not something this command works around.

Compatibility

verify, doctor, rollback-preview, and DC-64’s incremental lifecycle cache all continue to work against a repository containing a merged block — tested, not argued (crates/prikk-cli/tests/merge/dc74_merge_execution.rs).

Deferred

• Automatic merge-base discovery — --baseline-block stays explicit.
• Widening patch_algebra’s conservative subset.
• Merging more than two sides in one command.

Conflict arbitration / resolution is not on this list. “Deferred” means eventually built; automatic conflict resolution is refused by the architecture and will not be built at all — see Conflict Resolution Is Refused By Design.

PatchPayload.parent_patch_ids is not on this list either. It was removed at Patch schema 2 (0.24.0), not left unpopulated — there is no patch DAG because the field no longer exists, not because it is inert. BlockPayload.parent_block_ids, which DC-75 records, answers a related but different question: block-level parentage, not a patch DAG.

Sync

RFC 116 adds prikk sync: negotiation-as-artifacts between two repositories, with no network code in prikk itself. RFC 117 stage 3 extends the same artifact to carry tags, adopted separately from sealing. See Security and Signing Setup for the maintainer key both sides need before sealing or adopting anything sync brings in.

prikk sync summary   --output <file>
prikk sync compare   --summary <file>
prikk sync have      <ref> --output <file>
prikk sync build     <ref> --have <file> --output <file> [--force]
prikk sync accept    <file> [--claims-out <file>] [--force]
prikk sync pending
prikk sync seal      <ref> --claim <id>
prikk sync seal      <ref> --claims <file>
prikk sync tags
prikk sync adopt-tag <name>

The loop, as a person actually runs it

Two repositories, A (has content B wants) and B (wants it), moving files by whatever means the two operators already have — email, a shared drive, a USB stick. Every step below names the file the previous step produced.

A: prikk sync summary --output summary.bin
B: prikk sync compare --summary summary.bin
B: prikk sync have <ref> --output have.bin
A: prikk sync build <ref> --have have.bin --output artifact.bin
B: prikk sync accept artifact.bin --claims-out claims.txt
B: prikk sync pending                              # optional, observational
B: prikk sync seal <ref> --claims claims.txt
B: prikk sync tags                                 # optional, observational
B: prikk sync adopt-tag <name>                      # per tag, if any arrived

summary publishes every heads/* ref A holds, each with its own patch-set digest and count — a few hundred bytes regardless of history size. compare reads a summary against B’s own refs and reports each as in-sync, differs, remote-only (B lacks it), or local-only (A lacks it). have is B’s own reachable patch-id list for one ref B wants — the input build needs to compute exactly what B is missing. build is A’s side of that computation: it writes an artifact carrying the delta, one recognition claim per block the delta touches, and every local tag whose target lies within the ref’s ancestry. accept verifies and stores everything the artifact carries — patches, blobs, claims, tags — and reports what it found; it does not seal or adopt anything by itself. pending lists patches accept has stored that are not yet reachable from any of B’s own blocks. seal takes the claim ids accept wrote out and turns the accepted patches into B’s own sealed blocks, under B’s own maintainer key. tags lists every tag B has received but not adopted, with its current signature outcome and whether B’s own history can resolve it yet. adopt-tag creates B’s own local tag for one received tag, once B holds the same patch set locally.

What it does — and does not do

prikk does not move the bytes, and does not encrypt them. A file sync build writes contains repository content in the clear. prikk guarantees integrity and authenticity — every object is content-addressed and every claim, tag, and sealed publication is signed — never secrecy. The channel that moves the file is the operator’s choice and the operator’s responsibility. What travels is narrower than “everything,” though: the artifact carries only the objects the delta and the ancestry walk actually name, plus public key material for the patches’ own authors — never a secret key or seed, which live only in each operator’s own environment variables and never appear in any artifact.

A deletion’s own content travels too. An artifact carries the content each deleted node held, so the receiver can replay and roll back that deletion. When nothing stored it — a text file whose edits only ever travelled as spans — sync build derives it by replaying the history and carries the result, checked against the id the deletion names. Before 0.43.0, building an artifact for such a history refused.

prikk stays off the network by design, not by omission. Every check in the accept path already treats the artifact as untrusted input from an unknown origin; adding a transport would add attack surface without adding verification strength, so RFC 116 ruled negotiation-as-artifacts first and network code out of scope for now.

The receiver seals and adopts under its own key, always. Accepting an artifact never adopts a maintainer key, never advances a ref, and never creates a local tag by itself — those are separate, explicit acts (seal, adopt-tag), each signed locally.

An object’s id is the hash of its payload, and signatures are not part of the payload. So a receiver that seals the same patches, in the same grouping, onto the same parent produces the sender’s block id and the sender’s RefState id exactly; only the signatures on them differ. (Measured: a receiver sealing one accepted claim under its own maintainer key got the sender’s block and heads/main RefState ids.) Sealing the patches in a different grouping, or onto a different tip, gives different ids. A sender’s tag and the receiver’s adopted tag are different objects: adopt-tag writes a tag object and RefState of its own, naming the same target block.

An accept interrupted partway never leaves a dangling reference. accept writes under one lock, held continuously from the first write to the last, in a fixed order: patches and blobs first (content-addressed and idempotent, so a replayed accept writes nothing new for anything already present), then AUTHOR key material, then claims and tags last. Claims and tags are what every other command treats as “this was accepted,” so if accept is interrupted partway through, part of the artifact may already be sitting in the object store, but nothing yet points at it as accepted — there is no reference naming content that was never stored. Running the exact same accept again simply continues it to completion: the content already written is skipped, not rewritten.

One id, several signers, in format 7. After the receiver has sealed the sender’s patches as above, importing the sender’s bundle of that ref merges: each shared object keeps one stored copy carrying both maintainers’ signatures, and the import reports objects gaining signatures: N. The same happens in the other order, when the receiver imports first and seals afterwards. What may join a stored object is checked first: every incoming signature must verify, or the whole import or exchange is refused with nothing written; a MAINTAINER signature is kept only if this repository has adopted its key, and is otherwise dropped and named on a signature not stored: line; an AUTHOR signature needs key material under the usual trust-on-first-use rules. Nothing arrives pre-trusted.

An object carries at most 4 counted signatures when an import or exchange would store it. Every signature counts except a MAINTAINER signature by an adopted key that verifies; above the limit the whole import or exchange refuses, naming the object, at least 5 counted signatures and limit of 4, and writes nothing — counting stops there, so the number is not the object’s total. It applies to new objects and merges alike. Local commands never check it and are never refused. seal signs with an adopted maintainer key, which does not count; your own AUTHOR signatures do, so on an object whose set they helped fill, another signer’s copy is refused. See Trust and Threat Model. A format-6 repository — one created by 0.44.0 or earlier and not yet upgraded — still holds one signed copy per id and refuses with existing container record for <id> differs from candidate, naming prikk format upgrade.

Divergence is reported, not treated as damage. If an accepted patch does not apply to the receiver’s current tip, that means the two histories have moved differently since they last agreed — ordinary, not corruption.

Limits

• No remote-tracking, no named remotes, no discovery. Every step names a file explicitly; prikk remembers nothing about who you last synced with. Each round starts from nothing.
• Each exchange costs O(history), not O(change). A have-list is 32 bytes per patch reachable from the ref — at 100,000 patches, roughly 3 MB, sent on every exchange regardless of how small the actual delta turns out to be.
• Adopting a tag resolves by scanning local blocks, and that scan is superlinear. Measured at roughly 12.6 ms over 500 blocks and 86 ms over 2000 in a single long branch. Do not expect it to stay fast as history grows.
• The summary covers heads/* only. remotes/* never appears in it — received, unsealed history is a separate namespace. Tags are not listed in the summary, but they do travel in the build artifact and are adopted separately (RFC 117) — a repository can receive and adopt tags even though compare never mentions them.
• sync compare, sync build and sync accept each refuse an oversized input file before reading it, and sync accept refuses any one object inside the artifact over a separate bound you can set (equal to the total by default, so it only bites once you lower it) — see Size bounds on incoming artifacts for the defaults, the refusal wording, and how to raise or lower either one.

Out of scope

Transport, remote-tracking, and tag deletion are not built. Nothing here documents them as forthcoming.

Claim-to-Source Anchors

Provenance

This guide covers RFC 116 (stages 1 through 7) and RFC 117 stage 3. It is documentation-only and does not change CLI behavior, artifact format, signing, trust, or repository state.

Backup and Restore

prikk bundle export/verify/import (DC-78) are what back up and restore a repository today. This page is the recovery procedure: make a backup, check it later without touching anything, and restore it — plus, just as important, what that restore does and does not establish about the history you get back. See Security and Signing Setup for the maintainer key setup this page’s trust maintainer add step assumes.

Prikk is early implementation software. Work through this page with throwaway content, the same example key material the tutorial uses — never real seeds.

Set up a repository to back up

If you have already worked through the tutorial, skip to Make a backup — this is the identical setup, condensed. Each refusal below is explained there, not repeated here.

mkdir source-repo && cd source-repo
prikk init
export PRIKK_AUTHOR_KEY_ID="dev-author"
export PRIKK_AUTHOR_SEED_FILE="$PWD/author.seed"
export PRIKK_MAINTAINER_KEY_ID="dev-maintainer"
export PRIKK_MAINTAINER_SEED_FILE="$PWD/maintainer.seed"
prikk trust maintainer add \
  --key-id "dev-maintainer" \
  --public-key "a00899dfd3357aee69729405913f9324dfc033cec04a2215239eda64ae6d9d91"
echo "hello prikk" > readme.txt
prikk commit -m "genesis"
prikk seal --allow-no-audit

initialized Prikk repository at /path/to/source-repo/.prikk
trusted maintainer key: dev-maintainer
adopted maintainer keys: 1
recorded worktree patch in active WAL
baseline ref: heads/main
patch id: ...
WAL sequence: 1
operations: 1
referenced blobs: 1
...
  create-file readme.txt
...
sealed active WAL into block
patches: 1
block id: ...
heads/main RefState: ...
...

Make a backup

A backup is one ref’s sealed closure — the ref’s own RefState plus every object reachable from its target block back to genesis:

Run this from inside source-repo, writing the backup one level up so it survives independently of the repository it came from:

prikk bundle export --ref heads/main --output ../backup.bundle

exported heads/main
tip block: ...
objects: 5
author key material: 1 included (continuity only, not a trust decision)
repository format: 6
tool version: ...
note: this bundle contains one ref's closure only -- other refs in the source repository, if any, are not included, and this bundle makes no claim about them
wrote ../backup.bundle

Running this again refuses rather than silently replacing the file:

prikk bundle export --ref heads/main --output ../backup.bundle

error: refusing to overwrite existing file at ../backup.bundle (pass --force to overwrite it intentionally)

Pass --force when overwriting is actually what you want.

Only sealed history is backed up — this is the limit that costs the most

commit records a patch in the active write-ahead log; only seal publishes it onto a ref. bundle export walks the ref’s own published block ancestry — the active WAL is not part of that walk. If you commit and do not seal before exporting, that commit is not in the bundle, and nothing about the export command tells you so.

This is not a hypothetical. Still inside source-repo, commit again without sealing:

echo "not yet sealed" > notes.txt
prikk commit -m "notes, not yet sealed"
prikk bundle export --ref heads/main --output ../backup-after-unsealed-commit.bundle

exported heads/main
tip block: ...
objects: 5

The tip block and object count are identical to the first export. The second commit is not an error, not a warning, and not present — the bundle is byte-for-byte a backup of the state before that commit ever happened. Before exporting, check whether anything is queued:

prikk status

...
active WAL records: 1
trailing partial WAL bytes: 0
heads/main RefState: ...
queued patches: 1 targeting heads/main
...

queued patches: 1 is the tell. Seal first, then export — now backup.bundle covers both generations:

prikk seal --allow-no-audit
prikk bundle export --ref heads/main --output ../backup.bundle --force

sealed active WAL into block
patches: 1
block id: ...
heads/main RefState: ...
...
exported heads/main
tip block: ...
objects: 9
author key material: 1 included (continuity only, not a trust decision)
repository format: 6
tool version: ...
note: this bundle contains one ref's closure only -- other refs in the source repository, if any, are not included, and this bundle makes no claim about them
wrote ../backup.bundle

objects: 9 now (two RefStates, two blocks, two patches, two blobs, and the snapshot the first block carries as a checkpoint) — --force was necessary because ../backup.bundle already existed from the first export.

A bundle is one ref

bundle export takes exactly one --ref. A repository with several branches needs a bundle per branch — nothing collects them for you, and the manifest’s own printed note above says so in every bundle you make, not only here.

For every ref, every object, and the trust material in one file, see The Archive Format instead: prikk archive export <file> carries the whole repository, verbatim. prikk archive verify <file> reads one back and reports whether it is internally consistent, needing no repository and writing nothing. prikk archive import <file> [--adopt] lands every ref the archive carries into a fresh (or existing) repository: by default under remotes/<ref>, the same received-pointer shape bundle import already produces, or as a real local branch under --adopt, when it is absent locally, signed by a key this repository has adopted (trust maintainer add), and verified — every other ref still lands under remotes/, with the reason named.

With prikk 0.51.0, run archive verify on every export before relying on it (fixed in 0.52.0; see the limitation for the two shapes and why).

A repository holding any file over 256 MiB cannot be archived. archive export (and bundle export, for a ref that reaches such a file) refuses up front, naming the over-bound object, and writes nothing — the same per-object bound archive import/bundle import already enforce when reading one back. A copy of this repository’s own .prikk/ directory is the real backup for a repository in this state.

If the archive’s own exported local ref and one of its own carried received pointers would land at the same remotes/<ref> name — because the source repository itself once bundle imported something for that same ref — the exporter’s own ref wins the name; the colliding received pointer is not landed, and the import’s own report names it and the RefState it would have landed (its objects are still imported either way). A successful --adopt lands the exporter’s own ref as a real local branch instead, so there is no collision at all in that case.

If archive import is killed or lost partway through, prikk doctor names it (PRIKK-DOCTOR-INTERRUPTED-IMPORT) and its id, with two ways out: run the same import again (it resumes from wherever it stopped), or prikk doctor --cancel-import <id> to restore the repository to what it was before the import ever started. If the process was killed outright — a real SIGKILL, a lost machine, not a command that returned an error on its own — its lock files are still on disk (nothing steals a lock automatically: see prikk unlock’s own guide), and doctor’s own message says so, naming prikk unlock first, ahead of resume or cancel. The sequence is always the same order: prikk doctor to see what is true, prikk unlock --lock <path> for each lock it (or prikk unlock on its own) lists, if any are present, and only then the same import again, or --cancel-import.

Check a backup later, without restoring it

bundle verify reads a bundle file and reports whether it is structurally sound and internally consistent. It needs no repository and writes nothing — safe to run against a backup sitting on a shelf, from any directory. Leave source-repo first, to show it really does not need one:

cd ..
prikk bundle verify --input backup.bundle

bundle verifies: heads/main
RefState: ...
tip block: ...
objects: 9
author key material: 1 present (continuity only, not a trust decision)
repository format: 6
tool version: ...
note: this bundle contains one ref's closure only -- other refs in the source repository, if any, are not included, and this bundle makes no claim about them
note: this checks structural and internal consistency only -- no signature is cryptographically verified (a standalone bundle carries no trust material to check one against), and this bundle's own author-key section is recorded here, never independently verified, the same as at import. A verified bundle is not yet a trusted one -- import it and run `prikk verify` for that.

Restore

Restoring means importing into a repository and then checking the result — import alone is deliberately not enough to trust what arrived.

mkdir restored-repo && cd restored-repo
prikk init
prikk bundle import --input ../backup.bundle

initialized Prikk repository at /path/to/restored-repo/.prikk
received remotes/heads/main
RefState: ...
objects: 9
new objects: 9
author key material: 1 recorded (continuity only, not a trust decision)
note: no local ref was created or advanced, and no MAINTAINER key was trusted; this repository now holds the received history at remotes/heads/main, which `prikk log --ref remotes/heads/main` and `prikk show` read, and `prikk verify` checks once `trust maintainer add` trusts the sealing key

Restoring into a repository that already holds some of the history stores nothing twice. An object it already holds under the same signatures is counted but not written; the same object under an additional signature — a copy another maintainer sealed — merges into the stored one in a format-7 repository, reported as objects gaining signatures: N, and is refused in a format-6 one (see Sync).

Import records material; it does not create trust. The imported history lands as remotes/heads/main, not heads/main — no local ref moved, and the maintainer key that sealed it is not yet trusted here. Trust it explicitly, the same key id and public key Security and Signing Setup describes adopting:

prikk trust maintainer add \
  --key-id "dev-maintainer" \
  --public-key "a00899dfd3357aee69729405913f9324dfc033cec04a2215239eda64ae6d9d91"

trusted maintainer key: dev-maintainer
adopted maintainer keys: 1

Now confirm the restore:

prikk verify

verified repository: /path/to/restored-repo/.prikk
...
object items: 9 scanned, 0 failed
...
publication trust issues: 0
sealed blocks: 2
sealed-block ...: dev-maintainer
sealed-block ...: dev-maintainer
...
received refs: 1
received-ref remotes/heads/main: ...

verify is the same command, unmodified, that checks any locally-authored repository — the bundle format adds no separate verification path. A restored copy is only as checked as this command says it is; import’s own report is not a substitute for running it.

What a restore gives, and what it does not. Measured on the binary, in a fresh repository after bundle import:

• It gives verifiable history at remotes/heads/main. prikk log --ref remotes/heads/main lists the received blocks, prikk show <block> reads their patches and content, and prikk verify checks every object and names the key that sealed each block. With no maintainer key trusted, verify reports publication-trust issues and exits non-zero; after trust maintainer add for the sealing key, it passes.
• It does not give a working branch. None of these turn the received ref into your own heads/main today: prikk branch create heads/main --from remotes/heads/main and prikk checkout --patch-plan or --patch-materialize --ref remotes/heads/main refuse (remotes/heads/main is a received ref, and this command does not accept received refs), so no worktree is written; and prikk merge --into heads/main --from remotes/heads/main refuses in a fresh repository (ref heads/main does not exist in this repository), even with the sealing key trusted. The refusal names what does read a received ref: log, merge-evidence, merge-plan and bundle preview.
• It cannot be passed on. prikk bundle export --ref remotes/heads/main refuses, so a restored copy is not itself a backup source.

A bundle import restore is therefore an intact, checkable copy of the history, not a repository you continue working in that way. prikk archive export <file> writes a whole repository, verbatim, into one file (RFC 155) — see The Archive Format. prikk archive verify <file> reads one back and checks structure, reference closure, and every signature against the archive’s own carried key material, reporting internally consistent, never trusted — it needs no repository and writes nothing. A signature by a key the archive does not carry (for instance, a received branch the source repository itself never trusted) is named, not refused on: trust is always the receiving repository’s own decision, never the archive’s. prikk archive import <file> --adopt is the landing step that turns a carried branch into a working one: absent locally, signed by an adopted key, and verified, it becomes a real local branch; every other ref still lands under remotes/, exactly like bundle import’s own received pointer, with the reason named.

What this proves, stated precisely

• Corruption is detectable. Every object’s id is a hash of its own bytes, and bundle verify confirms every reference inside the bundle resolves to an object whose recomputed id matches. Content addressing works the same way a downloaded release’s checksum does: it proves the bytes are intact and internally consistent, not who produced them.
• A deletion carries the content it removed. A bundle includes the file content each deleted node held, so a receiver can read that deletion in full — prikk show renders the content rather than <unavailable blob …>. Where nothing stored that content — a text file whose edits only ever travelled as spans — the exporter derives it by replaying the history and carries the result, checked against the id the deletion names. Before 0.43.0, exporting such a history refused outright. Rolling that deletion back is a separate matter: rollback-preview and inverse-plan work on a published local ref, and an imported history lands at remotes/…, so both refuse there (remotes/heads/main is a received ref, and this command does not accept received refs). The content is present for when the history is local.
• bundle verify answers “is this file intact” without a repository or a restore. Nothing is written; nothing needs to exist first.
• verify_repository after import is what turns a restored copy into a checked one — the same structural and authorship checks any repository gets, run against what was actually written.

What this does not prove

• No signature is cryptographically checked offline. A standalone bundle file carries no trust material to check a signature against — bundle verify checks structure only. Authenticity is checked after import, by verify.
• Authorship is trust-on-first-use, not identity. See Trust and Threat Model § Trust Roots and Roles for exactly what that does and does not establish — it is not restated here, so the two cannot drift apart.
• A restored repository has no maintainer trust policy until you give it one. bundle import adopts no key; prikk verify reports publication-trust issues until trust maintainer add is run for the key that sealed the history you received.
• This is not release authority. Releases of prikk itself are signed by the project’s one maintainer key, and release-signers.toml is empty because no multi-signer policy exists yet (Release, Versioning, and Compatibility § How prikk releases). That is separate from repository-local maintainer trust — trusting a maintainer key here says nothing about who built the prikk binary you are running.

Limits

• One ref per bundle. Multi-ref export does not exist; back up each branch you care about separately.
• No rehearsed restore across a repository-format change. This page exercises ordinary export and import on the current format; migrating a repository from an older on-disk format via bundle export/import, as layout.rs’s own retired-format messages describe, has not been exercised end to end as part of this page.
• bundle import, bundle preview and bundle verify each refuse a bundle over a size bound before reading it, and refuse any one object inside it over a separate bound you can set (equal to the total by default, so it only bites once you lower it) — see Size bounds on incoming artifacts for the defaults, the refusal wording, and how to raise or lower either one.

Claim-to-Source Anchors

Provenance

This guide implements DC-44’s last design goal (bundle-manifest-handoff-v1.md’s own follow-up, backup-restore-page-handoff-v1.md). It is documentation-only and does not change CLI behavior, bundle format, signing, trust, or repository state.

This page’s own command sequence is exercised by an automated test (crates/prikk-cli/tests/installers_and_help/dc44_backup_restore_page.rs), which runs every command above, in order, against the compiled binary, and asserts on the same output lines quoted here, including the --force refusal and the unsealed-commit demonstration. A change to the CLI that alters any of them fails that test, not just this page.

Git → prikk: a vocabulary map, not a feature map

If you know Git, prikk’s commands will look familiar and several of them mean something different. commit does not publish. There is no HEAD and no staging area, though there is a current branch that branch switch moves. seal has no Git counterpart at all. Reading prikk’s words as Git’s words will make you wrong about several things at once, and you will not notice, because nothing will error — the commands will simply do something other than what you expected.

This page is a vocabulary map for a human, not a migration tool. It does not import Git history and does not promise to; the closest active work on that is RFC 113, which is a design for the import contract, and nothing implements it yet.

Command correspondence

Commit versus seal, a two-phase model

Git’s commit does one thing: it creates a commit object and moves the branch pointer in the same step. prikk splits that into two commands with nothing in between them optional:

prikk commit --from-worktree -m "message"   # queues a signed Patch to the local WAL
prikk seal --allow-no-audit                 # publishes the queue as a Block, moves the ref

A queued-but-unsealed commit is genuinely not part of history yet — it does not appear in log, and a peer reading your repository cannot see it. You can queue several commits before sealing them together. There is no Git operation that maps onto commit alone; it is closer to git add plus git commit --no-verify into a holding area that Git does not have, and seal is the step that actually behaves like git commit’s publishing half.

A current branch, no HEAD

There is no HEAD and no detached state, but there is a current branch: .prikk/current-branch names one local branch (heads/main in a new repository), and every command that takes --ref defaults to it. prikk branch switch heads/<name> moves the worktree and the pointer together. Unlike git switch, it never carries uncommitted changes across: a dirty worktree, or unsealed work queued for another branch, is refused, and you commit or seal first. --ref given explicitly still works on every command without switching.

Messages are stored; authors and dates are not

prikk commit -m <message> requires a non-empty message and stores it — since 0.32.0 it is a signed, identity-bearing field on the Patch itself (Patch schema 4), and prikk log prints it under its block, one line per patch. Changing a message changes the patch id, exactly as changing an operation does: it is evidence, not an annotation (RFC 123).

A patch written before 0.32.0 carries no message and shows no message line — absence, not a placeholder. Those patches stay readable forever; the message was never recorded and cannot be attached retroactively.

An author display name and a commit date are still not stored, and the date never will be. created_at is pinned to zero at every signing site so object ids stay reproducible across machines, which CI proves by mutating a repository on Windows and Linux and diffing the resulting id lists. A timestamp inside the identity surface would destroy that property. The display name is a separate, deferred question (RFC 123 §5). A tag’s message is persisted too — the two commands are now symmetric in this respect.

File-based distribution instead of remotes

There is no remote registry, no URLs, and no network transport of any kind in the binary. Moving history between repositories is always a file you produce and hand to the other side yourself:

• prikk bundle export/import/verify — a complete, self-contained history bundle in one file.
• prikk archive export/verify — a whole repository, every ref and every object, verbatim, in one file (RFC 155). archive import is not built yet.
• prikk sync’s summary/compare/have/build/accept/pending/seal subcommands — an incremental, gap-closing exchange, still file-based, still no sockets.

Either way, what you receive lands as an untrusted remotes/<name> pointer — readable by log, merge-evidence, and merge, but not automatically merged or trusted the way a Git remote-tracking branch is once fetched.

Claim-to-Source Anchors

Provenance

Seeded from the external architecture audit’s 2026-08-31 feature-completeness matrix (audit-2026-08-31-task-1a-design-functionality.md §4), re-verified against main at the time of writing rather than copied — several rows in that matrix are now stale (worktree-status was broken then and is fixed; .prikkignore did not exist then and does now). RFC 128 §5 requested this page. It does not cover RFC 113 (history import) or any importer tool — neither exists yet.

Command Surface

Every command prikk accepts, in one place. This page is an inventory, not a tutorial — each command’s own behaviour, refusals, and worked examples live in the guide, and the Git→prikk mapping explains where the vocabulary differs from Git’s.

Every command accepts --help for its own usage:

prikk <command> --help

prikk init [path]
prikk key generate [--out <path>]
prikk key public [--seed-file <path>] [--role author|maintainer]
prikk key status [path] [--role author|maintainer] [--format json]
prikk setup [repo-path] [--author-seed-out <path>] [--maintainer-seed-out <path>]
prikk trust maintainer add --key-id ID --public-key HEX
prikk trust maintainer remove --key-id ID
prikk trust maintainer list [--format json]
prikk trust maintainer check --key-id ID [--format json]
prikk commit [--from-worktree] [--text-edits] [--ref heads/<branch>] -m <message>
prikk mv <old> <new>
prikk seal --allow-no-audit [--ref heads/<branch>]
prikk status [--format json]
prikk log [path] [--limit N] [--ref REF] [--format json]
prikk checkout --plan-only [path] [--ref <ref|block-id>]
prikk checkout --snapshot-plan [path] [--ref <ref|block-id>]
prikk checkout --snapshot-materialize [path] [--ref REF]
prikk checkout --patch-plan [path] [--ref <ref|block-id>] [--format json [--content-path <path>]...]
prikk checkout --patch-materialize [path] [--ref REF]
prikk checkout --patch-delete-plan [path] [--ref <ref|block-id>]
prikk checkout --patch-materialize-delete [path] [--ref REF]
prikk show <block-id|patch-id> [--format json]
prikk tree [path] [--ref <ref|block-id>] [--prefix <p>] [--format json]
prikk cat --path <p> [--ref <ref|block-id>] [--output <file> [--force]] [--max-bytes N] [--format json]
prikk extract (--ref <ref|block-id>|--claim <claim-id>) <dir> [--allow-full-replay] [--plan-only] [--max-bytes N] [--max-files N] [--format json]
prikk diff [path] [--from <ref|block-id>] [--to <ref|block-id>] [--path <p>]... [--format json]
prikk merge-evidence --baseline-block ID (--left-block ID|--left-ref REF) (--right-block ID|--right-ref REF) [path]
prikk merge-plan --baseline-block ID (--left-block ID|--left-ref REF) (--right-block ID|--right-ref REF) [path]
prikk merge --allow-no-audit --baseline-block ID --into REF --from REF [path]
prikk inverse-plan [path] [--ref REF]
prikk rollback-preview [path] [--ref REF]
prikk rollback-draft --append-inverse [path] [--ref REF] -m <message>
prikk rollback-draft-verify [path] [--ref REF]

prikk branch [list] [--all] [--format json]
prikk branch create heads/<name> [--from REF]
prikk branch close heads/<name>
prikk branch switch heads/<name>
prikk tag [list] [--format json]
prikk tag create tags/<name> --target <ref|block> [-m <message>]
prikk config get <key>
prikk config set <key> <value>
prikk config unset <key>
prikk config list
prikk bundle export --ref REF --output <file> [--force]
prikk bundle import --input <file> [--max-object-bytes N]
prikk bundle preview --input <file> [--ref REF] [--max-object-bytes N] [--format json]
prikk bundle verify --input <file> [--max-object-bytes N]
prikk archive export <file> [--format json]
prikk archive verify <file> [--format json]
prikk archive import <file> [--adopt] [--format json]
prikk sync summary --output <file>
prikk sync compare --summary <file>
prikk sync have <ref> --output <file>
prikk sync build <ref> --have <file> --output <file> [--force]
prikk sync accept <file> [--max-object-bytes N] [--claims-out <file>] [--force]
prikk sync pending
prikk sync seal <ref> --claim <id>
prikk sync seal <ref> --claims <file>
prikk sync tags
prikk sync adopt-tag <name>
prikk worktree-status [path] [--ref REF] [--format json]
prikk verify [path] [--stop-on-first-error] [--format json]
prikk doctor [path]
prikk doctor [path] --repair-wal-tail
prikk doctor [path] --repair-index
prikk doctor [path] --repair-pointer-index-tail
prikk doctor [path] --repair-tails [--plan-only]
prikk doctor [path] --repair-main-ref
prikk doctor [path] --rebuild-pointer-index [--plan-only]
prikk doctor [path] --discard-damaged-commits [--plan-only]
prikk doctor [path] --restore-queue-target --ref <ref> [--not-current-branch] [--plan-only]
prikk doctor [path] --recovery-list
prikk doctor [path] --recovery-restore <run id> [--plan-only]
prikk doctor [path] --recovery-clear [--plan-only]
prikk doctor [path] --cancel-import <id> [--plan-only]
prikk ref complete <ref> [--plan-only]
prikk format upgrade [path]
prikk unlock
prikk unlock --lock <path> [--yes|--force]
prikk compact --pointer-index|--received-index|--trust-policy|--all [--plan-only]
prikk compact --received-index|--trust-policy --keep-slot a|b [--plan-only]
prikk received remove <remotes/…> [--plan-only]
prikk --version

What --from and --target accept. branch create --from REF takes any published ref: a branch ref names its Block directly, and a tag ref is dereferenced through its tag object, so --from tags/v1 publishes the new branch at the Block that tag names. tag create --target takes a block id or a branch ref, and refuses a tag ref — a tag of a tag is outside the model (ref → tag object → block, one hop), and resolving it silently would make --target tags/v1 and --target that tag’s own block indistinguishable in history. The refusal names both accepted forms.

Key ids.

• setup (when it creates a seed) and key generate --out write the new key’s id, ed25519-<first 16 hex of the public key>, beside the seed, as <role>.key-id in the key directory or <seed path>.key-id.
• Every signer, setup and key status resolve the id the same way: PRIKK_<ROLE>_KEY_ID, else that file, else the legacy role word.
• setup adopts the maintainer key under the resolved id and prints it.
• key status reports key_id_source as environment, key-file or default, and a key-id file that does not hold its seed’s id as reason: key-id-file-mismatch, which refuses signing.

format upgrade is explicit, verified and one-way. A repository created by 0.44.0 or earlier is format 6; new repositories are format 7, which is format 6 plus “an object id may hold several records, the last authoritative”. prikk format upgrade takes the writer lock, runs the same verification as prikk verify and refuses — changing nothing — unless it would exit 0, then overwrites the one byte of the .prikk/FORMAT marker in place and flushes it (no rename; RFC 168 §3.3, crates/prikk-store/src/format_upgrade.rs:81-88). Nothing stored is rewritten. It is idempotent on a format-7 repository, never runs by itself, and has no inverse: prikk 0.44.0 and earlier refuse a format-7 repository at open. See Release Compatibility.

Refusals about refs and repositories.

• A ref that does not exist. A command that reads an existing ref’s state refuses an absent name before anything else with precondition not met: ref <name> does not exist in this repository (exit 1), adding a sentence when remotes/<name> exists. That covers log and worktree-status given --ref, every checkout mode, inverse-plan, rollback-preview, rollback-draft, rollback-draft-verify, merge-evidence, merge-plan, merge --into/--from, bundle export, branch create --from, tag create --target, branch close and branch switch, which keeps its own route sentence.
• Not refused: sync have, sync build and bundle preview answer an absent ref as a state (“none of it”), and commit --ref, seal --ref and branch create create the ref. In a fresh repository, log and worktree-status without --ref still report the unpublished current branch.
• A received ref given to a command that cannot use one (checkout, inverse-plan, rollback-preview, bundle export, branch create --from, tag create --target) refuses with precondition not met: <name> is a received ref, naming the commands that read received refs (log, merge-evidence, merge-plan, bundle preview) and the one that takes it into a local branch (merge --from).
• A path with no repository refuses as a precondition naming that path (“no prikk repository at ”), decided when the repository is opened, in every command that opens one.

A point: a ref or a bare block id. checkout’s read-only modes (--plan-only, --snapshot-plan, --patch-plan with or without --content-path, --patch-delete-plan) take --ref as a ref name or a bare block id, 64 lowercase hex characters, resolved by one resolver.

• A block the repository holds resolves whether or not any ref reaches it: an older block on a branch, or a block only received history holds. Reading it adopts nothing.
• block <id> is not in this repository and object <id> is a patch, not a block (naming the type it is) refuse as preconditions, exit 1. A --ref value that is neither a ref name (heads/…, tags/…, remotes/…) nor 64 lowercase hex is a usage error, exit 2.
• The modes that write the worktree (--snapshot-materialize, --patch-materialize, --patch-materialize-delete) refuse a block id: writing the worktree needs a branch, because the next commit authors against one.
• The prose header reads block: <id> for a block id and ref: <name> otherwise; --plan-only prints ref-state: <none> for a block id. patch-plan-content-v1’s ref holds the value as given, now possibly a block id; its schema version is unchanged.

Reading a point: tree. tree lists the files present at a point — a ref, or a bare block id — with each one’s mode, exact size and whether it is text or binary, by the same classification checkout --patch-plan --format json reports. It reads received refs. Without --ref it lists the current branch, and an unpublished current branch lists nothing, exit 0; an explicit absent ref refuses. --prefix filters by whole path components; the replay is whole-tree either way. --format json is tree-listing-v1. See Reading a point.

Reading a point: cat. cat writes one file’s bytes at a point, text or binary, to stdout or to --output. The content is resolved in full before anything is written, so a refusal writes nothing. --max-bytes bounds what is written — exactly, and all or nothing — but not memory, which is the shared replay’s own cost; --output refuses an existing file without --force and any path inside .prikk/, and is written to a temporary sibling then renamed into place. Binary content refuses a terminal, naming --output; text is written. A path that is not a file at the point refuses with path <p> does not exist at <point>. --format json is path-content-v1: the same fields as one tree-listing-v1 entry, and no bytes.

Writing a point into a new folder: extract. extract --ref <ref|block-id> <dir> writes every file at a point into a new directory that does not exist yet, no repository history and no worktree state, the same shape git archive | tar -x produces. <dir> must resolve outside this repository’s own root (.prikk/ included) — compared by identity, never by spelling, so a relative path, a .. that lands back inside, a symlinked parent, or a differently-cased or short-name spelling of the root on Windows all refuse just as a plain path inside the worktree does; a path outside the repository, including a sibling directory whose name merely starts with the repository’s own name, is unaffected. The reason is the same one commit --from-worktree already gives for its own worktree content: a copy left inside the repository would be picked up as worktree content by the very next commit. Unlike cat/tree, it anchors only where a writer would: the same admitted-anchor rule checkout’s own worktree writes use, never the weaker rule that lets cat and tree display any snapshot that merely decodes correctly. A remotes/... ref under a key this repository has not adopted therefore always replays fully from its own genesis; past 63 blocks with no admitted snapshot in reach, extract refuses by name, giving the distance and --allow-full-replay to read it anyway. Every file whose content has not changed since the admitted anchor streams straight from its stored blob id, nothing is held resident past the one file’s own size, and a path renamed after the anchor still streams from that same id, at its new path. The target must not already exist; a leftover <dir>.prikk-extract-tmp from an interrupted run refuses by name rather than being reused or deleted; the whole write is atomic (a temporary sibling, then one no-replace rename), and every file and directory is synced before it, so a crash never leaves a target with missing or partial content. provisional: yes|no says whether an admitted anchor was actually found and used, or the replay fell back to genesis instead.

--plan-only reports the point’s own file count, total bytes, largest file: N bytes and provisional, and writes nothing at all — no target, no temporary sibling. --max-bytes N/--max-files N refuse the whole point, by name, before the first byte is written — learning the point’s own total size this way costs what it costs (each file not already resident is read once to measure it), the same cost a real write already pays; the pre-walk’s own bound (refusing a point whose nearest admitted snapshot is unreachably far back) is the separate, cheap guard against unbounded history depth, checked before a single Patch or Blob is read, never relaxed by these flags. --format json (extract-report-v1) carries file_count, total_bytes, largest_file_bytes (the single largest entry’s own byte length, always present, the same number the text form’s largest file: N bytes line gives), provisional, written (whether this call actually wrote the target), point (the ref name or the block/claim id given, the one fixed key tree’s own tree-listing-v1/cat’s own path-content-v1 both use), point_kind ("ref", "block", or "claim"), target_block_id, and claim_parent_block_id (always present; null unless point_kind is "claim", in which case it is the claim’s own declared parent — the block its own patches would be sealed onto, not target_block_id, which is the block the claim recognizes; no command printed a claim’s parent before this round) — the same hand-rolled, schema_version-named convention those commands already use. --claim <claim-id> (mutually exclusive with --ref) previews a pending RecognitionClaim — the same id sync seal --claim takes — as if its own patches were sealed onto its own declared parent, without sealing anything: useful to inspect what a claim would produce (its size, or its content) before deciding to accept it. A claim naming more than one parent (one built from an ancestor Merge block) is refused by name — there is no field in the claim saying which parent is mainline, so this is refused rather than guessed. --claim takes the identical pre-walk bound as --ref/a bare block id: past the trusted distance from the claimed parent’s own nearest admitted checkpoint, it refuses by name unless --allow-full-replay is given. extract’s own peak memory, whole command, tracks the largest single file it actually reads (roughly twice that file’s own size, not once — see Current State), not the point’s own total content size; this holds the same way whether the point is named by --ref, a bare block id, or --claim — --claim’s own own derivation step (prepare_extract_plan_for_claim) costs a little more than the ref/block-id path’s own equivalent planning step (about 1.1–1.3x, measured), but that planning cost is small next to the one shared, dominant cost every path pays: streaming the point’s own largest file once. See Current State for the measured figures, both the planning-only comparison and the whole command. See Reading a point.

refusal-v1: a machine-readable refusal document. Under --format json, every refusal extract exits 1 for — never a usage error, exit 2, which prints no document — writes exactly one JSON document to stdout (never stderr; stderr’s own text and the exit code are entirely unchanged by this). This is a structural guarantee at extract’s own command boundary, not merely a property each refusal happens to have today: a refusal reached by a path this document’s own list does not yet name still gets a document, classified by a fallback, rather than exiting 1 under --format json with nothing on stdout.

{"schema_version": "refusal-v1", "command": "extract", "refusal": "<id>", "reason": "<id>|null", "message": "<the stderr text>"}

refusal is one of fifteen stable, kebab-case ids: over-max-bytes, over-max-files, destination-exists, destination-inside-repository, temporary-sibling-exists, point-not-found, claim-not-found, not-a-claim, claim-has-several-parents, claim-parent-not-sealed, case-collision, no-checkpoint-in-reach, not-a-repository, damaged-repository, io-failure. claim-parent-not-sealed means the claim’s own declared parent has not been sealed or received into this repository yet — seal or receive it first, then extract the claim again; this repository is not damaged. reason is set only for no-checkpoint-in-reach, naming which of three conditions the admitted-anchor search found in reach — one cause at a time: the first blocker the search meets, not necessarily the only one. Fix it and run again; the next refusal names the next cause, if any. In priority order: signer-not-adopted (a recorded checkpoint whose signer this repository has not adopted — adopt the key), not-recorded (a checkpoint in reach, never recorded by verify/seal — run verify), or no-checkpoint (none at all — --allow-full-replay). Every other id carries reason: null. message is stderr’s own text, without its leading error: prefix — the generic framing applied to every command’s own error, never part of the refusal’s own text itself; the JSON document never paraphrases it.

This is this project’s own, reusable form for a JSON refusal — refusal-v1 is extract’s own document today, but its shape (schema_version, command, refusal, reason, message) is designed as a precedent other commands adopt when next touched, not a one-off specific to extract.

Removing a received pointer: received remove. received remove <remotes/…> [--plan-only] removes one received ref’s own pointer from the received-index container — the same container bundle import/archive import write and cat/tree/checkout/extract read at a bare remotes/… point. The objects it reached are not removed, only the pointer: a stored Block or RefState nothing else reaches any more is reported by prikk verify as an unreached object, a non-blocking warning, not a failure (see verify’s own entry above). When verify also reports a damaged object, the walk cannot read past it: objects reached only through the damaged one are counted as unreached, and their publication trust is not checked, so the count can include objects that are in fact reached. verify still fails on the damage itself (verify/reachability.rs, verify/objects.rs). --plan-only reports what would be removed — the pointer’s own current target, or that there is nothing named — writing nothing, but it still takes the container’s lock for the duration of the read: the same reason compact’s own --plan-only variants do — an operator acts on what a preview reports, and the read should not go stale against a concurrent writer before it reaches the terminal; the lock is released once the read is done. A real run saves the removal to the recovery log unconditionally, naming the run id so prikk doctor --recovery-restore <id> can undo it, as long as nothing has since written to the same slot (a later, sound re-import of the identical name makes the restore refuse, rather than silently discarding it). Refuses a name that does not start with remotes/, a name with no received pointer, and a damaged received index, the same way compact --received-index already does.

Comparing: diff. diff shows what changed between two states. A bare prikk diff compares the current branch’s tip (with any queued commits) against the worktree — exactly what commit would author, so commit then diff is empty again; --from <point> compares that point against the worktree; --from and --to together compare two points, each a ref (a received ref is read, not adopted) or a bare block id. A lone --to is a usage error. Each differing path has one status: added, deleted, modified, renamed, mode or binary; a new worktree file is added, with its content, and ignored paths never appear. Text changes carry unified hunks with 3 lines of context, and a last line without a newline is marked as diff -u marks it. A rename is reported only when history (or a live prikk mv) declares one, never inferred from similar content. A binary file shows ids and sizes and never its bytes; prikk cat reads either side. A worktree path commit would refuse is named under unsupported_paths with commit’s own refusal and no content. The line diff is shortest within a work bound, above which the entry says minimal: false and its hunks, still valid, are larger. --path (repeatable, exact) filters the output, and the work is whole-tree either way. Two states that are the same give no differences and exit 0; diff writes nothing. An unsupported operation, or a blob that is missing or does not recompute, in either history fails the whole call. --format json is diff-report-v1; see Comparing.

Size bounds on incoming artifacts. RFC 158 Stage A: bundle import, bundle preview, bundle verify, sync compare, sync build and sync accept all read a file arriving from outside the repository, and every one of them refuses before reading it when its size is over the bound — on the open file’s own metadata, so nothing large is allocated to discover it is large, then enforced again while it streams, so a lying declared size is still caught. Every refusal names what was too large and its size, the bound applied (in bytes and the nearest binary unit), where that bound came from, and how to change it; none of them says “malformed” or a bundle is “persisted” data, since neither is true of an oversized but otherwise well-formed input.

Four size bounds (three overridable, the have-list fixed) and three count bounds exist — six variables in all (DC-86), none previously documented. The size bounds:

A bundle and a sync exchange artifact also each declare a count of objects they carry (bundles) or of patches/blobs/author keys/claims (exchange artifacts), bounded by PRIKK_BUNDLE_MAX_OBJECTS and PRIKK_EXCHANGE_MAX_OBJECTS respectively (default 100,000 each), and the sync summary’s ref count by PRIKK_SYNC_SUMMARY_MAX_REFS (default 100,000).

The per-object bound applies to bundle import, bundle preview, bundle verify and sync accept — everything that decodes objects from outside, never to a repository’s own commit, which is not bounded by default. It measures an object’s encoded size as it travels — its content plus a header — checked on the length prefix before the object’s bytes are copied or decoded. So a file of exactly the bound you set refuses: the header adds 69 bytes (measured, for text and binary files alike, and pinned by a test), so a file of N bytes needs a bound of at least N + 69. The refusal names the size it saw, which is that N + 69. Default: 256 MiB, the same as the total bundle/exchange bound, so it is inert at the defaults — it only acts once an operator lowers it. Resolved highest-precedence first: --max-object-bytes N on the command itself (on bundle import, bundle preview, bundle verify, and sync accept), else the repository’s own incoming.max-object-bytes in prikk config (not available to bundle verify, which opens no repository), else the default. The bound is never taken from the input it bounds — nothing inside a bundle or exchange artifact can raise it, and nothing an import or accept writes can reach .prikk/config.

What is still true for bundle verify and bundle preview, and for bundle import against a non-seekable input: an artifact under its bound is still read whole into memory, and decoding costs a multiple of that — measured on a bundle carrying one 255 MiB blob, at the defaults, three samples each (before bundle import streamed a regular file): bundle verify peaks at a median of 787,400 KiB (≈3.0× the bundle’s own size), bundle import at 1,570,984 KiB (≈6.0×). A pipe or FIFO input is read into memory in full, the same as this — a non-seekable input cannot be read twice, so it must be buffered before anything else happens.

bundle import against a regular file is different: it stays an open file, read and re-read in place rather than buffered, so its own memory follows the largest single object the bundle carries, not the whole bundle. bundle verify/bundle preview, and bundle import fed a pipe or FIFO, are unchanged and still carry the multiplier above.

prikk config is a repository’s own small, durable settings file at .prikk/config — never in the worktree, so a checked-out or imported file can never set one. One key = value per line; blank lines and # comments are allowed. An unknown key, a duplicate key, or an invalid value (zero, negative, non-integer) each refuse, naming the line, never a silent fall back to the default. The only key today is incoming.max-object-bytes. get/list print the effective value and its source ((default) or `.prikk/config`); set validates then writes atomically; unset restores the default. set rewrites the whole file and unset removes it, so a comment you wrote by hand — which the format allows — is dropped without a word: keep notes somewhere else. An older prikk build simply does not read this file — it has no effect on that build’s own behavior, and no error results from a repository holding one.

Exit codes. 0 — the operation succeeded and did what was asked. 1 — operational failure: verification findings, an integrity failure, a refusal, a dirty worktree. 2 — usage error: an unknown argument, a missing required flag, a duplicate flag. Graded verification results are in prikk verify --format json, not in the exit code.

Current State

What prikk can do today, what it cannot do yet, and the limits worth knowing before you rely on it. This page describes deferrals — things not built yet. Permanent refusals, which are a different thing, are in Non-Goals.

What works today

The local core can initialize a repository, author signed patches, seal them into blocks, inspect history, verify integrity, diagnose common repository issues, perform safe checkout planning and materialization for the supported subset, display merge evidence and merge plans for explicit sealed candidates, and execute a merge when the two sides are proven confluent — refusing cleanly, with no object, WAL, or ref write, when they are not.

Cross-platform history identity is tested, not assumed. Prikk authors, commits, and checks out on Linux, macOS, and Windows, and CI requires a repository authored on Linux, mutated on Windows, and verified back on Linux to produce byte-identical object ids — so the claim that anyone can verify anyone’s history holds across the three.

Known limits worth stating up front: merge-base discovery is manual; conflicts are detected and refused but never resolved; sync exists between repositories, but prikk does not move the bytes itself — confidentiality is the user’s channel’s property, not prikk’s — negotiation is branch-scoped (tags travel and are adopted separately, under the receiver’s own key), and there is no discovery or remote-tracking; verify cost is linear in history length; verify checks author signatures repository-wide, but only as trust-on-first-use continuity — it proves the same author signed as last time, not who that author is on first contact; and verify checks a locally-published tag’s maintainer signature against this repository’s own trust policy, but a received, not-yet-adopted tag is deliberately exempt — its signature is the sender’s, under a key this repository has not adopted.

Next increment candidates are tracked in ROADMAP.md.

Not a good fit yet

Prikk is not yet the right tool if you need:

• a production replacement for Git;
• stable repository-format compatibility;
• Git object compatibility or transparent Git interoperability;
• hosted forge workflows, or remotes;
• complete branch management, or semantic merge;
• plugin/audit execution, attestations, or automated publication controls;
• mature key lifecycle features such as revocation, rotation, hardware signing, or thresholds;
• flexible exclusion of generated files — .prikkignore (since 0.29.0) takes literal repo-relative path prefixes, one per line, with no globbing, no negation, and no per-directory files, so patterns like *.log do not work; and a file swept into history by mistake still cannot be removed later.

Known limitations, measured

Disclosed here rather than left implicit, each with the figure it was measured at and the release it is planned for.

• Trust keys, trust policy, author keys, the received index, and the three generation logs now have a tail defined by position, a verify/doctor line, and a repair (fixed in 0.49.0, RFC 164 Rules A/B/C, then corrected by §9). Before this round (N2’s remainder, N7, N10, M4): a torn prefix at these seven files was a repairable-looking tail, but 100 or more zero or random bytes at the same position was damage under their own pre-0.49.0 shape rule – trust maintainer add, a commit, or bundle import refused with “<container> has a damaged entry”, a generation log’s own reader refused every command that resolves a ref (on the pointer index’s own log) or just compact (on the other two), and none of the seven had a repair verb – the way out was a manual backup-and-truncate. Rule A first defined a tail as “everything after the last sound record, whatever its shape”; §9 corrected this the same round, before release, once measurement showed it let a complete last record with a failed checksum be truncated as a tail – for a file whose last record carries a decision (the trust policy’s latest snapshot, a generation log’s live slot, the pointer index’s newest pointer), that silently re-asserted the previous decision. A single flipped body byte in a real trust policy snapshot, followed by the pre-§9 --repair-tails, silently re-trusted a key that snapshot had just revoked, verify exiting 0 throughout — measured on a release build before this was closed. §9 was itself incomplete: it decided “complete” from the header’s own magic, version, and length fields, and any one of those three can itself be the single corrupted byte. A flipped header field rolled every reader back to the state before the last record, before any repair even ran – §9.2 corrects this: completeness is decided by the checksum, recomputed with the format’s own real magic and version constants over either the claimed length or the length to the end of the file, whatever the stored header fields say. Verified exhaustively, not sampled: every single byte offset of a last record, across the trust keys, trust policy, author keys, the received index, the generation logs, and the pointer index, is now asserted (a cheap, decode-only test per format) to never decode as a tail. Now: a tail is an incomplete record or bytes that are not a record header, when nothing sound follows; a complete record (its checksum verifying one of the two ways above) is damage, even when last, however its header got corrupted. verify and doctor report a tail as a warning (never failing on it alone) and interior damage (including a complete, corrupted last record) as a failure; prikk doctor --repair-tails truncates every genuine tail these seven files (plus the WAL and the pointer index) have, in one run, saving what it removes first, and refuses – unconditionally, changing nothing – if any covered file has interior damage, including a complete corrupted record. What remains: interior damage still has no automatic repair – by design, the same as every other covered file – so the way out for it is still manual (back the file up first, ask before truncating; a complete corrupted record has no offset a repair can safely act on at all). Corruption spanning more than one field of the last record (for example a zeroed sector, touching the checksum and other fields together) can still read as a tail: the checksum-decides rule above only resolves a single field’s own corruption against an otherwise-intact record. Telling that shape apart reliably needs a per-record witness (format 8), not yet built. The object containers’ own short tails (N7) are now reported too (verify/doctor print a trailing-partial byte count per persisted object type), reporting only, no repair, per the review’s ruling. The ref log’s own tail (M4) and N3’s interrupted publications are now settled (RFC 165, 0.49.0): the ref log is Rule B’s eighth reported file and --repair-tails’s tenth covered one (§9.2 applied to it the same as the other seven); a torn last record with a completable pointer lead is an interrupted publication, completed by prikk ref complete <ref> (any adopted key, not only the one that started it), never truncated as a tail. Disclosure, released versions (no advisory, per the owner’s ruling); code history kept apart from measurement: the code shipped in 0.20.0 for all three files (trust policy 2827fab7, the pointer index 0550e340, the three generation logs b33d1942), confirmed from history, not measured directly. Measured on 0.46.0, 0.47.0, and 0.48.0 (0.20.0-0.45.0 not independently confirmed), with one reader per file – trust maintainer check for the trust policy, branch list for the pointer index and its generation log, not every reader (round 2’s own exhaustive, all-reader sweep is against the fixed 0.49.0 build, not these historical releases): a length-field flip in the trust policy’s last snapshot read straight through to the previous one on all three measured versions, verify exiting 0 throughout (0.46.0’s and 0.47.0’s own verify does not read the trust files at all; 0.48.0’s reads them but still exits 0 for this shape). A length-field flip in the pointer index’s or its generation log’s own last record rolled branch list back to the previous tip or slot on 0.46.0 and 0.47.0, verify exiting 1; on 0.48.0 the generation log refuses instead (its own one-byte-body rule rejects any length but exactly one), but every byte, header or body, flipped in the pointer index’s own last record rolls branch list back with no repair involved, and a body-byte flip (checksum mismatch) is separately truncatable by doctor --repair-pointer-index-tail as a tail, reverting the ref’s tip while verify stays failed both before and after. A flipped magic or version byte is refused on every measured released version – that rollback shape existed only in this release’s own, unreleased Rule A, never shipped. All fixed in 0.49.0 by §9 and §9.2.

• A bundle import interrupted by a crash could leave a block durable while the patch, blob, or parent block it names is not, and no repair cleared it (fixed in 0.49.0). In 0.48.0 and earlier, objects were written in the bundle’s own carried order, not in dependency order – across kinds, and, within one kind, a child block could be listed before its own parent. An interruption partway through could leave verify failing for good with one of: “object <id> references missing snapshot blob <id>” / “… missing block patch <id>” / “… missing parent block <id>”; “snapshot of Block <id> names Blob <id> for <path>, which is missing”; or “lifecycle replay: blob <id> required for a state effect is missing” – while a commit was still accepted. None of the three doctor repairs cleared it – re-running the same import cleared it in every case reproduced (25 of 25). Reproduced at 89 of 300 kills on 0.48.0 and 136 of 300 on 0.47.0, with an 80-file bundle; present since bundle import was first introduced (0.20.0). Fixed in 0.49.0: every writer that lays down more than one object in a single command – bundle import, sync accept – now writes them in dependency order, both across and within kinds, so a new interrupted write can no longer produce this shape. What remains, after RFC 164 Rule E (0.49.0): verify still needs the original bundle to make such an object whole, but no longer fails forever over one nothing in the repository actually needs. verify/doctor now classify a stored object’s own dangling reference by reachability from committed state (a ref, a received pointer, a queued patch, or a sealed block reached from them): reachable, it is still the same hard failure named above; unreachable, it is an unreferenced remnant – a warning, naming the object and what it lacks, and verify exits 0. No command removes a remnant in 0.49.0; re-running the same bundle import is still the only way to make a still-needed one whole, exactly as before this round.

• Existence checks on RefState, Tag and Attestation references (0.49.0 step 5, round 2; the Attestation half 0.50.0 step 2 Part B). verify requires each attestation a RefState’s required_attestation_ids names to be present as an Attestation object (a typed read), and now also decodes it (AttestationPayload::decode_canonical, added this round) and requires its own target_block_id to be present too. bundle import refuses before any write on either gap: an absent attestation, or one present but naming an absent target block. No producer in this repository writes a non-empty required_attestation_ids list, so an honest repository cannot fail either check. Still disclosed as a gap: a received ref’s previous_ref_state_id is not required by bundle import. verify does check a received tip’s previous state (one read), and bundle import refuses a bundle whose ref chain is not carried.

• A crash inside branch create or tag create now has a command that completes it (N3, fixed in 0.49.0). Before this round: the ref log’s last record is torn; verify fails with PRIKK-VERIFY-REF-DIVERGENCE and doctor recommends manual recovery, but retrying the same branch create/tag create answers “already exists” rather than finishing the interrupted publication – DC-38’s own retry exists for seal only. Reached through merge too: a crash mid-publication leaves the same PRIKK-VERIFY-REF-DIVERGENCE state, and re-running the same merge answers “not confluent” rather than finishing it. Measured for merge: 10 of 300 kills on 0.48.0, 16 of 300 on the 0.49.0 build carrying the dependency-order fix above. Fixed in 0.49.0 (R1-R3): every publication (seal, branch create, branch close, tag create, sync adopt-tag, merge) now refuses before its first write while another ref’s publication is incomplete – the same refusal commit already gave – so a seal (or any other publication) can no longer bury an unrelated ref’s torn record behind its own, appended content. A publication’s own retry of its own interrupted state is never blocked by this (seal’s DC-38 retry still completes). Fixed in 0.49.0 step 3 (R4-R6): prikk ref complete <ref> completes an interrupted branch create/branch close/tag create/sync adopt-tag/merge publication the same way seal’s own DC-38 retry always completed its own – by any adopted maintainer key, not only the one that started it. Every condition evaluated before any write (the leading RefState verifies under current trust, chains cleanly, names a target that exists, and, for a WAL-consuming publication, retained WAL evidence still matches); a lead that fails is left alone (not completed), and the entry point’s own “already exists”/“not confluent” refusal now names prikk ref complete <ref> when that is why. sync seal remains locked out of its own interrupted publication: its own precondition cannot yet tell “my own retry” apart from “another ref’s incomplete work,” so it refuses both – a known, disclosed gap, not worked around in this round. A lead that fails R4’s rule entirely (an untrusted or revoked signer, a broken chain, a missing or wrong-kind target, or mismatched WAL evidence) has no automatic completion; prikk doctor --rebuild-pointer-index re-derives the pointer index from the ref log instead, dropping that one lead (named) while leaving every other ref untouched – it refuses outright if any lead anywhere is completable, since completing it is the correct fix and a rebuild would otherwise discard an authorized transition. Addendum 1: a ref-log tail with no pointer lead (zeros, random bytes, or any torn prefix left for a reason unrelated to a pending write) is not an incomplete publication – commit and every other writer that does not append to the ref log proceed over it; every publication still refuses over it (RFC 164 Rule D: a writer refuses over a tail in a file it appends to), naming the tail’s own offset and byte count; its repair is prikk doctor --repair-tails, the same as the other nine files it covers.

• Fixed in 0.49.0 (N6): a damaged last WAL record is no longer removed uncritically as a tail. RFC 162 rule 3 used to define the WAL’s tail by position, not shape: a last record whose own bytes are all present but whose checksum fails was indistinguishable, once nothing sound followed it, from a genuine crash-torn append – so --repair-wal-tail removed it either way, even when it was a commit the user had already been told succeeded. A commit now writes a small local witness alongside the WAL (the count, Patch id and frame hash of the last record it acknowledged); verify, status and every writer read it before a tail speaks. A genuine, never-acknowledged crash tail is still removed exactly as before (--repair-wal-tail, --repair-tails). An acknowledged commit that is now damaged or altogether missing refuses instead (verify exits 1; commit/seal/rollback-draft refuse, naming it) – prikk doctor --discard-damaged-commits [--plan-only] is its own way out, never folded into the tail repair’s single meaning.

• Fixed in 0.49.0: a crash during a commit after the first one in a session could leave ref-name empty while the queue still held records (0.20.0-0.48.0). Every commit, not only the first, used to rewrite this small file by a durable truncate then a durable append; a crash between the two left nothing durable naming which ref owned the queue. The file is now written once per session, by the first commit only – a later commit never touches it again, so no commit past the first can tear it. verify and doctor exit 1, and commit/seal/rollback-draft refuse, over any session still stranded from before this fix (or over the same ref-name-vs-witness disagreement by a different route). prikk doctor --restore-queue-target --ref <ref> [--plan-only] is the way out – the ref always comes from the caller, never from the witness; see the troubleshooting entry for the exact text.

• Fixed in 0.49.0 (R1): a ref publication now reads the whole ref log once, not three times. classify_state’s own replay is threaded through the append’s idempotency check and the post-write agreement check (a ranged read-back of just the bytes appended, not a fourth whole read). Measured at generations 4, 64 and 1,024: 3 whole reads before, 1 after, at every depth; about 1.8× faster at depth 1,024 on a release test binary. What remains: the write-path precondition (M8, below) used to share this same three-reads shape but is now fixed separately; reconciling this round’s own ~417 B/generation figure against an earlier ~4.3 KB/generation measurement (likely counting more than the ref log alone) was not settled.

• Fixed in 0.49.0 (R2): a commit’s own write-path precondition no longer checks every ref’s whole history. ensure_no_incomplete_publication used to run a full verify_refs, replaying the ref log once per ref – a commit touches no ref, yet paid refs × log size. Now one pass over the pointer index and one over the ref log, comparing each ref’s newest pointer with its newest log record. Measured (release build): 62 µs at 1 ref before and after is noise-level, but 6.3 ms → 108 µs at 100 refs, 74 ms → 417 µs at 400, and 6.8 s → 4.4 ms at 4,000. verify/doctor keep the fuller check (chain continuity, signature-envelope structure, missing-object detection) this precondition never needed.

• Listing objects by type reads that type’s whole container, including on sync seal’s own path. Deferred to 0.50.0 or later (ROADMAP.md, the 0.49.0 schedule).

• Fixed in 0.53.0 (F4): a one-file commit no longer reads every stored blob to learn its kind, exactly at a checkpoint; between checkpoints it follows the content added since the nearest one. Before 0.53.0, a cold baseline — a branch switch, a step the cache’s own one-block fold cannot take (two seals since the last resolution, or a merge block), a missing or damaged lifecycle-state.v1 specifically, or every 64th resolution (the forced reanchor) — replayed the whole lineage, reading every historical blob’s frame to re-derive its kind: 1 MiB of stored content read 1.1 MB, 16 MiB read 16.8 MB, 64 MiB read 67.1 MB. The cold baseline now derives from the nearest checkpoint this repository has itself sealed or verified under an adopted maintainer key (RFC 159’s anchor-trust function, the same one seal/merge/sync seal already use), and folds only the blocks after it (at most 63). Measured, one 1 MiB file rewritten and sealed per generation, a cold commit after each generation shown (candidate against 0.52.0, release build, time in ms / peak RSS in KiB): generation 1, 16/11,888 vs 18/11,696; 32, 81/12,104 vs 80/12,380; 63, 144/11,844 vs 144/11,888; 64, 146/11,888 vs 146/12,160; 65 (a new checkpoint), 14/11,876 vs 149/12,040; 70, 26/11,888 vs 157/11,984. Both binaries pay the same cost up to the next checkpoint; the candidate drops once a new one exists, 0.52.0 never does. With no checkpoint in reach at all (a repository that has only ever received history, before its first local seal or verify), the full replay still runs, unchanged. A restore, a fresh clone, or deleting the whole .prikk/cache/ directory also removes the checkpoint record (.prikk/cache/replay-verified-blocks.v1 — a different file from the incremental cache this fix targets), so a cold commit there is in exactly this no-checkpoint case: it costs what it did in 0.52.0 until the next prikk verify or seal rebuilds the record. Measured: 32 ms at 16 MiB stored on the commit right after deleting .prikk/cache/, 1 ms on the commit right after a verify rebuilds the record. verify records the checkpoint whether or not it exits 0: the write (verified_blocks::record_verified_blocks, called while verify_repository_with_options still builds its own report) and the exit-code decision (verify_verdict’s own publication-trust check, read only afterward) are two separate steps — a failing trust check cannot prevent a write that already happened. Measured: a received ref signed by a key this repository had not adopted (bundle import, never followed by trust maintainer add) made a release build’s prikk verify exit 1 for “repository has publication-trust issues”; with the record file deleted first, it reappeared afterward regardless, 112 bytes, identical to a run before the deletion. The every-64th forced derivation is counted in the cache file itself, so this bound holds only while a cache file is present. The residual, extending RFC 159 ruling C1 from seal to commit: a state root (and a checkpoint’s own manifest) commits to a file’s blob id, never to its bytes, so neither seal nor a cold, anchored commit re-reads the content of a blob no live file names. Measured, below the checkpoint: a commit that edits the damaged file as text still refuses (it reads the old content to apply the edit); a commit that replaces it, appends to it (binary), deletes it, renames it (a declared move never reads old content either), or touches a different file entirely all succeed. verify still reports the damage in every succeeding case. With no admitted checkpoint, every one of these still refuses, unchanged.

• Fixed in 0.49.0 (RFC 165, M4): verify reports garbage bytes in the ref log. Before 0.49.0, 100 zero bytes appended to the ref log container: verify and doctor exit 0 with no warning, a seal appends behind them, and verify stayed 0 with the garbage in the middle of the file. The state was harmless (ref-log records are signed and chained), but nothing reported the bytes. The ref log is now a reported file, and --repair-tails covers it.

• Fixed in 0.49.0 (RFC 167): resynchronisation over hostile content is linear, not quadratic. verify over a WAL torn tail packed with fake frame headers used to grow from 0.24 s at 256 KiB to 13.98 s at 2 MiB, extrapolating to hours at 64 MiB (a plain, unpacked tail stayed 0.01–0.02 s at every size, so the cost was specific to the hostile shape). Six readers shared the defect: the WAL, object containers, trust policy, the received index, the ref log container and the pointer index. Each now carries a work budget (bytes hashed, at most 8x the input) shared by every candidate the resynchronisation scan visits; a scan the budget cuts short is always reported as damage, never silently read as a tail. Measured at 64 MiB: 0.25–0.29 s, down from a projected 2.8–4.6 hours. Not a self-vouching header (a header-only checksum, which would remove the re-parse entirely): that is a format change, format-8 input, still planned for a future increment, not this one.

• A commit holds all new file content in memory at once. 64 files of 4 MiB each peaks at about 284 MiB. Streaming and chunking (large objects, Stages B–D) are not yet built.

• The object index’s own lookup is a linear scan, and the whole index is held resident in memory for the duration of a write session. Not yet fixed.

• bundle import peaks at about 4.6 times the bundle’s size in memory (5.26 GiB for a 1.15 GiB bundle), from whole-file and whole-object buffering. Found during RFC 155’s design round, outside that RFC’s own scope; a candidate for a later release. prikk archive import does not share this defect: it processes one object at a time, so its own peak RSS is bounded by the single largest object the archive carries, not by the archive’s own total size — measured at about 5 times the largest object’s own size (an earlier version held a whole object type’s own batch at once, measured at 2.25 times the archive’s own size for 1 GiB concentrated in one type; fixed before 0.51.0 shipped).

• prikk extract’s own peak memory tracks the largest single file it actually reads, not the point’s own total content size (0.54.0): every file whose content has not changed since the admitted anchor streams straight from its stored blob id, one at a time, and only a text file edited since the anchor (at most 63 blocks of edits) is held resident. Measured against the real, shipped implementation (release build, fresh process per sample, /proc/self/status’s own VmHWM): a 64-file, ~62.6 MiB mixed text/binary point sitting on a checkpoint (no file larger than about 1.6 MiB) peaks at about 4.5 MiB over the process floor; a since-checkpoint point whose largest single file is a 24 MiB binary (16 MiB more added across 32 further generations) peaks at about 50 MiB; a 30-generation, checkpoint-free lineage whose largest single file is about 1 MiB peaks at about 3 MiB. The real figure is closer to twice the largest single file’s own size, not once: decoding any Blob’s canonical payload (BlobPayload::decode_canonical) copies its content into a fresh Vec rather than reusing the envelope’s own already-read bytes, so the envelope and the decoded content are both resident for a moment. This is why the since-checkpoint point’s own 24 MiB file dominates its own measurement (about 2x its own size, not the point’s own 24.5 MiB total); a damaged blob anywhere at the point still refuses the whole extraction, the same all-or-nothing guarantee every other patch-replay reader gives.

• --plan-only costs the same as a real write, not less (0.54.0): it reads every file’s content once to measure it (plan_summary, crates/prikk-cli/src/extract.rs), the identical read a real write already pays, and only skips the write itself. Measured: on the since-checkpoint shape below (a 24 MiB file, a separate growing.bin reaching ~1.7 MiB across 32 further generations), a whole extract --ref run peaks at about 55,250 KiB (ru_maxrss, two samples: 55,400 / 55,100 KiB) and extract --ref --plan-only peaks at about 54,994 KiB (55,052 / 54,936 KiB) — functionally the same cost, over a process floor (prikk log --limit 1) of about 12,376 KiB (12,368 / 12,384 KiB). This matters for planeter’s own size report: asking only for the size is not a cheap operation here, and the text must not imply otherwise.

• --claim’s own whole-command peak memory follows the identical “roughly twice the largest file read” rule as the ref/block-id path — there is no anomaly (0.54.0). An earlier measurement compared --claim’s own planning phase alone (prepare_extract_plan_for_claim, which derives state through derive_next_state_for_candidate — the identical mechanism seal/ merge/seal-from-accepted already share, not patch_replay::extract’s own block-chain replay) against a page that otherwise describes the whole command’s own cost, which reads as one property when it was two: a first draft of that planning-only figure also had a fixture-construction mistake (32 distinct new files instead of one file repeatedly replaced), caught and corrected before it reached the architect — see the review record for the full account. The planning phase alone, corrected, costs little (release build, fresh process per sample, /proc/self/status’s own VmHWM, process-floor baseline subtracted, ~7.0 MiB): on a parent shaped like the figure above (64 files, ~64 MiB, sitting on a checkpoint), ref/block-id peaks about 2.2 MiB over the floor during planning alone, --claim about 2.9 MiB; on the since-checkpoint shape, ref/block-id peaks about 6.9 MiB over the floor during planning alone, --claim about 7.5 MiB — both about 1.1–1.3x, not a scaling anomaly (a plausible, bounded reason: StoreBackedResolver::blob_kind, lifecycle_cache/store_resolvers.rs:80-94, decodes a Blob’s entire payload just to read one field, once per CreateFile/ReplaceBinary the derivation folds forward, and the claim’s own one extra CreateFile pays this once more than the ref/block-id path’s own equivalent planning step does). The whole command, measured end to end (a real extract --claim <id> <dir> subprocess, on the identical since-checkpoint repository the ref/block-id figures above were measured against, ru_maxrss, two samples: 54,200 / 54,212 KiB): about 54,206 KiB, against the whole extract --ref run’s own 55,250 KiB over the identical ~12,376 KiB floor — the same order of magnitude, not a multiple of it, because both commands are dominated by the same final step: streaming the repository’s own largest file (here, the untouched 24 MiB genesis.bin) once, through the identical BlobPayload::decode_canonical double-buffer named above. --claim’s own small planning-phase overhead is real but negligible next to that one shared, dominant cost. Nothing here needs further investigation before 0.54.0.

• Fixed in 0.52.0: in 0.51.0, an archive of a repository that has accepted a sync artifact (sync accept), or where a text file was edited, sealed, and later deleted, failed its own archive verify and did not import — even though the source repository’s own prikk verify passed cleanly. The archive’s own closure check required every reference to resolve, more strictly than the store itself does for an accepted-but-unsealed claim’s own references or a sealed patch’s blob references. Both failures were fail-closed: nothing was written in either case, and the source repository itself stayed untouched. The archive’s own closure pass now shares the store’s own existence rules directly, so it checks exactly what, and exactly where, the store itself checks — a 0.51.0-written archive of either shape imports cleanly under 0.52.0, provided its own source repository verified clean.

• A repository holding any file over 256 MiB cannot be archived or bundled (the bound archive import/bundle import already enforce on the way back in, DEFAULT_BUNDLE_MAX_OBJECT_BYTES). archive export refuses up front for any over-bound object anywhere in the repository; bundle export refuses up front for any over-bound object the one exported ref reaches. Before 0.52.0, archive export wrote such a file successfully, and only a later archive verify/archive import refused it — fixed alongside the closure defect above. A copy of this repository’s own .prikk/ directory is the real backup for a repository in this state.

• Content imported under a key this repository does not adopt (bundle import, archive import) is stored, and prikk verify reports its publication trust until that key is adopted. Replacing a received pointer with a later, sound import of the same ref moves the pointer, but does not remove the objects the earlier import wrote — there is no command that removes stored objects. A copy of this repository’s own .prikk/ directory, taken before the import, is the way back. 0.54.0 (RFC 164 Rule E) changes what happens once the pointer has been replaced: a stored Block or RefState that nothing in committed state reaches any more (the same reachability RFC 164 Rule E already computes for a dangling reference, applied here to the object itself) is reported as an unreached object, a non-blocking warning, and no longer fails verify’s publication-trust check. When verify also reports a damaged object, the walk cannot read past it: objects reached only through the damaged one are counted as unreached, and their publication trust is not checked, so the count can include objects that are in fact reached. verify still fails on the damage itself (verify/reachability.rs, verify/objects.rs). While the received pointer is still present, everything it reaches stays reached, and verify keeps failing on it exactly as before — this changes nothing for an import whose pointer has not yet been superseded. The bytes stay either way; no command removes them yet. 0.54.0 (received remove) adds a second way the pointer itself can go, on purpose: prikk received remove <remotes/…> removes the pointer directly, the same consequence as replacing it (everything it alone reached becomes an unreached-object warning on the next verify), without waiting for a later, sound import to happen to supersede it. The objects themselves are still not removed by this or any command.

• A WAL whose damage exhausts the resynchronisation scan budget has no repair command (RFC 167). prikk doctor reports the failed record and recommends preserving the repository and inspecting it; no command in 0.49.0 removes the damage, so the way out is a backup or a clone. (Reproduced with the hostile M5 repository at 256 KiB: doctor exits 1 with this recommendation.)

• Fixed in 0.53.0 (M6): a commit reads the queue three times, not four. Before 0.53.0, every commit read the active WAL in full, under one held lock, four times: the publication-cleanup check (is a prior seal’s own drain of this queue still incomplete?), the authoring read (the tail/damage check, the active-queue limit, the commit-witness classification, and the baseline fold over already-queued patches, all off one pass), the pre-append check immediately before the durable write (the tail is clean, no record is damaged anywhere in the queue, the next sequence number, an idempotent retry), and a fourth, redundant replay() that ran no check of its own – it existed only to fold the commit witness’s own running hash from bytes the second read had already decoded. That fourth read is gone: the witness now folds over the records the pre-append check already holds. The three reads that remain each still do real work, and the cost stays linear in the queue’s own length on purpose, so that a damaged queued commit is always noticed before more work is stacked on top of it. Measured at 100 / 800 / 3,200 queued commits: 207,555 / 1,610,968 / 6,422,700 bytes before, 157,046 / 1,209,605 / 4,818,404 after – about 25% fewer bytes at every depth. The external review’s own 6.2 ms at 800 / 4.0 ms at 100 (0.48.0) is unaffected: those figures were never doubled by the redundant read removed here, since the external review predates RFC 166’s own witness fold entirely. Source: external review 014, 014-review.md:175-179.

• One damaged blob makes every file at that point unreadable (M7). The replay is whole-tree, so prikk cat --path fails for the intact files as well, and there is no salvage read that returns the sound files and names the damaged one. Deferred to 0.50.0 or later (ROADMAP.md, the 0.49.0 schedule). Source: external review 014, 014-review.md:208-213.

• Three Windows residuals of the recovery log (RFC 168 §6, accepted). Each is a new-name or rename case that Windows has no primitive for, so none is closed in 0.49.0:

  • (a) worktree files after a completed branch switch or checkout may not be durable after a power loss. The route: move the files prikk worktree-status lists as modified out of the way, then prikk checkout --patch-materialize --ref <current branch>. Missing files are written by that checkout; a file the user deleted and the checkout writes back is removed by the user.
  • (b) a repair’s save in the same Windows boot as the log’s creation, in a repository created before 0.49.0. The log is created by the first write command, so this is rare.
  • (c) the witness’s first creation, in a repository created before 0.49.0. A lost creation falls back to the older classification (RFC 166 rule 3), the one a session written by an older binary gets today.

What scale to expect

The list above is about missing features. Scale is a separate question, and worth stating on its own: what happens as a repository’s history gets deep, or its tracked file count gets large. Every figure below was measured with a release build (the build you install) on Linux, on the development state that shipped as 0.47.0 (a build that reported 0.46.0, plus the changes the CHANGELOG lists under 0.47.0), on the RFC 139 corpus profile prikk-self (a real project’s shape; 155 tracked files at depth 256). Each figure names the depth range it rests on. Depth is the number of sealed blocks.

• Sealing cost grows roughly quadratically with history depth, and per-seal cost is worse than linear. seal derives the next state root by walking the ancestor lineage, so each seal costs more the deeper the history is. Three independent builds, each grown to depth 1,024 (the deepest measured), median of three, mean over the 16 blocks ending at each depth:

  depth	one seal	cumulative time to build to it
  32	0.09 s	4 s
  64	0.18 s	11 s
  128	0.30 s	30 s
  256	0.64 s	98 s
  512	1.4 s	6.4 min
  1,024	5.0 s	34 min

  The per-seal exponent is 1.2 over depth 32–1,024 (1.15–1.24 across the three builds) and rises with depth: it is about 1 up to 256, and 1.6–1.8 between 512 and 1,024. The cumulative exponent is 2.0 over depth 128–1,024 (1.9 over 64–1,024). Quadratic is the release build’s shape too, but only from about depth 128 on: over depth 32–128, the only range a debug build measured, the cumulative exponent is 1.4 in release against 1.96 in debug (the cause was not investigated). A release seal is 15–33 times cheaper than a debug one at the same depth (0.30 s against 9.9 s at depth 128). Every 64th seal also writes a checkpoint and costs more than an ordinary one: about twice as much near depth 128 (the seal of block 129 took 0.61 s against 0.31–0.33 s for blocks 128 and 130), less at depth, because the lineage walk dominates both (1.6× at block 513, 1.4× at 961). The per-seal figures above are means over windows that end at every 64th block and so never include one of these; the cumulative column does include them. This is the figure that decides how long it takes to build, or import, a deep history, and it has been measured only to depth 1,024; the build to 2,048 was not attempted (the 2-hour rule stopped it, its build having been projected at 2.3 hours). Nothing here is projected past 1,024. 0.48.0 changes this. seal, merge and sync seal start from the nearest checkpoint that an adopted maintainer signed and fold at most 63 blocks instead of walking the lineage. Release build, alternating with 0.47.0’s, three samples each (a shared machine, 1-minute load 1.0–2.8 at each step’s start), medians:

  	0.47.0	0.48.0
  one seal at depth 256 (an ordinary block)	0.64 s	0.07 s
  one seal at depth 1,024 (an ordinary block)	4.5 s	0.12 s
  the last ordinary block before a checkpoint, depth 1,024	4.3 s	0.46 s
  the seal that writes a checkpoint, depth 1,024	6.1 s	1.8 s
  sync seal --claims of a 64-block catch-up, depth 1,024	254–280 s	17.9–18.5 s
  cumulative time to build to depth 1,024 (three builds)	1,947 s	279 s

  It is not flat. A 0.48.0 build to depth 2,048 (three builds; 0.47.0 was not built that deep) averaged 1.7 s per ordinary seal over its last 16 blocks and 1,308 s cumulative: the fold and the checkpoint write grow with the size of the tree, not with depth. A checkpoint that no adopted maintainer signed, or that lies more than 63 blocks back, is not used, and the command does the full walk, as 0.47.0 does.

• Sealing also needs memory that grows with the square of depth. One seal’s peak resident memory, measured with getrusage on the 0.47.0 release build: about 124 MiB at depth 256 and about 1.8 GiB at depth 1,024 (1,874,000 KiB sealing block 1,025, three samples). seal keeps a copy of the tree’s state for every block of the lineage it walks. At depths past a few thousand blocks, memory rather than time is the first limit. In 0.48.0 it does not: one seal at depth 1,024 peaks at about 30 MiB (29–30 MiB over ordinary blocks, 53 MiB for the block that writes a checkpoint; three samples each), against 1.8 GiB, and a 64-block sync seal catch-up at that depth peaks at 56–57 MiB against 2.0 GiB.

• Checkout is close to linear in depth; merge-evidence is a little worse, and both are cheap at these depths. From depth 32 to 256: checkout --patch-plan 36 → 152 ms and checkout --patch-materialize 125 → 591 ms (exponents 0.70 and 0.77; the tree itself grew as depth^0.84, 29 → 155 files), and merge-evidence 34 → 455 ms when the two sides only add files (exponent 1.28; the baseline’s replay is all it does). When each side edits files that were edited before, merge-evidence costs 69 → 473 ms (0.97). Peak memory at depth 256 is about 11 MB for all of them (polled VmHWM). Cost tracks history depth, not repository size, but at these depths depth is cheap: a commit that has to replay the whole history (no cache) measured 69 ms at depth 33 and 494 ms at depth 256 (exponent 0.96). The depth^1.45 figures this page used to give were measured before 0.43.0 (checkout was not yet anchored), at checkpoints that a divergence had shifted, in a debug build. A debug build measured today gives nearly the same shapes as release over the same depths (0.68 and 1.26), and costs 8–30 times more at each depth.

• A commit that can use the cache costs about the same at any depth we measured. Between seals, the second and third commit, and a commit after worktree-status, take 39–44 ms at depth 256, against about 475–507 ms before 0.47.0 (they replayed the whole history each time). A commit at a tip that edits text an earlier block edited, 487 ms → 52 ms; the same commit editing that file, 936 ms → 53 ms. The cache’s independent full replay still happens every 64 uses. Depth range 32–256; three interleaved runs each.

• Incremental commit memory is flat up to a few thousand tracked files, then grows linearly at roughly 1.7 KiB per file beyond that — measured peak around 11.6 MiB at 100 files and 113 MiB at 64,000 (release, three samples at each of seven sizes).

• Before 0.48.0, a command’s memory also followed the size of what the repository stored. Every object write read its whole object container into memory only to learn its length, and reading an object back read the whole container to decode one record. A commit that added one small file to a repository with a 256 MiB blob container peaked at 266 MiB on 0.47.0; on 0.48.0 it peaks at 22 MiB, the same as with an 8 MiB container (22 MiB; release build, three samples each, container sizes 8, 64 and 256 MiB). A first commit of 4,000 files of 20 KB read 162 GB on 0.47.0 and reads 81 MB on 0.48.0 (16.2 s → 0.3 s), about the size of the files themselves: what a first commit reads now doubles when the file count doubles (1,000 files 20 MB, 2,000 files 40 MB, 4,000 files 81 MB). The writer used to re-read the whole object index after every object write, which was quadratic in the number of objects (a first commit of 8,000 files of 40 bytes read 9.4 GB; it now reads 1.6 MB).

A few things worth knowing about these numbers before relying on them:

• They describe shape and order of magnitude, not a guarantee for any particular repository. They were measured against a small corpus of profiles — two profiles, chosen deliberately at opposite ends of one axis but also differing 46x in breadth from each other, so results are bracketed by two shapes rather than interpolated across every shape a real repository might have. The timing figures above use one of them, prikk-self.
• The evidence is not equally deep. The sealing figures are three builds to depth 1,024; the checkout and merge-evidence figures are five depths (32 to 256), three samples each, so their exponents are direction, not a fitted curve; the cache figures are five cells, depth 32–256; the commit-memory figures reach 64,000 files.
• The machine was shared with other work (load average 1.7–13 during the sealing builds), which is why each sealing figure is the median of three and why absolute times can move by up to about two times between runs. Ratios within a table are the sturdier reading.
• All of the above was measured on Linux.

Release, Versioning, and Compatibility

This page defines Prikk’s current pre-1.0 compatibility and official-release policy. It separates source versioning, Git release identity, external distribution, and evidence so a release does not need later housekeeping to become truthful.

For repository format details, see repository layout and authority. For identity-bearing objects, see the data model. For persistence limits, see durability and crash recovery.

Core Caveats

• Prikk is pre-1.0 experimental software, not a production Git replacement.
• Cargo APIs, CLI behavior, object schemas, and repository formats are not generally stable.
• No migration path, support window, LTS line, or 1.0 schedule is promised.
• The workspace version alone does not identify an official release.
• Current release checks are partly manual. cargo deny is not a configured gate. cargo audit is: it runs as a standing release gate locally (--no-fetch, rfcs/EXECUTION-ORDER.md §6 rule 9) and as a scheduled CI job every Monday against a freshly fetched advisory database (.github/workflows/security-audit.yml), so an advisory that arrives without any code change is still caught.
• Releases are made by one maintainer under their own signing key, by the procedure in RFC 152 — see How prikk releases below. In v0 there is no second signer, no support window (only the latest release gets fixes) and no stability promise for the object format, the CLI’s JSON schemas or the library API. Each is absent on purpose and named here so nobody discovers it after depending on it.
• release-signers.toml is empty because no multi-signer policy exists yet, not because releases are unsigned: every release tag is signed by the maintainer key and verified before it is pushed. The file gains entries the day a second maintainer with a release key exists (§ What changes as the project grows).

Compatibility Surfaces

Prikk treats these as separate compatibility surfaces:

• Cargo crate source APIs and feature sets;
• command names, arguments, exit behavior, and human-readable output;
• canonical object schemas, signature preimages, ObjectIds, and identity domains;
• repository format, on-disk layout, and migration/refusal behavior; and
• source archives and published documentation.

Before 1.0, a minor release may intentionally change documented Cargo or CLI surfaces when release notes identify the change. Repository-format changes additionally require an accepted governing RFC with a new format/schema where applicable and explicit directional read, write, migration, and refusal behavior.

SemVer and release notes cannot authorize silent identity mutation. A signature preimage, ObjectId, canonical identity schema, or domain change requires accepted design authority, a new explicit version or domain, refusal or migration behavior, and literal compatibility vectors. Existing identity versions are never reinterpreted.

Format Stability Contract

RFC 114, answering badge criterion 2 — what minimum must never change for a verification claim made today to hold in ten years. Stated as a promise a user can rely on:

Any prikk release can read every object any prior supported release wrote, and verifies it to the same conclusion. Storage may require a migration step, which is documented and tested. Object identity and signatures never require one.

This splits every byte in a repository into two categories, and they have opposite rules.

Frozen forever — verification-bearing, never changes once shipped:

• The object-id preimage: OBJECT_ID_DOMAIN (b"PRIKK-OBJECT-ID-v1") ‖ type code (u16 BE) ‖ schema_version (u32 BE) ‖ payload length (u64 BE) ‖ canonical payload, hashed SHA-256.
• The canonical encoding of each (object_type, schema_version) pair that has ever been written by a shipped release.
• The signature preimage, per signer role.
• The algorithm identifiers themselves (Ed25519, SHA-256) — not merely the algorithms.
• The patch-set digest preimage (RFC 115 Stage 1, design-v1.md §5/D4): PATCH_SET_DIGEST_DOMAIN (b"PRIKK-PATCH-SET-DIGEST-v1") ‖ count (u64 BE) ‖ each patch id, sorted ascending and deduplicated, 32 bytes each, hashed SHA-256. Not itself a stored object or an ObjectId — a comparison value, following MerkleRoot’s shape — but identity-bearing all the same: two prikk versions must produce identical bytes over the same patch set, or the “are these two repositories the same?” comparison it exists for means nothing across an upgrade.

May change, and must carry a tested migration path:

• Repository format version and on-disk directory layout.
• Container framing, the object index, the WAL.
• The bundle exchange format.

Freezing is not “never add a field.” A schema version lives inside the object-id preimage, so a new field means a new schema version and new ids for objects written under it — with no change whatsoever to objects already written under an earlier schema version. The obligation is to keep every version ever shipped decodable forever, hashing exactly the way it did on the day it was written — not to stop evolving.

If SHA-256 or Ed25519 is ever broken: a broken algorithm gets a new algorithm identifier, used by new objects going forward. Every object already written continues to verify under the identifier it was written with, unchanged. An existing identifier is never redefined — doing so would retroactively alter what past objects mean, which is exactly what this contract exists to prevent.

The obligation covers shipped releases, not every commit. A schema version or format that only ever existed in an unreleased build is owed nothing under this contract; what shipped is permanent, what merely existed in git history is not.

Formats 1 through 5 are not supported under this contract (owner decision, RFC 114 §5.3) — prikk has never been used in production, so there is nothing to protect there. See Repository Format Transitions below for what that means for each retired format specifically.

Repository Format Transitions

New repositories use format 7 and schema-2 Blocks with replay-derived clean-state Merkle roots. Format 7 is format 6 plus one rule: an object id may hold several container records, and the last one is authoritative — which is how one object carries several signers.

Formats 1 through 5 are rejected at open. Each is refused with an error naming the format found. The earlier bounded legacy read-only mode for format 1 no longer exists — it was retired when format 1 was, and there is no read-only fallback for any superseded format.

Format 6 stays openable, and upgrades in place. A format-6 repository opens and works as before, holding one record per id: a second signer’s copy of a stored object is refused, naming the upgrade. prikk format upgrade moves it to format 7 in place: it takes the writer lock, refuses — changing nothing — unless prikk verify would pass, and then overwrites only the one byte of the FORMAT marker, in place and flushed (RFC 168 §3.3; no rename). Nothing stored is rewritten, because every format-6 repository is already a valid format-7 one. The upgrade is explicit, never automatic, idempotent, and one-way: prikk 0.44.0 and earlier refuse a format-7 repository at open, so upgrade only once every prikk that opens the repository is newer.

The format has moved repeatedly and deliberately: 1→2 (state Merkle roots), 2→3 (object containers), 3→4 (ref containers), 4→5 (trust containers, received-ref index, active ref metadata), 5→6 (compaction slots and generation logs), 6→7 (several records per object id). Prikk is early implementation software and has not committed to format stability. Bumps up to 6 each made every older repository unopenable, with no in-place migration; 6→7 is the first a repository crosses in place.

To carry work across one of the earlier transitions, use prikk bundle export on a version that still opens the old repository and prikk bundle import into a new one. Never edit FORMAT by hand — editing the marker does not change the on-disk shape it describes, and skips the verification prikk format upgrade requires.

Bundle Format Transitions

The bundle exchange artifact (prikk bundle export/import) carries its own magic and version, independent of the repository format above. Bundles are always exported as PBNDL003 (DC-44 increment 3, bundle-manifest-handoff-v1.md), which added a self-describing manifest section after the author-key section — an addition PBNDL002 has no room for and cannot be extended into silently, so the bump is fail-closed on the write side: an older client meeting a newer bundle refuses it outright with its own hardcoded magic check. The manifest names the on-disk repository format and the exporting tool’s own version, and states plainly that a bundle is one ref’s closure only — other refs in the source repository, if any, are not included, and the bundle makes no claim about them. Both prikk bundle export and prikk bundle verify print it.

PBNDL001 and PBNDL002 bundles are still accepted on import (PBNDL001 acceptance corrected shortly after the PBNDL002 bump shipped — bundle-v1-import-regression-v1.md; PBNDL002 acceptance is this bump’s own §3 obligation, verified with real bytes, not a hand-built approximation). This is read compatibility only, the same asymmetry every repository-format transition on this page already has: read what an older client wrote, write only the current format. This is also what keeps the repository-format migration path above actually usable — an old repository can only be opened by an old prikk build, and that build only ever produces a PBNDL001 bundle, so refusing to import one would sever that migration in both directions at once. A PBNDL001 bundle decodes exactly like a PBNDL002 one whose author-key section is empty, which in turn decodes exactly like a PBNDL003 one whose manifest section is absent: the Patches a PBNDL001 bundle carries read Unverifiable, the same outcome DC-53 already defines for any Patch this repository never recorded AUTHOR key material for, and a PBNDL001/PBNDL002 bundle’s own verify report simply states no manifest is present rather than printing absent fields as if they had been checked.

The workspace’s declared minimum Rust version is exactly 1.85.0. The locked product workspace must check, test, and build on that toolchain:

cargo +1.85.0 check --workspace --all-targets --locked
cargo +1.85.0 test --workspace --locked
cargo +1.85.0 build --workspace --locked

MSRV rise policy. The floor above cannot go lower — it is the edition-2024 minimum — but it can rise. It rises only when a dependency or language requirement forces it, never for convenience, and a rise is a minor-version event: the release’s CHANGELOG.md carries a ### Changed — breaking once: entry naming the specific dependency or language feature that forced it, and a line under ### Upgrading. A rise whose cause is not recorded is indistinguishable from a rise for convenience, which this policy forbids.

Current-stable quality gates are separate from minimum-version compatibility. In particular, strict Clippy runs on current stable because its lint set changes between compiler releases.

A patch release must not intentionally break a documented surface. An unavoidable correctness or security break uses a minor release unless a committed emergency exception is accepted by maintainer and architect before tagging. The exception cannot waive identity versioning.

Version Numbers and Release Identity

One version covers the whole workspace: the workspace version and the seven internal crate pins carry it together. In v0 a release with any runtime change is a minor bump (0.41.0 → 0.42.0); a release that changes no runtime source (installer, metadata, docs) is a patch (0.27.1, 0.31.1). Breaking changes happen before 1.0; each is stated in the CHANGELOG as breaking once, with the migration in one line, and is why the crates say “API may change without notice before 1.0”.

A release is its signed, annotated tag. Tags are unprefixed versions such as 0.42.0, not v0.42.0. List them in version order:

git tag --sort=-v:refname

Plain lexical sorting can incorrectly make older 0.9.x tags appear newer than 0.17.x tags. An untagged build is a development build even when prikk --version equals the latest release.

How prikk releases

A release is a theme delivered, not a date reached: the owner authorizes a cut and names its theme, and main is the next release in progress — every commit on it has passed the fourteen local gates and CI. The procedure (RFC 152 §3):

1. Readiness. The dev team checks every --help synopsis and description against the binary, the CHANGELOG against the commits since the last tag, docs messages against the binary, the root-export diff, the package footprint and the memory ratio, and writes a smoke script covering every shipped feature that runs against any prikk binary. Findings are fixed as their own commits. The release commit is exactly three files: the version and its pins, the lockfile’s member versions, and the CHANGELOG heading dated the day it is prepared.

2. Review. The architect reviews the sweep and the commit, runs the fourteen gates on that exact commit, and runs the smoke script against a release build of it.

3. Push, then CI green on every job, including the Windows and macOS suites — the only place platform code runs.

4. Tag. Annotated, GPG-signed with the repository’s configured key, verified with git verify-tag --raw <tag> 2>&1 | grep VALIDSIG, then pushed. From 0.48.0 the tag’s message has as its subject the project name followed by the version (for 0.48.0: prikk 0.48.0), then a blank line, then the line Release notes: https://github.com/prikk-vcs/prikk/releases/tag/X.Y.Z.

   The Release workflow refuses to build unless the commit’s most recent CI run on main completed successfully. The Release workflow builds four targets and publishes the assets. The Release page carries that version’s CHANGELOG section in full, so the notes are read there and not behind a link to a file that is reorganised over time. The signed tag covers the source at the tagged commit, and the section is part of that commit: verify the tag (git verify-tag --raw X.Y.Z 2>&1 | grep VALIDSIG, as in Verifying a release) and read the same section from the tagged tree (git show X.Y.Z:CHANGELOG.md) to compare it with the Release page. The tag does not cover the binaries (see Verifying a release). A tag is never moved or re-signed; a mistake ships as the next patch release. Tags before 0.48.0 keep their bare version message.

5. Verify the artifact. Download the Linux asset, check its sha256 against the published file, read its build-info (commit and tag), run its --version, compare the Release page’s notes with the tagged CHANGELOG section, and run the smoke script against it: what is checked is the bytes users get, not the tree they came from.

6. Publish on the owner’s word, per release. The eight crates in dependency order from a detached worktree at the tag, each confirmed on the registry index; then cargo install prikk --version X and the smoke script once more against what crates.io serves.

7. Tell the consumers. The CHANGELOG is the record. A project building on something a release changed hears about it directly, starting from the section’s ### Output changes.

Each release section leads with what a reader must know, each block only when it has something in it: ### Security (with the advisory id where one is published), ### Upgrading (what to do after upgrading), and ### Output changes (what a program reading the CLI will see differently). Then come the Added, Changed and Fixed entries (RFC 161).

What blocks a cut, without exception: any red gate; any commit on main the architect has not reviewed; CI not green on the release tree; a --help text that is false on the shipped binary.

What protects a release, and what deliberately does not exist

Protects: signed tags on a key one known person holds; checksums and build-info published beside every asset; the release-policy gates on every push in CI, and cargo audit against a fresh advisory database on its own weekly schedule (not per push — a new advisory can arrive with nobody touching the code, so it needs a schedule of its own, in security-audit.yml); the smoke script run against the artifact, not the tree; publication by a person after the artifact is verified; and never unpublishing — a bad version is superseded by a patch release, and yanked only on the owner’s word with a CHANGELOG line saying why.

Does not exist, on purpose, in v0: a second signer; a support window; a stability promise for the object format, the CLI’s JSON schemas or the library API. A checksum on a downloaded binary proves integrity of transport. Whatever you obtain, verify its content with prikk verify.

What changes as the project grows

• A second maintainer with a release key. On the owner’s explicit word, in a commit naming the person and the fingerprint, release-signers.toml gains its first entries; from then on a release tag must be signed by a key in that set, and the release-policy tool gains that one check.
• A first production user. A support window is stated, SECURITY.md’s advisory path is exercised once as a drill, and the memory and cost measurements release prep already takes become numbers a user can rely on.
• 1.0. The stability promise arrives in three named layers, each on its own RFC: the object format and exchange artifacts first (already versioned by schema), the CLI’s JSON schemas second (already -v1 everywhere), the library API last if ever.
• Publication from CI. Possible at any time and deliberately not done while one person’s word is the control that matters most; revisited when a second maintainer exists.

Release-Policy Checks

Run cargo run --locked -p prikk-release-policy -- check from the repository root to execute the release-evidence schema and sequence fixture tables. It asserts date-time formats, rejects unknown schema assertions, fails when computed validity differs from a fixture’s expected outcome, and leaves the worktree unchanged. It is one of the fourteen gates every candidate runs locally (rfcs/EXECUTION-ORDER.md §6 rule 9), and CI’s policy job runs it with the other three release-policy gates on every push.

Every review and release record states the commands actually observed, and what was unavailable or inapplicable. Nothing — cargo audit, registry publication, a GitHub Release, Pages — is reported as passed unless it was observed for that exact release.

Claim-to-Source Anchors

Provenance

The compatibility, format and bundle sections implement RFC 114 and the DC-series format decisions. The release sections describe RFC 152: they replaced, on 2026-09-13, the DC-35 signer-governance, release-state, disputed-tag and evidence-snapshot sections written for a maintainer quorum the project does not have. Nothing here authorizes a signer or claims that any release passed a check it was not observed passing.

Platform Support

This page is the authoritative current-state reference for which platforms Prikk runs on and, concretely, which commands are read-only versus repository mutation. It exists because that boundary had never been enumerated anywhere — DC-71 traced it once, here, so it does not have to be re-derived from source on demand and cannot drift silently again (a CI job builds every listed non-Linux target on every change; see Non-Linux CI conformance below).

The boundary

Repository mutation requires Linux, macOS, or Windows. crates/prikk-store’s anchored filesystem primitives use no-follow, nonblocking, atomic-rename, and no-clobber-install capabilities (durability and crash recovery) with a reviewed implementation on each of those three platforms — LinuxDurability, MacosDurability (DC-81/DC-82; G3 uses fcntl_fullfsync in place of fsync, measured ~180x slower on the GitHub macOS runner), and WindowsDurability (DC-87 Stage 2) — and no reviewed equivalent on any other platform yet (DC-37, superseded for Linux/macOS/Windows by DC-87). Every mutation function’s signature compiles on every platform; only its body has a real implementor on Linux, macOS, and Windows, and a caller on any other platform receives a clean runtime error rather than a build failure or a silent no-op.

What Windows actually guarantees and does not, for path resolution (G1). This is stated here rather than left to be discovered, because it is a real difference and not a coverage gap. Anchored resolution on Linux and macOS opens each path component with openat(dirfd, name, O_NOFOLLOW), so the handle for a component is bound to the object that was checked — the next open is scoped to that handle, not to a re-walked path string. Windows has no equivalent: no Win32 primitive takes a directory handle as a resolution root for opening a child by name, so the walk itself is always a re-walked path string on Windows, by construction.

Windows’ actual implementation (crates/prikk-store/src/foundation/fsutil/anchored/windows.rs) refuses a reparse point at each component as it is opened (FILE_FLAG_OPEN_REPARSE_POINT plus a post-open attribute check), which defeats a symlink or junction that is already in place. It does not close the window between checking a component and opening the next one. So a concurrent local process that substitutes a reparse point mid-walk, timed into that window, is not provably defeated on Windows, while it is on Linux and macOS. A passive, already-planted reparse point is caught on every platform. This mid-walk window is unchanged by anything below — DC-96 verifies the anchor a walk starts from, not each intermediate component of the walk itself.

Prikk does not claim otherwise. This gap was accepted, once, on the condition that it be stated rather than elided (prerequisite-ruling-v1.md §4.1) — this section is that statement.

Anchor replacement (DC-96 Windows Anchor Identity). DC-87 Stage 2’s own CI job demonstrated a second, wider gap: renaming a repository’s root (or .prikk specifically) aside and creating a fresh directory at that path redirected both reads and writes — including objects, refs, and the WAL, not only the worktree — into the impostor, silently, with prikk reporting success. This was not the G1 mid-walk race above; it needed no reparse point at all, and the disclosure as it stood would have led a reader to conclude it was already defended. It was not.

Fixed, as prevention, not merely detection. An earlier version of this fix stored only a path string plus an identity value and refused on mismatch — detection, and wrong: it could satisfy only half of each acceptance test, since the tests require operations to keep working correctly against the retained directory after a replacement, not merely refuse (.git-exclude/reviewed/DC-96-implementation-ruling-v1.md §2-§4). WindowsAuthority (crates/prikk-store/src/fsutil/anchored/windows_authority.rs) instead retains the directory handle it was bound to. Windows has no openat-equivalent to resolve a child by name against that handle, but a retained handle still follows its object across a rename — GetFinalPathNameByHandle returns its current path. Every walk re-derives that current path from the retained handle first, confirms via identity (GetFileInformationByHandle’s (volume serial number, file index) pair) that the object found there is still the one that was bound, and only then walks forward from it. Both Win32 calls go through prikk-ffi — crates/prikk-ffi, the one workspace crate permitted unsafe per DC-90. Three residual properties, stated precisely rather than left to be inferred:

• Anchor replacement between operations: prevented while a repository is open, in two different ways. For .prikk (repository_mutation), the retained handle follows a rename that does succeed — the gap the CI job demonstrated, now closed by continuing correctly against the retained directory rather than merely refusing. For the worktree root (worktree_mutation), the outcome is stronger still: NTFS refuses the rename outright, because RepositoryLayout retains a nested handle on .prikk inside it — see the next paragraph for what this means operationally.
• Anchor replacement racing a single operation — swapped between the post-open identity check and the open that immediately follows it — is still possible. The window is narrowed from “any time before the next operation” to one check-then-open pair; it is not closed, because Windows still offers no openat-equivalent to close it by construction the way Linux and macOS do. DC-99 Stage 2 found the confirmation step guarding this window unexercised by any test: a negative control neutralized WindowsAuthority::verified_anchor_path’s identity comparison and the full suite stayed green, 936/936, identical to the unmodified branch — neither DC-96 acceptance test constructs the narrow race this comparison exists for. RFC 106 built the failpoint barrier this needed (TestBarrier::AnchorVerification, mirroring DC-98’s wait_at_directory_create) and constructed the race directly: a test holds the window open, installs a replacement at the anchor’s own path, and confirms the operation is refused with the specific “Windows anchor replaced” diagnostic — passing on real Windows CI (run 32002318009). Repeating DC-99’s negative control against this new test reproduced the same failure shape deliberately: with the comparison neutralized, that one test failed and was the only failure in the suite (run 32002319494). The comparison now has a control that depends on it.
• Intermediate path components are unchanged — this is exactly the G1 mid-walk window above, and DC-96 does not touch it.

A fourth property, user-facing rather than adversarial: while a prikk command holds a repository open on Windows, that repository’s directory — and any directory containing it — cannot be renamed or moved by any process, prikk included. NTFS refuses to rename a directory that contains an open handle anywhere within it, unconditionally, and prikk retains one on .prikk for the duration of a command (RepositoryLayout::init/open, crates/prikk-store/src/fsutil/anchored/ windows_authority.rs). This is not a bug report waiting to happen; it is the mechanism above, observed from the other side. It is bounded to a single command’s execution — prikk has no daemon — so the window is as long as one invocation takes, not a whole working session.

The 64-bit file index is not reliable on every filesystem — identity is the secondary check, not the sole mechanism, which is why this does not weaken the fix. Per Microsoft’s own documentation for BY_HANDLE_FILE_INFORMATION (nFileIndexHigh/nFileIndexLow): “The ReFS file system… includes 128-bit file identifiers… The 64-bit identifier [nFileIndexHigh/nFileIndexLow] is not guaranteed to be unique on ReFS” — ReFS callers needing a reliable id are directed to GetFileInformationByHandleEx with FileIdInfo instead. Windows 11’s Dev Drive, Microsoft’s own recommended location for source repositories, is ReFS. This matters less than it would have under the detection-only design: the primary mechanism here is the retained handle following the renamed object via GetFinalPathNameByHandle, which does not depend on the file index at all; identity is only the confirmation that what was found at the re-derived path is the same object, not what determines where the walk goes. A coincidental file-index collision on ReFS would need to land on the object the walk already, independently, arrived at correctly — not redirect it. FILE_ID_INFO is not used here; if a future increment needs a stronger per-filesystem guarantee, that is its own design question.

The DurabilityContract methods on Windows

The trait has eleven methods (crates/prikk-store/src/foundation/fsutil/contract.rs:89-172); each has a row below.

Windows residuals of RFC 168 (accepted by the owner), each by name.

• (a) Worktree files after a completed switch or checkout. On Windows, a power loss shortly after a completed branch switch or checkout can bring back old contents of rewritten files, bring back deleted files, or lose created files. Nothing in the repository is damaged. Worktree files keep their atomic replace (RFC 168 §3.4): writing a user’s file in place would change what hard links and running programs see.
• (b) A repair’s first save in a repository created before 0.49.0. The recovery log is a new name there. On Windows, a power loss in the same boot as its creation can keep the repair’s truncate and lose the log’s first appearance, so the bytes that repair removed are not kept. Repositories created by 0.49.0 create the log at init, and a later save appends to an existing name, which is durable.
• (c) The commit witness’s first creation in a repository created before 0.49.0. A lost creation falls back to RFC 166 rule 3, the classification a session written by an older binary has always had.

promote and publish_immutable retired (DC-98 Stage 1). Both rows above are gone, not merely weakened. promote (no named guarantee of its own, orphaned by RFC 102 Stage 4’s ref-pointer rewire) and publish_immutable (G5, race-safe no-clobber publication) both had zero production callers left; the ruling that had kept publish_immutable (design-v1.md §12.3) named its own discharge condition — Stages 4-5 shipping and showing no loose-file use remained — which DC-98’s RFC confirmed. DurabilityContract has eleven methods today, all covered by the table above.

The init-time exemption. create_exclusive and ensure_directory create names, and Windows cannot make a new directory entry durable. Both are reachable only during init. This is tolerated because an interrupted init has nothing to lose — no user history exists yet, and FORMAT is written last — so an incomplete init is detectable and a re-run completes it idempotently. That argument depends on ordering, not on a durability primitive, so it holds on Windows unchanged.

DC-76’s negative controls, per guarantee, on Windows (DC-97; G5 retired in DC-98). Stage 2 shipped with none of DC-76’s original nine demonstrated there; DC-97 classified each individually rather than leaving one blanket statement, since the honest answer differs guarantee by guarantee. G5 (race-safe no-clobber publication) is no longer one of the guarantees to classify at all — retired in DC-98 along with publish_immutable, its only method, once both had zero production callers left. Eight guarantees remain:

Reported rather than silently left implicit, per DC-76’s own precedent (two of its original nine also could not be cleanly demonstrated on the platforms it shipped on, and were reported rather than dropped).

The same gap exists on the read path today, in the shipped read-only configuration. All four non-Unix fallback read functions resolve a whole path in one operating-system call, so reparse points at intermediate components are followed — there is no component-by-component walk on that path at all. One of them, read_file_if_exists, additionally does not refuse a symlink at the final component, unlike its three siblings in the same module, which use a no-follow stat. That last one is an asymmetry inside one file rather than a platform limitation, and it is stated here rather than left implicit because the guarantee is otherwise described per-function.

prikk unlock’s PID liveness check now has a real primitive on all three platforms (DC-99 Stage 1) — the same shape as set_permission_bits/durable_directory_entry above, outside the DurabilityContract table because it lives in a different module (crates/prikk-store/src/unlock.rs). Linux/macOS use kill(pid, 0) via rustix::process::test_kill_process; Windows uses OpenProcess/WaitForSingleObject (prikk_ffi::process_liveness) — OpenProcess failing with ERROR_INVALID_PARAMETER and a successfully-opened handle’s WaitForSingleObject reporting it signaled both mean the process is gone; ERROR_ACCESS_DENIED on open means it exists but this caller cannot query it further, the same reasoning Linux/macOS’s EPERM branch already applies. Both platforms trust a positive result (AppearsRunning) and never a negative or unknown one — PidLiveness’s own advisory contract is unchanged; a real primitive makes the refusal better informed, it does not make clearing safe. One platform-specific guard: PID 0 names the Windows System Idle Process, a real but never lock-file-legitimate PID, and is rejected before the OS call so a malformed pid=0 lock body produces Unknown on Windows the same way rustix::process::Pid::from_raw(0) already makes it produce Unknown on Linux/macOS.

Read-only commands build and run everywhere. They never reach a mutation primitive — verified by tracing every command’s call graph to crates/prikk-store/src/fsutil’s mutation set (ensure_root, write_file_atomically, write_worktree_file_atomically, append_file_required, truncate_existing_file_required, truncate_file_empty_required, create_new_file_required, remove_file_required/remove_file_if_present_required/remove_worktree_file_required, promote_file_required, publish_immutable_file, ensure_directory_required, sync_directory_required), not merely by a command’s name suggesting it.

The command set

This table is derived from each command’s help text and module documentation. It is not traced through the call graph, and it is not an authoritative list until a test checks it.

The rows that were already here were traced 2026-08-04 (DC-71) by following each command’s implementation to whichever of the mutation functions above it does or does not reach, including transitively — rollback-draft, for instance, calls no mutation primitive directly in its own file, but reaches one through Wal::append_patch. The rows added 2026-10-07 (the doctor repair rows, key, setup, diff, cat, tree, show, merge, mv, config, bundle, branch switch, trust maintainer, sync, unlock, ref complete, format upgrade, compact) are classified from each command’s help text in crates/prikk-cli/src/commands.rs and its module doc, and were not traced through call graphs. A name suggesting “plan” or “preview” is a hint, not proof.

Non-Linux CI conformance

.github/workflows/ci.yml’s non-linux-build and non-linux-verify jobs run on GitHub’s native windows-latest and macos-latest runners on every push and pull request, so a regression in this boundary — the exact defect DC-71 fixed, which shipped undetected because nothing built a non-Linux target — fails CI immediately rather than being found by a user or the next trial build. non-linux-verify additionally runs the full read-only command set, including worktree-status (RFC 122), against a fixture repository authored on Linux, so this is a demonstrated property, not merely a successful compile.

The macOS mutation test suite and Windows mutation test suite CI jobs (DC-81, DC-87 Stage 2) run the suite that compiles there natively on macos-latest and windows-latest — not every test in the workspace: a few are gated more narrowly than the platform, each for a named reason, so each platform’s own count is smaller than stable’s. The gates that remain, by name:

• Linux only, by necessity: invalid-UTF-8 names. A directory or file name containing a byte that is not valid UTF-8 cannot be created on macOS (APFS rejects it, EILSEQ), and Windows names are UTF-16, so the byte sequence cannot be constructed there. Tests: wal/tests.rs (wal_for_layout_produces_byte_exact_paths_for_a_non_utf8_session_name), lock/tests.rs (active_lock_acquires_a_byte_exact_path_for_a_non_utf8_session_name), and commit_boundary/worktree_patch/tests.rs (non_utf8_worktree_path_fails_closed), and unlock/tests.rs at line 284 (list_held_locks_reports_a_lock_under_a_non_utf8_session_name).
• Corrected (0.50.0 step 2 Part C): the fsutil/tests/conformance.rs suite is not Linux-only. DC-81 (macOS) and DC-97 (Windows) already ported it: of the four conformance assertions, three (create_exclusive_refuses_an_ already_occupied_path, durable_directory_entry_accepts_the_named_files_own_path, and the pre-existing guarantees G1/G2/G5/G8) run on all three platforms, and the macOS/Windows mutation CI jobs already run the full workspace suite (cargo test --workspace --locked --no-fail-fast), not a narrowed one — this has been true since those two rounds landed; the entry above was stale. G9 is the one genuine exception (set_permission_bits_masks_file_type_bits_out_of_a_recorded_mode, Linux and macOS only): it reads back POSIX mode bits (PermissionsExt::mode), which do not exist on Windows, so it cannot be reused unchanged there — Windows’ own no-op shape is covered separately (windows::tests::set_permission_bits_is_a_documented_noop), documented in conformance.rs’s own coverage-map comment. G6/G7 (append_and_truncate_reject_fifo_without_ blocking, read_rejects_fifo_content_despite_the_os_permitting_the_open) are Linux-and-macOS by necessity too (FIFOs are POSIX-specified, DC-81), already covered by the directory-sync bullet’s own reasoning below.
• Not windows (macOS and Linux), by necessity: a directory-sync injection point. A directory fsync is a failpoint only where a directory can be synced (Linux, macOS), and Windows has no such operation. The tests that inject one are gated not(windows) (or, for the caller_tests module as a whole, the equivalent any(target_os = "linux", target_os = "macos")) and run on macOS: among them the lock, active-metadata and patch-checkout retry tests. An append never creates a name, so it syncs only the file (RFC 102 §3) — the WAL, trust and refs tests that used to inject this point on an append no longer have one there; each was retargeted to its own surviving RequiredFileSync injection point on the same call path instead, or confirmed one already existed.
• Unix (macOS and Linux), by necessity: symlink creation. a_symlinked_witness_path_refuses_the_same_way_every_other_session_file_does creates a symlink, which macOS allows and Windows allows only with a privilege.
• Resolved (0.50.0 step 2 Part C): the snapshot test that removes a file between stat and read (snapshot/tests.rs’s a_file_removed_mid_entry_is_refused_not_reported_unchanged, using worktree:: before_stat_for_test). Named from source: both the seam and the test are a plain thread-local closure and std::fs::remove_file — nothing unix-only, unlike the seam above it in the same file (between_plan_and_write_for_test, genuinely gated to match patch_checkout’s own Linux-only tests, DC-71), which this one had apparently been gated to match by copying rather than its own reason. Widened to run on all three platforms; no longer a gap.
• Linux only, as written: individual tests gated cfg(target_os = "linux") inside suites that run elsewhere. crates/prikk-cli/tests/verify_and_doctor/rfc158_incoming_bound.rs gates six control1_* tests (lines 96-227: bundle import, preview and verify; sync compare, build and accept; each on a sparse 1 GiB file). In crates/prikk-cli/tests/rfc147_declaration_resolution.rs the items at lines 514, 721, 746 and 762 are gated: a_rename_reports_a_mode_change at 514, and the socket and FIFO fixture helpers at 721 and 746 (line 762 was not checked by name). Neither file records the reason for the gate at the gate itself.
• Linux only, and #[ignore]d: measurement units, run by hand. crates/prikk-cli/tests/append_length_io.rs (file-level #![cfg(target_os = "linux")], line 22; its three #[ignore] units are measurements) and the G2 table in crates/prikk-cli/tests/hostile_lengths.rs (hostile_lengths_g2_table, lines 371-383, #[ignore]). They run only with --ignored, so they are not part of the platform gates above.

Neither developer nor architect can run either platform locally as part of this project’s own environment, so the CI job existing and being green is the verification for each backend, not a supplement to one done elsewhere.

windows-mutate → linux-mutate-reference → verify-cross-platform-history (DC-87 Stage 2 criterion 7) close the one property none of the jobs above can: that repository authored on Linux, mutated on Windows, and verified on Linux produces identical object ids and a clean verify. The Linux-built fixture is mutated identically on both platforms with the same deterministic signing seeds fixture already uses; the Windows-mutated repository is then handed to a Linux job, which runs prikk verify against it directly and diffs its recorded object ids against the independently-computed Linux reference. Every other job in this workflow is one platform verifying itself — this is the only one where a different platform checks Windows’ output.

What is not covered here

• Other platforms have no prebuilt binary. Prebuilt archives cover four targets: Linux x86_64 and aarch64, macOS aarch64 (aarch64-apple-darwin), and Windows x86_64 (x86_64-pc-windows-msvc) (.github/workflows/release.yml:35-46). Anywhere else, build from source (cargo build/cargo install); see install.
• DC-76’s negative controls are only partly demonstrated on Windows, for the eight guarantees that remain (G5 retired in DC-98) — see “The DurabilityContract methods on Windows” above for the per-guarantee table and reasons. G1, G2, G3, G4, G8, and G9 are demonstrated; only G6 and G7 are not, and both for the same reason — no Windows analogue exists to demonstrate at all (Windows named pipes live in a separate \\.\pipe\ namespace, not reachable the way a FIFO is on Linux/macOS), unrelated to the failpoint injection mechanism DC-98 wired for the other six.
• macos-latest is Apple Silicon (aarch64-apple-darwin), not x86_64 — GitHub’s default since the macOS 14 runner image. windows-latest is x86_64. Neither the x86_64 macOS nor the arm64 Windows variant is separately CI-gated, and Windows arm64 is untested entirely; nothing in the Windows backend is architecture-specific (it is #[cfg(target_os = ...)], not target-triple-specific), so this is a coverage gap in CI breadth, not a known or suspected difference in behavior.
• File mode / executable-bit authoring on Windows, or any platform with no observable POSIX mode (DC-87 §3.3/§4.3): worktree authoring never derives a node’s recorded mode from such a platform’s filesystem — an existing node’s already-recorded mode is always carried forward untouched, and a brand-new file is created non-executable by default, since there is no existing recorded mode to inherit and no observed signal to use. set_permission_bits is correspondingly a documented no-op on Windows (see the guarantee table above) — this is a missing capability (an executable file’s initial creation cannot be authored from such a worktree), not data loss — a previously-recorded executable bit is never silently dropped from sealed history by this platform difference.
• Re-checking out a file whose bytes already match, on such a platform: the file is recognized as unchanged by its bytes alone, since there is no observable mode to compare them against, and checkout --snapshot-materialize / --patch-materialize count it under unchanged files: exactly as they do on Linux. Until 0.43.0 every such file was counted under written files: instead, and the no-op set_permission_bits was called again for it — a wrong count and pointless work, never a wrong byte on disk (DC-87). A file that disappears between its bytes being read and its mode being read is a different case and still refuses the checkout, on every platform.

System Architecture

An overview of how Prikk is put together: which crate owns what, which way dependencies point, and where the boundaries that matter are enforced.

For the objects themselves and how they change over time, see Data Model Relationships and Lifecycle.

Crate graph

Seven published crates. Dependencies point strictly downward — there are no cycles, and each crate depends only on layers beneath it.

graph TD
    CLI["<b>prikk</b><br/>CLI surface"]
    STORE["<b>prikk-store</b><br/>repository, WAL, refs, verify, merge"]
    REPLAY["<b>prikk-replay</b><br/>node lifecycle state"]
    OBJECT["<b>prikk-object</b><br/>canonical encoding, object identity"]
    CRYPTO["<b>prikk-crypto</b><br/>Ed25519"]
    HASH["<b>prikk-hash</b><br/>SHA-256"]
    ERROR["<b>prikk-error</b><br/>error taxonomy"]

    CLI --> STORE
    CLI --> OBJECT
    CLI --> HASH
    CLI --> ERROR
    STORE --> REPLAY
    STORE --> CRYPTO
    STORE --> OBJECT
    STORE --> HASH
    STORE --> ERROR
    REPLAY --> OBJECT
    REPLAY --> HASH
    REPLAY --> ERROR
    CRYPTO --> ERROR
    OBJECT --> HASH
    OBJECT --> ERROR

Dependency boundary, enforced not documented

prikk-store may depend on exactly getrandom and rustix; prikk-crypto on ed25519-dalek and getrandom; prikk-hash on sha2. Every other product crate has no third-party dependencies at all.

This is not a convention. It is checked by prikk-release-policy boundary-check, which resolves the real package graph from the root manifest and fails the build on any addition. Adding a dependency to a product crate is therefore a reviewed decision, not an implementation detail.

The mutation pipeline

Every change to sealed history follows the same path. Each stage is separately durable, and the repository is consistent if the process stops between any two of them.

flowchart LR
    WT["Worktree<br/><i>ordinary files</i>"]
    WAL["Active WAL<br/><i>uncommitted patches</i>"]
    OBJ["Object store<br/><i>content-addressed</i>"]
    REF["Ref<br/><i>published tip</i>"]

    WT -- "commit<br/>author signs" --> WAL
    WAL -- "seal<br/>maintainer signs" --> OBJ
    OBJ -- "publish<br/>compare-and-swap" --> REF

• commit turns worktree differences into a signed patch in the active WAL. The author signs.
• seal persists the WAL’s patches as objects and builds a block over them. The maintainer signs the block. Multiple commits may be queued and sealed together.
• publish advances the ref by compare-and-swap against its expected previous state, so a concurrent writer cannot be silently overwritten.

The two signatures are separate roles by construction: an author cannot seal, and a maintainer sealing another author’s work never re-signs that author’s patches.

Repository layout

Under .prikk/:

The last row is a requirement, not an observation: NFR-PERF-04 states that caches are rebuildable and never roots of trust. BlockSummaryCache uses the canonical codec for reproducibility but is explicitly excluded from block identity.

Where the platform boundary sits

Read-only commands run on Linux, macOS, and Windows, verified continuously in CI. Mutation runs on all three as of 0.21.0 — each platform’s durability implementor lives behind one gated dispatch point (ACTIVE_DURABILITY, DC-82), so adding Windows was one more arm there rather than a rewrite of the mutation layer, which is what the seam was drawn for.

Windows is not a straight equivalent, and the differences are named rather than implied: it has no openat, so anchored resolution is a validated path walk with the anchor’s identity confirmed against a retained handle, and four residual properties are stated in platform support. The mutation suite runs on all three platforms in CI, and a repository authored on Linux, mutated on Windows, and verified on Linux is required to produce byte-identical object ids.

That is deliberate. DC-37 requires anchored opens that refuse symlink traversal, atomic replacement, and explicit file and directory durability; those guarantees were implemented against Linux primitives first (LinuxDurability), macOS second (MacosDurability, DC-81), and Windows third (WindowsDurability, DC-87 Stage 2) — with no reviewed equivalent on any other platform. See Platform Support for the per-platform residual gaps, including Windows’ weaker anchoring guarantee in one stated way.

Where the unsafe-code boundary sits

Every crate in the workspace carries #![forbid(unsafe_code)], applied uniformly through the root Cargo.toml’s [workspace.lints.rust] table (unsafe_code = "forbid") and each member’s own [lints] / workspace = true. The owner’s ruling (DC-90) permits at most one workspace crate to be named as an exception — never inferred from what a crate happens to do — and no crate is named today: prikk writes no unsafe code of its own yet, even though it already runs some (rustix’s own internal FFI on Linux and macOS, which forbid(unsafe_code) governs code prikk writes, not code it depends on).

The boundary is a gate, not a convention. release-policy boundary-check (tools/release-policy/src/boundary/unsafe_boundary.rs) fails the build if a second crate is ever named exempt, if any non-exempt crate drops workspace lint inheritance, or — the rule that makes an eventual exemption self-guarding — if the one exempt crate opts out of inheritance without locally re-declaring clippy::undocumented_unsafe_blocks = "deny" in its own manifest. That lint is enabled once, at the workspace root, specifically because the crate permitted to write unsafe is also the one crate that could otherwise switch its own SAFETY-comment requirement off by deleting a line.

What the gate cannot see, and the review obligation that covers it instead, is documented in full in unsafe_boundary.rs’s own module doc — read that before relying on a green boundary-check as proof of anything it doesn’t test. In short: FFI-ABI correctness (whether a foreign function declaration actually matches the real platform ABI) and SAFETY: comment content are both human review judgments, not machine-checkable properties, and comment staleness — a comment that no longer justifies the code beneath it after an edit — degrades silently behind a gate that stays green either way.

Verification is the trust boundary

prikk verify re-derives rather than trusts: object ids are recomputed from canonical bytes, block state roots are re-derived from lineage, and a merge block’s recorded baseline is re-checked as a genuine common ancestor of both parents.

Two limits are worth stating plainly, because they define what verification means here:

• Verification confirms structural and cryptographic validity. It does not re-derive that a change was semantically the right change — that rests on the maintainer’s signature, uniformly, for merges exactly as for ordinary commits.
• verify enforces repository-wide author verification (DC-53): every reachable Patch’s AUTHOR signature is cryptographically checked against recorded key material. This remains trust-on-first-use continuity, not first-contact authenticity — there is no independent repository-wide AUTHOR trust policy (allowlist or revocation) the way MAINTAINER keys have one; see trust and threat model.

Known architectural costs

These are recorded rather than left implicit. The findings register they once pointed at was retired deliberately — reviews carry findings while they are live, and documentation and RFCs carry what outlives them — so this table, ROADMAP.md’s open-work index, and the RFCs themselves are where they live now.

What the block design trades, and what it does not

Patch-theoretic systems have a known failure mode: Darcs’s exponential merge, which arises because its patches are context-dependent. Reordering two of them requires commuting one into an equivalent that applies in the other’s context, and resolving conflicts means searching those orderings.

Prikk cannot have that failure mode, by construction. Its operations are context-free — every operation names a stable NodeId, and EditText identifies its span by content anchors with presentation_hint_line explicitly excluded from algebraic identity. A patch transports between lineages without transformation, which is also why a merge can adopt patches byte-identically with their author signatures intact. There is no commutation search to explode.

The second half is deliberate refusal rather than cleverness: the patch algebra proves confluence only for a conservative subset it can prove, and returns a typed conflict witness for everything else. Cost is bounded by refusing hard cases, not by exploring them. Sealing history into immutable blocks then keeps that reasoning confined to the active working set, which is itself capped (NFR-PERF-02).

The trade was real, it was measured, and it has been paid. That history is worth stating plainly:

The mechanism that bounds patch cost also created prikk’s own cost. History is sealed into a chain carrying state roots, and verify must re-derive those roots to check them. The first implementation re-derived each block’s state from genesis, so verifying the block at position i cost O(i²) and the whole chain O(N³) — about 34 seconds at 160 blocks.

Prikk did not inherit Darcs’s problem. It had a different one, and it lived in the verification path rather than the merge path — which mattered more, not less, because verification is this project’s central claim in a way that merge throughput is not. It was found by measurement rather than by reading the design, and it is now fixed.

verify derives each block’s state once, forward from its already-verified parent, memoizing as it goes — never from genesis per block — and checks the result against that block’s recorded state root. Combined with removing a repeated full-index decode on the same path, the cost is linear: 27.04 ms at 160 blocks, per-doubling ratio 1.97, against 167.85 ms and ×3.51 at the intermediate stage.

The property is held by a gate rather than by a measurement: rfc111_index_decode_cost_gate.rs fails if verify’s full-index-decode count ever grows with repository size again, and it was observed failing before its fix. So the block-oriented design’s central trade held — the cost it created was real, was found, and is now bounded and defended.

Repository Layout and Authority

This page is the authoritative current-state reference for Prikk’s on-disk repository layout and storage authority boundaries. It describes the current implementation and is grounded in the code, released RFCs, and implementation status records listed in the anchor table at the foot of the page.

For logical object concepts, see the data model. For repository path and worktree write-safety rules, see path and worktree safety. For local persistence and recovery behavior, see durability and crash recovery. For trust and signature scope, see the trust and threat model. For lock and ref compare-and-swap behavior, see concurrency and locking. For format stability, migration limits, and release identity, see release, versioning, and compatibility.

Core Caveats

• Prikk is early implementation software and is not a production Git replacement.
• .prikk/ is Prikk’s native repository format and is not Git-compatible storage.
• .prikk/FORMAT is a current format-version gate, not a stable-format or migration guarantee.
• Ref files are mutable pointers for convenience and recovery, not roots of trust.
• Cache-like directories are initialized today, but are not current roots of trust; the quarantine directory is retired and no longer initialized.
• Durability and recovery claims are supported by current unit and integration tests, not by a completed crash-matrix or fuzzing campaign.
• Repository mutation is exercised by project gates on Linux, macOS, and Windows (DC-87 Stage 2). Windows’ anchoring guarantee is weaker than Linux/macOS in one stated way — see platform support for the exact gap and which of the eight live durability guarantees (G1–G4 and G6–G9 in crates/prikk-store/src/foundation/fsutil/contract.rs; G5 was retired in DC-98) are held, weaker, or documented no-ops there. Read-only commands are CI-gated on macOS and Windows too — see platform support.
• Stable repository-format migration, garbage collection, quarantine enforcement, cache rebuilding, hosted forge trust, and remote-tracking remain deferred. prikk sync (RFC 116, RFC 117) and prikk merge (DC-74) have since shipped — see the sync and merge guides.

Initialized Layout

A fresh prikk init creates the repository directory, the initialized directories below, the format marker file, and the leaf files the default session and the write state need before their first write: worktree.marker, worktree.provisional, current-branch (heads/main), active/default/queue.wal, active/default/ref-name, active/default/declarations, active/default/witness, and recovery/log (crates/prikk-store/src/foundation/layout.rs:280-305, and ensure_write_state at layout.rs:740-751). The active WAL and active ref metadata are therefore empty when init returns. Ref, received-ref, and trust storage are fixed, named container files allocated by init itself, empty until first use — there is no per-ref, per-received-ref, or per-key-id file or directory created later, since none of those names exist at init time and a per-name file would have to be.

.prikk/
  FORMAT
  current-branch
  worktree.marker
  worktree.provisional
  recovery/
    log
  containers/
    patch/{a,b}.container
    block/{a,b}.container
    ref-state/{a,b}.container
    tag/{a,b}.container
    attestation/{a,b}.container
    blob/{a,b}.container
    index.container
    generations.log
  active/
    default/
      queue.wal
      ref-name
      declarations
      witness
  refs/
    containers/
      log-{a,b}.container
      pointer-index-{a,b}.container
      pointer-index-generation.log
      received-index-{a,b}.container
      received-index-generation.log
    locks/
  trust/
    keys.container
    policy-{a,b}.container
    policy-generation.log
  cache/

Every file above is created by init. Each is empty until first use, except FORMAT (its version) and current-branch (heads/main). No name under .prikk/ is created after init — that is a design invariant, not an implementation detail, and it is what makes the repository durable on filesystems that cannot make a new directory entry durable. The exceptions are the write-state files a repository created before they existed lacks: recovery/log and the default witness, which the first write creates exclusively (layout.rs:740-751), and the declarations file, which a write also self-heals (layout.rs, the RFC 144 §4o.2 comment in init). recovery/ is never authority (next paragraph); init creates its log, and a repository created before 0.49.0 gets the log and the witness at its first write.

recovery/log holds the bytes a repair removed, appended and flushed before the repair truncates. Each repair is one run, and each file it changes is one entry in that run. Every repair writes here and nowhere else. Each entry records its source file, the offset it was cut at, the removed bytes, a hash of the file before that offset, and the identity of the files that give those bytes their meaning. A repair names its run, for example recovery/log, run 3f9a0c1e8b2d4a57. A rewrite in place (the commit witness, ref-name) keeps the file’s previous bytes too, so a run can be undone exactly. It exists so that a repair can be wrong about what it removed (a torn tail and a lone damaged record look the same) without anything being lost. It is never authority: no classification reads it, and verify reports damage in it on its own line without changing its exit status. The log is never truncated except by prikk doctor --recovery-clear, which removes the saved content for good. It is not quarantine/, which is retired.

The three commands:

• prikk doctor --recovery-list prints the saved entries grouped by the repair run that wrote them: a line per run with its id and entry count, then each entry’s source and its label. A Cut entry (trailing bytes a repair removed) prints the offset it was cut at and its length; a Replace entry (the whole file’s own previous bytes, before a repair rewrote it in place — --keep-slot’s own saves, and the commit witness/ref-name rewrite) prints “replaced, N bytes saved” instead (0.51.0 step 1 Part C2, C4: “cut at 0” read as a truncation even when nothing was removed). It does not judge whether an entry can be restored.
• prikk doctor --recovery-restore <run id> [--plan-only] undoes the whole run, in reverse order: it prints its plan first (each step, and its conditions), then writes only when every condition holds. A step that already holds its result is skipped, so an interrupted restore finishes when it is run again. A later run that changed the same files is named, and the restore waits for it. It writes only when the source is exactly as long as the recorded offset, its bytes before that offset hash to the recorded hash, and the files that give the bytes their meaning are unchanged.
• prikk doctor --recovery-clear [--plan-only] lists what it will remove, then empties the log.

Repairs written before 0.49.0 are in recovery/ as *.bytes files. They are listed as older files, read or deleted by hand, and never restored.

init also creates refs/tmp/, which is allocated but never written to. It is a remnant of a retired candidate-publication mechanism, not authority for anything, but its absence is an error: verify scans it on every run, so repository open validates it is present.

Ten further directories that were previously allocated at init for the same reason — objects/ and its six object-type subdirectories, quarantine/, refs/by-id/, refs/logs/ — are no longer created. Nothing has ever written into any of them (object and ref storage moved into containers years earlier), and nothing validates their presence at open, so a repository initialized before this change keeps them harmlessly and a newly initialized one simply lacks them. One dormant diagnostic still reads the objects/ tree if present — see Object Store below.

New repositories contain 7 in FORMAT; a repository created by 0.44.0 or earlier contains 6, still opens, and moves to 7 in place with prikk format upgrade (see Release Compatibility). Formats 1 through 5 are rejected at open, with an error naming the format found and directing migration through prikk bundle export on a version that still supports it; so is any number this build does not know. The format marker is a gate: a repository whose on-disk shape does not match what the code expects is refused rather than opened and left to fail later.

cache/ holds rebuildable, non-authoritative state — a corrupt or absent cache file is never an error, and any operation’s result is identical whether the cache is warm, cold, or missing.

There is no initialized gc/ directory, and prikk performs no garbage collection: no object is ever deleted or superseded once written.

Object Store

Objects are not stored one-file-per-object. Every persistent object envelope is a checksum-framed record appended into a shared, per-type container allocated at init:

containers/<object-type>/a.container

with a paired b.container allocated at init and permanently unused — object containers have no data model to compact against (see Compaction below) — and one containers/index.container mapping each object id to the container, slot, offset and length where its record lives.

Six object types are persisted this way — patch, block, ref-state, tag, attestation, blob. RefUpdate is stored inline in ref logs, not as an object record.

Why containers rather than files. An object’s identity is its content hash, so every one-file-per-object write created a new directory entry. Making a new name durable requires an fsync on the parent directory, which POSIX provides and Windows does not — there is no documented or undocumented Windows primitive that makes a new directory entry durable. Appending to a file that already has a name needs only content durability, which every supported platform provides. Moving objects into fixed, init-allocated containers is what makes prikk’s durability guarantee statable as a property rather than as a list of platforms that happen to pass.

Reading is isolate-and-continue. A damaged record is named at its byte offset and the scan continues to the next intact one, so corruption is confined to the records it actually damaged rather than failing the whole container. A record is authority only when its frame checksum verifies, its envelope decodes and validates, it has the expected type, and its computed content-addressed id matches the requested id.

The index is rebuildable and off the durability path. An object record is appended and made durable before its index entry is appended, so a crash between the two leaves an object present but unindexed — recoverable by rebuilding the index from a container scan. The reverse ordering would let a reader see a valid index entry pointing at bytes that are not there, so the ordering is load-bearing.

Nothing deletes an object, and nothing is rewritten. Writing an id that already exists with identical bytes is a no-op. In format 7 an id may hold several records, and the last one is authoritative: another signer’s copy of a stored object — the same type, schema and payload under other signatures — is written as one superseding record carrying the union of both signature sets, and the index’s last entry for the id points at it. Every reader resolves an id to that last record, in every pass. The union is decided under the object-store lock against the record as stored at that moment, so two writers merging into one id keep both signature sets. A copy whose payload differs under the same id is corruption and is refused in every format; in format 6, any different copy is refused. Containers therefore only ever grow.

objects/ and its six type subdirectories are a retired one-file-per-object layout, replaced by the containers above; nothing in a format-3 repository writes into it, and init no longer creates it. A repository initialized before this change may still have it on disk — its presence or absence is not validated at open — and if so, one dormant diagnostic (scan_loose_file_temp_debris, kept for .pobj.tmp. debris a format-3 repository can no longer produce) still reads it during verify.

Refs and Ref Logs

Ref pointer and ref-log storage is shared, not per-ref: every ref’s own pointer entry and log records live in containers allocated once at init, not in a file named for that ref. A ref name does not exist until branch create/tag create mints it, well after init — a per-ref file could never be one of init’s own fixed names, so pointers and logs for every ref instead interleave inside:

refs/containers/pointer-index-{a,b}.container
refs/containers/log-a.container
refs/containers/log-b.container
refs/locks/<ref-name-storage-key>.lock

Locks remain per-ref files, one per ref name actually in use, unaffected by this: the storage key is the hex SHA-256 digest of the ref name bytes, the same digest used internally to attribute each container entry to its own ref.

pointer-index-{a,b}.container is an append-only, checksum-framed sequence of pointer entries; each entry records one ref’s human-readable name, its published RefState object id, and the SHA-256 key derived from that name. A ref’s current pointer is its last matching entry in the live slot — republishing a ref appends a new entry rather than rewriting the old one, and which slot is live is named by this container’s own generation log, not always a (see Compaction below). It is useful for lookup and recovery, but is not trusted alone: verification checks pointer content against RefState objects and ref-log evidence, the same as before.

received-index-{a,b}.container holds the same shape of entry for received refs — pointers imported by prikk bundle import under the separate remotes/<name> namespace (DC-78 §D4), never refs/by-id/: an imported RefState object keeps the origin repository’s own embedded ref name, which could never agree with a locally renamed pointer, so received refs get their own container and key space rather than a special case in the ordinary one. Last-entry-wins, the same as the ref-pointer index, and compacted the same way. This index is never consulted by verify_repository directly — every object a received pointer leads to is checked by the ordinary object-store scan regardless of how it was discovered.

log-a.container/log-b.container hold every ref’s RefUpdate log records, interleaved by append order; a reader filters to one ref’s own subsequence by that same per-record key. Each record carries a signed RefUpdate envelope inline with frame magic, versioning, length, and checksum. Ref logs are publication evidence when their record chain, referenced RefState objects, target Blocks, signatures, and trust policy checks all hold — unchanged in meaning, only in storage shape. Slot b is allocated alongside slot a at init and permanently unused: the ref log is DC-38/DC-69’s audit trail and must never be compacted, so writes always target slot a (see Compaction below).

refs/locks/*.lock files are local synchronization files for ref-specific publication and repair, not a root of trust. There is no longer a temporary-candidate mechanism: an append-only pointer entry has no candidate value to stage before becoming durable, so a publish that used to write, sync, and promote a candidate now durably appends the pointer entry directly, in one step.

refs/by-id/ and refs/logs/ are no longer initialized directories — nothing has read or written either since ref publication moved into containers, so init no longer creates them, and a repository missing them behaves identically to one that still has them from before this change (their presence or absence is not validated at open).

refs/tmp/ is different and is genuinely required. init still allocates it, and verify lists it on every run, so a repository missing it fails verification with directory is absent: refs/tmp. Nothing has written into it since ref publication moved into containers, so the scan can only ever find nothing — but the directory must exist for the scan to succeed.

Active Session

The default active-session paths are:

active/default/queue.wal
active/default/active.lock
active/default/ref-name

These files are runtime-written, not guaranteed members of a bare initialized repository.

queue.wal stores exact signed Patch envelopes before sealing. WAL records are load-bearing local session state: they are the pending changes that seal replays and publishes, but they are not sealed history until publication succeeds.

ref-name records which local branch ref owns a non-empty active WAL. Missing or malformed active ref metadata on a non-empty WAL is an integrity issue because seal must not guess the publication target.

active.lock is a local synchronization file. It prevents concurrent active-session writers, but it is not evidence of repository history or trust. Stale lock cleanup after a crash is manual today; see concurrency and locking for the current operator boundary.

Trust Store

The repository-local MAINTAINER trust containers are:

trust/keys.container
trust/policy-{a,b}.container

Both are allocated empty at init, then appended to by prikk trust maintainer add/remove — no name is created after init.

keys.container holds one append-only entry per adopted key id: the key id and its Ed25519 public key. It has no slot pair and is never compacted — TOFU history must persist across key removal (see Compaction below).

policy-{a,b}.container holds a sequence of complete policy snapshots in its live slot (named by this container’s own generation log, not always a) — each add or remove appends the entire current adopted-key-id list, not an incremental change; readers take the last complete snapshot, with required = 1 meaning any one adopted key’s signature suffices (never stored — it is a constant, not configurable). Seal checks the configured MAINTAINER signer against this repository-local policy before publication, and verify checks publication envelopes against the same local trust boundary.

This trust store is authority for current publication-trust checks. It is not remote trust, global identity, key rotation, hosted forge policy, or a multi-maintainer threshold system. Key revocation is supported (prikk trust maintainer remove): a removed key’s material is retained internally (so a different key presented later under the same id is still refused), but it no longer counts toward the adopted set or reserves its case-folded id.

Compaction