Cache validated run artifacts and reduce cold compilation costs

[bradcypert]

Repeated plum run commands currently regenerate LLVM and compile all native inputs. This adds validated reuse of generated IR and native objects, while linking a fresh executable for every run, and reduces cold compiler work without changing emitted IR.

Refs #63. This implements the artifact-cache and cold-compilation work; the full issue's performance targets and per-module compilation remain open.

Changes

• Key IR reuse by compiler content, source/dependency discovery, manifests, modes, and actual embedded-file reads. Validate cached data and inputs before reuse.
• Reuse native objects only for certified Linux Clang invocations. Reprocess C headers on each run, hash the actual toolchain, and reject assembly-dependent inputs from object reuse. Other platforms and custom compilers retain ordinary native compilation.
• Publish complete cache entries and embedded shims atomically, verify integrity, and recover from corruption, concurrent publication, cache cleaning, and unavailable cache roots.
• Add a configurable 1 GiB retention budget, oldest-entry eviction, abandoned-stage cleanup, cache list/clean controls, opt-out environment variables, traces, and phase profiling. Keep build, check, emit-llvm, and test uncached.
• Remove repeated source decoding and helper-discovery scans while preserving checking, initialization order, and byte-identical LLVM output.
• Add correctness and measurement harnesses, CI coverage, documentation, and a proposed per-module architecture. Refresh the tracked compiler binary and LLVM bootstrap seed; most of the diff is generated seed output.

Measurements

Three sequential samples on Linux x86_64 with Clang 22.1.8, comparing release compiler builds. Application runs use the default debug mode; complete samples and hashes are in the measurement report.

Operation	Original	New
Full compiler LLVM emission	36.11 s	3.23 s
Full compiler check	6.48 s	0.55 s
JSON example, uncached run	1.45 s	1.17 s
JSON example, warm cached run	1.45 s	0.55 s
JSON example, empty cache	1.45 s	2.24 s

LLVM output is byte-identical for the hello example, JSON example, and complete compiler. Warm runs still preprocess native inputs, validate the toolchain, and link. The provisional 200 ms warm-run and 10% cache-miss-overhead targets are not met, and the gh-dash/TUI workload has not been measured.

Validation

• 412 Linux cache assertions, including freed-memory poisoning and cached Plum/C debug-location checks, covering source and embed invalidation, header/library/toolchain changes, pinned dependency tampering, artifact corruption, runtime arguments/stdin/cwd/PTY behavior, custom compiler fallback, assembler file dependencies, concurrent publishers, and deterministic cache-clean races.
• 64 package checks; 20 compiler unit tests and 376 formatting checks pass.
• Full maintenance suite, including 190 sanitizer/rejection fixtures, passes; final targeted bootstrap, cache, package, memory, docs, shim, and cross-compilation checks pass.
• Fresh seed bootstrap reaches byte-identical LLVM fixed point. Peak compiler emission/check RSS is 109/41 MB, within the 128/64 MB limits.
• Cross-compilation covers macOS arm64/x86_64, Windows x86_64, and Linux arm64; Linux arm64 executes under QEMU. Linux, Linux arm64, macOS and Windows runtime acceptance passed in the corrected CI run.
• git diff --check passes.

See results and limitations, validation evidence, and the future incremental-compilation proposal.

Windows CI correction

The first CI run passed Linux, Linux arm64 and macOS validation. Windows compiler construction, ordinary programs and LSP passed, but a cache fixture containing ü in its filename repeatedly missed: saved ANSI argv bytes were rejected by UTF-8 decoding. Commit 11d7bc5 validates the saved path bytes directly, rejects malformed hex/NUL paths, and adds a Linux byte-filename regression for hits and edited-source misses. The harness also recognizes MSYS/Cygwin Python when guarding Unix-only PTY, symlink and executable-path fixtures. Native Windows console attachment remains outside these Unix PTY tests.

The corrected compiler and seed pass local cache, unit, formatting, fixed-point bootstrap and cross-compilation checks. Windows runtime checks pass in the corrected CI run. Recorded benchmark data retains the original implementation's digest.

macOS retention correction

The new retention check exposed a dangling CStr: the cache-root String
was freed before the native pruner read it. Commit d469d02 keeps the
owning String alive through the call and fixes the same borrowing pattern
in the debug fixture. A Linux allocator-poisoning regression fails against
the previous compiler and passes with the correction.

All 412 local cache assertions, compiler unit/format checks and seed
bootstrap checks pass. macOS platform/cache checks and the required
Clang 18 Linux object-cache/debug job pass in
the corrected CI run.
The remaining jobs are still running at this update.