# Execution-Plan Cache

Execution-plan caching is an optional optimization around the authoritative
`plan_recipe(...)` contract. It does not cache run results, operation outputs,
or planning failures.

`ExecutionPlanCache` is an in-memory, bounded LRU cache. Its public key is a
canonical SHA-256 digest over every semantic input to planner resolution:

- the complete effective recipe;
- normalized runner and backend selectors, plus implementation selection;
- execution-profile enforcement policy;
- the research and execution-profile validation catalogs;
- execution-plan, planned-step, operation-contract-set, and cache-key schema
  versions;
- every operation contract in the supplied registry, including parameter
  schemas and materialization declarations;
- the registry's Python class identity;
- each operation's Python class identity.

The authored recipe hash is run provenance rather than a planner input. It is
therefore included in cache evidence when supplied, but it does not reduce
hits between authored recipes that compile to the same effective recipe.

## Safety And Concurrency

An execution plan embeds concrete `Operation` objects. Internally, cache slots
are therefore partitioned by `OperationRegistry` object identity even when two
registries have the same deterministic semantic key. This guarantees that a
plan requested with a new registry cannot execute an operation instance from
an older registry. Entries weakly reference the registry itself, so the global
bounded cache does not keep an otherwise-unused registry and all of its
unreferenced operations alive.

Plans and cache evidence are immutable. Concurrent requests for the same key
and registry coalesce around one planning operation; requests for distinct
keys can plan concurrently. Callers already waiting on a failed planning
attempt observe that same failure, but the failure is never retained for a
later request.

The cache defaults to 128 entries and evicts the least-recently-used entry.
Callers can:

- set `use_cache=False` for a one-shot bypass;
- call `invalidate(key_sha256=...)` for semantic-key invalidation;
- optionally restrict invalidation to one registry;
- call `clear()` to remove all entries;
- call `stats()` to inspect hits, misses, bypasses, evictions, entries, and
  in-flight planning operations.

Both `clear()` and `invalidate()` also suppress insertion of plans that were
already in flight when invalidation occurred.

## Evidence

Each lookup returns `ExecutionPlanCacheResult(plan, evidence)`. Evidence is a
small serializable object with `outcome` (`hit`, `miss`, or `bypass`), the
deterministic key schema/digest, effective-recipe, registry, validation-catalog, and plan digests,
optional authored-recipe provenance, and the cache capacity/current size.
Executors can persist `evidence.to_dict()` in their manifest and summary
without making cache state part of the execution plan digest.

Run-bundle verification checks the evidence schema and links that can be established from the
bundle. The process-local hit/miss outcome and opaque cache-key/registry digests are performance
telemetry, not an independently attestable scientific-result claim.

`EXECUTION_PLAN_CACHE_KEY_SCHEMA_VERSION` must be incremented when resolution
semantics change without an execution-plan schema-version change. This makes
invalidation explicit instead of relying on process restarts.