feat(cache): closes #686 — HIR-addressable per-module object cache (Plan C)

[TheHypnoo]

Summary

Closes #686. Replaces the V2.2 source-bytes hash in the per-module object cache key with a deterministic fingerprint of the post-transform HIR that perry_codegen::compile_module actually consumes. Formatter-only edits, comment changes, quote-style rewrites, and any other source change that lowers to identical final HIR now hit the cached .o.

• New perry_hir::stable_hash module with hash_module(&Module) -> u64 and a streaming hash_module_with<H: StableHasher> variant. Walks the HIR with an exhaustive match (no _ => wildcards) over every variant, so adding a new HIR variant breaks the build and forces the author to assign a stable tag and walk children. The only HashMap reachable from Module (ObjectType.properties) is sorted by key before emit.
• compute_object_cache_key's second parameter renamed source_hash → hir_hash; field tag \"src\" → \"hir\" so any pre-Plan C: HIR-addressable object cache for incremental builds #686 cache entries cleanly miss.
• Hash is computed inside the rayon per-module job at compile.rs:3905, after every HIR-mutating pass has run. compile_module(&Module, ...) documented as load-bearing — switching to &mut would have to also move the hash to AFTER codegen.
• CompilationContext.module_source_hashes and the per-module djb2_hash(source.as_bytes()) call in collect_modules.rs removed (no remaining consumers).

Diagnostics

• PERRY_DEV_VERBOSE=1 now prints per-miss cache miss: <name> hir=<...> key=<...> lines on top of the existing aggregate codegen cache: H/T hit (M miss) summary.
• PERRY_CACHE_DEBUG_HIR=1 dumps the post-transform HIR of every miss to .perry-cache/debug/<key>.txt so two miss-dumps can be diff-ed to find the divergent field.

Tests

• 5 new perry_hir::stable_hash unit tests covering insertion-order independence, behavior-vs-cosmetic differentiation, per-field metadata sensitivity, and a pinned in-process determinism check.
• New crates/perry-hir/tests/cross_process.rs + examples/stable_hash_cross_process.rs: spawns the example binary twice via cargo run --example and asserts byte-identical stdout. This is the only way to catch a forgotten HashMap sort, since Rust's RandomState only randomizes iteration BETWEEN processes, not within one.
• Existing object_cache_tests::key_changes_with_source_hash renamed to key_changes_with_hir_hash with a comment documenting the inverse case ("same source bytes, different HIR" is covered by build_id, not by this hash). All 18 cache tests stay green.
• scripts/run_cache_tests.sh gains two new steps after the existing cold/warm/partial/rewarm cycle:
  • cosmetic edit: appends a trailing comment, asserts ALL hits and unchanged runtime output.
  • behavior edit: mutates a literal so the HIR differs, asserts exactly 1 miss and runtime output reflecting the change.

Test plan

• `cargo test -p perry-hir stable_hash` (5 unit tests pass)
• `cargo test -p perry-hir --test cross_process` (1 integration test passes)
• `cargo test -p perry --bin perry object_cache_tests` (18/18 pass)
• `bash scripts/run_cache_tests.sh` end-to-end:
  • cold: `0/4 hit (4 miss)`
  • warm: `4/4 hit (0 miss)`
  • partial (source change): `3/4 hit (1 miss)`
  • rewarm: `4/4 hit (0 miss)`
  • cosmetic: `4/4 hit (0 miss)` and runtime output unchanged ← Plan C gate
  • behavior: `3/4 hit (1 miss)` and runtime output reflects edit
• `cargo build --release -p perry-runtime -p perry-stdlib -p perry` clean
• `cargo test --release --workspace --exclude perry-ui-{ios,tvos,watchos,visionos,android,windows,gtk4}` green except for the pre-existing perry-codegen::manifest_consistency::every_dispatch_entry_has_manifest_counterpart failure from v0.5.810 (unrelated to this PR — verified by reproducing on main)

Out of scope (per #686 non-goals)

No JIT, no interpreter, no separate perry dev backend, no Plan B (linked-binary cache), no effort to keep the HIR hash minimal across mono bookkeeping changes — over-invalidation when monomorphize_module rewrites a node into something codegen would have produced identical bytes for is the accepted trade for keeping the hash a simple post-transform fingerprint.

Notes for the maintainer

Per CONTRIBUTING.md, this PR does not touch `Cargo.toml` version, the `Current Version:` line in `CLAUDE.md`, or `CHANGELOG.md` — left for the maintainer to fold in at merge.

[TheHypnoo]

CI status update after rebasing on `main` (now at v0.5.818) and adding the missing `Expr::AsyncStepDone` arm to the exhaustive match in `stable_hash.rs` (the variant landed in upstream commit `b216cef1` while this PR was open).

The remaining red jobs are all pre-existing on `main`, not introduced by this PR:

Job	Root cause	Where
`lint` (`cargo fmt --all -- --check`)	rustfmt diffs in `cjs_wrap.rs`, `optimized_libs.rs`, `targets.rs`, `api-manifest/entries.rs`, `codegen/expr.rs`, etc.	All upstream files this PR doesn't touch
`cargo-test`	`perry_codegen::manifest_consistency::every_dispatch_entry_has_manifest_counterpart` — the v0.5.810 ink-API additions (`fastify::type`, `better-sqlite3::raw`, 12 `perry/tui` hooks) are in the dispatch table but missing from `API_MANIFEST`	`crates/perry-api-manifest/src/entries.rs`
`api-docs-drift`	Same v0.5.810 manifest changes; `docs/src/api/reference.md` + `docs/api/perry.d.ts` weren't regenerated	`docs/`
`doc-tests (gtk4)`	`javascriptcore6-sys v0.4.0` custom build script failure on the runner	Infrastructure

Confirmed by inspecting the most recent `Tests` workflow run on `main` itself (sha `6640820a`) — same failures: `lint`, `api-docs-drift`, all `doc-tests` variants. The `cargo-test` failure is newer (post-`6640820a`, from the v0.5.810/811 manifest landings).

`harmonyos-smoke` is the one job in this matrix that exercises this PR's code path — it's green.

Files changed by this PR (9 total, none of them in the above failure list):

```
crates/perry-codegen/src/codegen.rs
crates/perry-hir/examples/stable_hash_cross_process.rs
crates/perry-hir/src/lib.rs
crates/perry-hir/src/stable_hash.rs
crates/perry-hir/tests/cross_process.rs
crates/perry/src/commands/compile.rs
crates/perry/src/commands/compile/collect_modules.rs
crates/perry/src/commands/compile/object_cache.rs
scripts/run_cache_tests.sh
```

Local validation on this branch:

• `cargo test -p perry-hir` → 25 + 1 (cross-process integration) green
• `cargo test -p perry --bin perry object_cache_tests` → 18/18 green
• `bash scripts/run_cache_tests.sh` → cosmetic edit hits all 4/4 (Plan C gate), behavior edit produces exactly 1 miss

Happy to fold in maintainer fixes for the upstream-broken jobs if that's preferred over waiting for a separate cleanup PR — just let me know.

[proggeramlug]

@TheHypnoo Sorry, main is "corrupted" right now by all the updates flying in. Will clean it by EOD and merge this :)