An Orchid.Runner.Hook that transparently intercepts step execution and serves results from cache when possible.

How It Works

For every step in the workflow, the hook:

1. Checks cacheability — the step must have cache: true in its options, and both :meta_store and :blob_store must be present in the workflow baggage. If either condition is false the step is executed normally.

2. Derives a cache key — delegates to OrchidStratum.HashKeyBuilder.step_key/4.

3. Probes the Meta Store — if a MetaItem exists for the key and every referenced blob is still reachable in the Blob Store, the cached outputs are returned immediately (cache hit).

4. Executes the step on a miss — hydrates any {:ref, ...} inputs back to their raw payloads, calls the underlying step, then dehydrates the outputs (storing payloads in the Blob Store and replacing them with {:ref, blob_store, hash} tuples) and persists a new MetaItem.

Enabling the Hook

The hook is registered as a global hook in Orchid options:

opts = [
  baggage: %{
    meta_store: {MyMetaAdapter, meta_ref},
    blob_store: {MyBlobAdapter, blob_ref}
  },
  global_hooks_stack: [OrchidStratum.BypassHook]
]

Or use OrchidStratum.apply_cache/4 to have this wired automatically.

Per-Step Control

Dehydration Contract

Dehydrated outputs carry payloads of the form {:ref, blob_store, hash}. The blob_store component is the exact store configuration tuple {Module, store_ref} so that the hook can route blob lookups to the correct adapter instance, even in multi-session or multi-tenant scenarios.

Blob integrity is verified with BlobStorage.exists?/2 before every cache hit, ensuring the hook is safe against store eviction or external deletion.