feat(compile): V2.2 on-disk per-module object cache (follow-up to #131, #132)

[TheHypnoo]

Summary

Implements the V2.2 on-disk object cache scoped in #131 and follows V2.1's in-memory AST cache from #132. Each .ts module's compiled .o bytes now land at .perry-cache/objects/<target>/<key:016x>.o, shared across every perry compile / perry run / perry dev invocation on that project.

The real perf win lives here, not in V2.1. On a 30-module synthetic project on my M1:

Scenario	Median (5 runs)	vs baseline
--no-cache baseline	714 ms	—
Cold cache (empty, warmed in run)	709 ms	~0% overhead
Warm cache (all hits)	509 ms	−29% (205 ms saved)
1 module edited, 29 cached	512 ms	−28%

Cost scales with changed modules, not total — the perry dev watch loop is the primary beneficiary.

Design

• ObjectCache (thread-safe via AtomicUsize counters, one file per entry so rayon workers don't contend) uses atomic tmp-then-rename writes. IO errors are counted and the codepath degrades to uncached — the cache is strictly an optimization, never a correctness dependency.
• compute_object_cache_key is a streaming djb2 (mirroring build_optimized_libs's prior-art pattern) over every CompileOptions field that affects compile_module's output bytes:
  • module source hash (djb2 computed once in collect_modules and stored on CompilationContext::module_source_hashes — no second file read)
  • target triple, is_entry_module, output_type, feature flags (needs_stdlib/needs_ui/needs_geisterhand/needs_js_runtime)
  • all import maps/sets — sorted so HashMap iteration order doesn't leak into the key
  • imported classes with full signature (name, source_prefix, ctor arity, fields, methods, parent, source_class_id)
  • imported enums, type aliases, imported async funcs, imported vars, imported param counts, imported return types
  • enabled features, i18n snapshot, CARGO_PKG_VERSION
  • topologically-sorted lists (non_entry_module_prefixes, native_module_init_names) preserve order so a link-ordering change (v0.5.127-128 bug class) invalidates consumers — this is the acceptance criterion @ralphhempel called out in V2 watch mode: incremental compilation cache — scoping (follow-up to #126) #131
• Disabled automatically in bitcode-link mode (PERRY_LLVM_BITCODE_LINK=1) since compile_module emits .ll text, not object bytes.

CLI surface

• --no-cache flag on compile / run / dev
• PERRY_NO_CACHE=1 env var (CI-friendly override)
• PERRY_DEV_VERBOSE=1 prints • codegen cache: H/T hit (M miss) per build (same env var V2.1 uses for parse cache:, so one lever turns on both lines in perry dev)
• perry cache info — location, total size, per-target breakdown
• perry cache clean — wipe .perry-cache/ for the current project

Deviations from issue #131 scoping

Two worth calling out so the maintainer can veto if desired:

1. Scope: the issue said "dev-only first, promote to compile later". This PR wires the cache into perry compile / perry run / perry dev all at once. Rationale: the cache has no dev-specific coupling (pure CompileOptions + source_hash key), and perry run / CI batch builds benefit from the same warm-hit path. Happy to gate behind a dev-only flag in a follow-up if preferred.
2. Plumbing: CompileResult gained an optional codegen_cache_stats: Option<(hits, misses, stores, store_errors)> so dev.rs can print the codegen cache: line alongside parse cache: after run_with_parse_cache returns. Widget/web/wasm helper returns get None (they never touch the codegen cache); the three codegen paths (--no-link, is_dylib, main success) populate stats from ObjectCache.

Tests

15 unit tests in object_cache_tests (all passing):

• Key stability across HashMap-insertion-order permutations
• Key divergence on every invalidation axis (source hash, perry version, target, entry flag, non-entry-prefix order, imported-class arity, bitcode mode)
• Disabled cache no-ops cleanly; no counters bumped, no files created
• Cross-target isolation (target-a and target-b keyed separately)
• Store → lookup round-trips bytes verbatim

Integration test (scripts/run_cache_tests.sh) on test-files/module-init-order/ (the real multi-module fixture that exercises topological init order):

• Baseline --no-cache → records expected output
• Cold cache: 0/4 hit (4 miss), output matches baseline
• Warm cache: 4/4 hit (0 miss), output matches baseline
• Source edit on one module: 3/4 hit (1 miss), output reflects the edit (the stale-bytes anti-regression)
• Restore source: 4/4 hit returns to full-hit state
• perry cache info / perry cache clean smoke-tested at the end

What does NOT ship in this PR

Per CONTRIBUTING.md: no [workspace.package] version bump, no **Current Version:** edit on CLAUDE.md, no "Recent Changes" entry — maintainer folds those in at merge time.

Test plan

• `cargo test -p perry --bin perry object_cache_tests` — 15/15 pass
• `cargo test -p perry --bin perry parse_cache_tests` — V2.1's 8 tests still pass (no regressions)
• `scripts/run_cache_tests.sh` end-to-end — PASS
• Benchmark on 30-module project: ~29% warm-rebuild speedup, ~0% cold-cache overhead
• Maintainer review of cache-key field selection vs any `CompileOptions` additions landed since branching

Closes (partial) #131.

[proggeramlug]

Merged to main as fast-forward at v0.5.160 (commits 50d09ed + de514d5 + 1a12afe).

Thanks @TheHypnoo! Folded in at merge time per CONTRIBUTING:

• Rebased onto latest main (on top of v0.5.159's winget fix).
• Added three post-audit fixes in 1a12afe: (1) PERRY_DEBUG_INIT / PERRY_DEBUG_SYMBOLS / PERRY_LLVM_CLANG hashed into the cache key so these env vars can't silently poison subsequent runs; (2) .perry-cache/ added to .gitignore (cache is machine-local because clang's -mcpu=native bakes host CPU features); (3) scripts/run_cache_tests.sh backreference ([0-9]+)/\1 → [0-9]+/[0-9]+ for BSD grep (macOS) portability.
• Bumped to v0.5.160 + CLAUDE.md Recent Changes entry.

16/16 unit tests pass, integration smoke passes, manual end-to-end (single-file, multi-module, cache info/clean, env-var-flip invalidation) all green.