Shared incremental caches#
The cache layout is manifest, interfaces/<Module>.<key>.aci,
programs/<digest>.acp, and artifacts/<key>.elf with its .meta. An interface's key digests everything its reuse
requires (schema, edition, compiler identity, module, source digest and the
direct dependencies' interface identities), so one cache holds a module's
interfaces for several sources at once -- two branches, or a workspace and the
mutated copies a gate checks -- and ALPHA_CACHE (the default for --cache)
lets such copies share it. Beside them the cache keeps receipts/ (each
command's run receipt, the path it prints), counters/<key>.unique-nodes
(the unique-node count of a closure every module of which came from the cache,
keyed by those interface digests and the workspace identity, so such a check
need not decode every interface body to report it) and stamps/ (below). The
interface directory is bounded at 32768 entries, programs/ and counters/ at
4096 and receipts/ at 512 (one cache serves a whole local gate run, every
gate and its mutants' copies: at 4096 interfaces and 512 programs such a run
evicted its own entries, so a clean root re-checked every run):
past a bound, the least recently used entries (a hit refreshes an entry's time)
are removed down to seven eighths of it.
Each publisher creates its own temporary file beside
the destination, writes and closes it completely, then atomically renames it.
An exception cleans up only that publisher's temporary file. A killed process
can leave an unpublished candidate; later compiler startups do not sweep it.
Admission depends on each entry, not on the manifest. Interface decoding checks the schema and integrity digest; reuse also requires the expected module, source digest, dependency identities, compiler identity, and edition. A sealed program's key includes the resulting interface identities. A mismatched entry is recomputed. Writers with different configurations write different keys, so they no longer replace each other's entries; a mismatched entry can never be reused.
Built artifacts#
alpha build on the default (evaluator) lane keeps the executable it wrote
in artifacts/<key>.elf, and the erased reduction's report (the numbers it
prints) in <key>.meta. The key digests the compiler identity, the edition,
the target and the sealed program's key (its closure's interface digests),
which are everything the backend reads: erasure, the erased reduction, the
runtime graph and the evaluator image are a pure function of the sealed
program. A rebuild of a program whose closure did not change reads the entry
instead of compiling (the self-hosted compiler: 44 s to 0.6 s) and writes the
same bytes and prints the same report. --direct, --object, --mutant,
--profile tune and --no-cache compile. The directory is bounded at 2048
entries of each kind, least recently used first, like programs/.
Digests trusted by file stamps#
A source's digest (SHA-256 of its bytes) and the compiler's identity (the SHA-256 of its executable) are taken from a stamp table while the file's stamp is the one recorded with them, as git's index takes a file to be unchanged. The stamp is the file's device, inode, size, and modification and status-change times in nanoseconds:
- writing a file sets its modification time;
- every change to it (a write, a rename onto its name, a
touchback to an old time) sets its status-change time, which no program can set.
A file is stamped before and after it is read. Only a read the file did not change during, of a file unchanged for two seconds, is recorded. A file changed within its timestamps' granularity is digested again next time, as git treats racily clean entries.
Sources are recorded in the cache's stamps/sources (16,384 entries, keyed by
device and inode, so hard-linked copies share an entry). The compiler is
recorded in $XDG_CACHE_HOME/alpha/stamps/compilers-sha256 (64 entries; the
former Fletcher-128 compilers table is never read back). --no-cache
digests every source. Without a user cache directory, the executable is
digested. debug/cache-invalidation-check.py builds after a same-size edit
whose old modification time was put back, and expects the new value.
The manifest describes the last writer's schema, edition, and compiler. It is
informational. Changing it no longer resets the interfaces/programs directories.
Entry encodings and JSON field names are unchanged; entries of the earlier
one-file-per-module layout are never read again and alpha cache prune removes
them.
alpha cache stats counts promoted .aci and .acp files and their byte sizes.
alpha cache verify validates promoted entries and classifies each problem
as corrupt, stale (another interface schema or edition, or the earlier
layout) or misplaced. alpha cache prune removes only promoted interfaces
that are outside the selected root's graph, stale, or in the earlier layout. These commands do
not treat another process's temporary files or unrelated files as entries.
Unpublished candidates remain until explicit cleanup; sealed programs and
interfaces are trimmed only by the bounds above, and there is no other
automatic concurrent garbage collection.
Run python3 debug/cache-concurrency-check.py --alpha /path/to/alpha --output /mounted/evidence for four rounds of four fresh processes sharing a cache:
two executable identities, two editions, and valid/invalid source snapshots.
Every result is compared with its corresponding cache-free check, including
module identities and diagnostics. The test checks foreign-file preservation,
verification, warm convergence, statistics, pruning, and corruption recovery.
This guarantee applies to repaired writers. An older compiler that still sweeps or resets the same cache directory can delete another writer's files. Full crash/power-loss qualification and the broader L23 incremental state-machine acceptance remain separate work; atomic rename does not imply durable fsync.