Deterministic identity hashing, confidence-aware cacheability rules, and pluggable two-tier (L1 fast key-value + L2 durable store) caching behaviour for JevDSL.

Cache Key Invariance & Auto-Invalidation

Every cache key ("jev_<sha256>") is derived deterministically from:

1. The recursively canonicalized input state map (canonicalize/1).
2. The compile-time %SystemOneSDK.Prepared{fingerprint: fp} SHA-256 digest of the contract's instructions, question types, and criteria.

Because prepared.fingerprint changes whenever a prompt or criterion is edited in defnoul, defchoice, defscore, or defjev, stale cached evaluations are invalidated automatically at compile time without manual cache flushing.

Telemetry Events

JevDSL.Cache emits the following :telemetry events:

• [:jev_dsl, :cache, :hit] — Measurements: %{duration: native_time}. Metadata: %{cache_key: String.t(), adapter: module(), tier: :l1 | :l2, contract: atom() | String.t() | nil}.

• [:jev_dsl, :cache, :miss] — Measurements: %{duration: native_time}. Metadata: %{cache_key: String.t(), adapter: module(), tier: :l1 | :l2, contract: atom() | String.t() | nil}.

• [:jev_dsl, :cache, :write] — Measurements: %{duration: native_time}. Metadata: %{cache_key: String.t(), adapter: module(), tier: :l1 | :l2, contract: atom() | String.t() | nil}.

Implementing a Custom Cache Adapter

defmodule MyApp.JevCacheAdapter do
  @behaviour JevDSL.Cache

  @impl true
  def get(key, _opts) do
    case MyApp.Cache.get(key) do
      {:ok, value} when not is_nil(value) -> {:ok, value}
      _ -> :miss
    end
  end

  @impl true
  def put(key, value, opts) do
    ttl = Keyword.get(opts, :ttl, 604_800)
    MyApp.Cache.put(key, value, ttl: ttl)
  end
end