Guide

Advanced Topics

Deeper tooling for verification, IR, sandboxes, and power-user workflows.

FileSet

Agent runs are the expensive part of a build: minutes of wall-clock time and real API spend per spec. Overplane avoids repeating them through content-hashed builds: every build step's output is captured as a file set, a deterministic, content-addressable snapshot of a directory tree, and cached under a key derived purely from the step's inputs. Same inputs, same key, no agent run. This page explains the snapshot format that makes that work, and the overplane fileset commands that expose it directly.

What a file set is

A file set records only what defines content: each file's relative path, permission bits, raw size, and a short content hash (12 hex characters of SHA-256), followed by the snappy-compressed payloads. No timestamps, no ownership, no duplicate paths; entries sorted in one total order. Because nothing non-deterministic is recorded, the same logical tree always produces the same bytes and the same content hash, which is embedded in the blob and re-verified on load, so corruption is always detected.

A file-set delta is the difference between two file sets: set (add or replace a path) and del (remove a path) operations. Deltas are whole-file; applying the diff of two sets always reproduces the second set exactly, hash and all.

How content-hashed builds use it

During overplane build, every step's result becomes a cache entry in dirs.cache/cas/ (a content-addressed store of .val blobs with .meta.json records):

• Raise and codegen steps cache a file-set snapshot of what the agent wrote. The key hashes everything that could change the output: the full rendered prompt (including the spec body), the agent backend and model, the sandbox image, and, for codegen, the content hash of the accumulated output of all prior specs.
• Verify steps cache the Z3 verdict, keyed by the content of the SMT inputs and the sandbox image.

On a rebuild, each step recomputes its key first. A hit restores the snapshot into the working tree and skips the agent or solver entirely; a miss runs the step and stores the result. The consequences you will notice:

• Editing one spec re-runs that spec's steps and everything downstream of it; untouched specs restore in milliseconds at zero cost.
• Purely cosmetic changes to a spec's frontmatter do not invalidate anything, because cache keys hash the rendered prompt, not the file.
• Failed agent runs are never cached, so a retry always re-executes.
• Each cached agent step records the original run's token usage and cost in its metadata; overplane cache ls shows the entries.

Restores use the same careful sync as the final output to dirs.code: files identical in content and mode are left untouched (preserving inodes and file watchers), changed files are written in place, and strays are deleted for a clean tree (--additive overlays instead).

Working with file sets directly

The same machinery is exposed as overplane fileset with five subcommands: create, inspect, extract, diff, and apply. Use - as a blob path to read stdin or write stdout.

# Snapshot ./src into out.fset (gitignore respected, .git skipped):
overplane fileset create ./src out.fset

# Inspect entries, sizes, modes, hashes, and the content hash:
overplane fileset inspect out.fset

# Materialize a blob (clean sync; --additive to overlay):
overplane fileset extract out.fset ./restored

# Delta between two snapshots, and reproduce the second from the first:
overplane fileset diff a.fset b.fset delta.fsd
overplane fileset apply a.fset delta.fsd rebuilt.fset
# rebuilt.fset is byte-for-byte identical to b.fset

create honors .gitignore (with full nested semantics) and skips .git by default; pass --no-gitignore and --include-git to capture everything, and --store to skip compression. extract refuses a non-empty destination unless --force is given. Determinism details: a global or user-level ~/.gitignore is never consulted, and an empty file set or delta is a valid, fully supported value. Pass --json to inspect for a canonical, scriptable listing.