Evaluate each distinct body once, parse the stage once and index used_by per inspection - #184

Ported from the fork, where it is merged and running: axisrow/BeamCraft#53 (branch bug/26-inspection-cache, merged there on 2026-10-23). Refs the fork's issue 26, finding 2 — the remaining cost inside the one inspection that every read command runs. Every reply is byte-for-byte unchanged by design.

What this changes

1. Body cache (beamcraft_engine::query::committed::BodyCache, used per thread by beamcraft_cli::plate::evaluate_decoded). Kernel bodies are kept by the exact bits of their complete shape inputs: contour, thickness, holes and cut of a plate; axis, roll, cut and resolved profile content of a member.
   • Id, label, kind, placement, material and the profile digest are not inputs. Tests check that bodies differing only in those are equal before they may share an entry.
   • No digest stands in for an input. -0.0 and 0.0 are different keys; the P04 signatures fold them, so they are not reused as keys.
   • The cache is in-process only (owner decision), bounded at 32 MiB and MAX_ELEMENTS entries, cleared when full, and never keeps a failure. A command's read of the head, its commit verifier and the copies of one model share bodies.
2. used_by index: definitions builds the material-to-plates map once instead of scanning every plate for every listed definition, on every fit_page attempt.
3. One parse (beamcraft_layer_engine::Reader::open_validated). inspect_revision and the commit verifier parsed and composed the stage twice (validate_layers, then Reader::open). Now the same rules run on the candidate that is then installed, with the same order, codes and messages.

Trust is unchanged. Received layer blobs are still verified against the manifest, structurally validated, indexed and decoded, and definition digests are recomputed. verify_derived still compares every stored mesh with the body, cached or not. A new test warms the cache, commits a structurally valid but wrong stored mesh for a copy, and requires INTEGRITY_ERROR with the body served from the cache.

Port notes

• Base: upstream master (236ce9b, including Fix K1 plate contours, body frames and unsupported USD drafts #174). The four topic commits were cherry-picked from the fork; the conflicts were adapted to the current master state: plate_users sits directly above the documented pub(crate) fn definitions_json, and the layer-engine files (Reader::open_validated sharing one implementation of the rules with validate_layers) and the test follow the fork's merged form (beamcraft_json, ElementId::prim_path markers).
• The evaluation stays lenient. The fork's strict cached evaluation had to be reworked for upstream: since Fix K1 plate contours, body frames and unsupported USD drafts #174 a revision can hold valid authored-only (unsupported) plates, and a strict per-plate evaluation inside evaluate_decoded made the commit verifier refuse exactly the revisions the draft flow is meant to store (reproduced with a near-planar rectangular plate from contour_plates.rs). The cache now enters through evaluate_committed_drafts_cached (engine), which mirrors evaluate_committed_drafts per plate — same checks, same order, same unsupported classification — and the uncached entry point delegates to it with a disabled cache. The second pass of an inspection reuses the same thread's cache instead of evaluating every body twice.
• The K1 plate_draft evolution that master gained since the fork's measurement base is untouched.

Measured, not assumed

Whether to remove the duplicate passes was decided in runs (owner decision): body cache (C), one parse (P) and one verified read of each layer blob (R) were measured in all eight combinations plus the base, against a decision rule fixed beforehand. C and P were kept; R had no measurable effect. The design note has the full tables: docs/design/issue-26-inspection-cache.md.

Before/after on the fork (Linux container, 4 vCPU Xeon 2.8 GHz, rustc 1.97.0, the dist release profile, fixtures of contributor-original synthetic stores, alternating runs; every output byte-identical between the two binaries; medians in ms):

Max RSS moves by at most +0.3 MiB and falls by up to 2.8 MiB on the frame (one parse holds one stage, not two). The figures were taken in the fork's environment and were not re-measured for this port; the code paths are the same.

How you verified it

On the fork (original PR, Linux): clean rebuild, cargo fmt --all -- --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace (1,247 passed), fixtures verify, beamcraft-boundaries check, cargo doc -D warnings, wasm32 check, cargo deny check; plus byte-for-byte comparison of every output of plate-inspect, definitions, view-export --out - and copy-element on the four fixtures.

This port (macOS, aarch64): cargo fmt --all -- --check, cargo clippy --workspace --all-targets -- -D warnings and the full cargo test --workspace — green.

New tests:

• crates/engine/src/query/committed.rs: six unit tests — cached bodies equal fresh ones for boxes, contours, holes and cuts, and for rectangle and I-section members; every shape input misses; excluded fields provably do not change the body; signed zeros are different keys; refusals are not kept; the budget and the disabled cache behave as documented.
• apps/beamcraft-cli/tests/inspection_cache.rs: cold and warm inspections are equal with hit and miss counts asserted; a warm cache still refuses a structurally valid but wrong stored mesh with INTEGRITY_ERROR, as do a cold thread and the CLI.
• apps/beamcraft-cli/tests/definitions.rs: used_by lists, their element-id order, the plates-only rule and paging.
• crates/layer-engine/tests/authored.rs: open_validated against validate_layers + Reader::open — same result on a valid stage, same refusal on broken definition, mesh, schema-marker and parse inputs and an unknown schema pin, live view kept after a refusal.

Never-crash

• No new unwrap/expect/panic!/todo! outside tests. The thread-local cache uses try_with and try_borrow_mut and falls back to a cache of the call.
• No indexing or slicing with input-derived positions. Allocations sized by input are capped: the cache budget counts key and body bytes, and the entry count is capped at MAX_ELEMENTS.
• No unsafe

Provenance

• Nothing taken from Tekla Structures or any Trimble product (assets, code, documentation, tables)
• No GPL/AGPL code copied in
• No new asset, nothing to add to ATTRIBUTION.md

Issue tracking

Fixes #372