@callback components(handle(), ref(), [component_key()]) ::
  result(%{required(component_key()) => json()})

Bulk component fetch: one call per breadth-first level of a resolve.

Names the store does not hold are simply absent from the map — a dangling $ref is the resolver's $unresolved marker, not an error.

@callback index(handle(), ref()) :: result([OapiCodemode.SpecStore.OperationSummary.t()])

The slim search index: every operation, no schemas.

In document order — the order %Decomposed{} carries its operations in, which OapiCodemode.Ingest derives from the document itself (paths in lexical order, methods in a fixed order within a path). A store persists that order and hands it back; it does not impose one of its own. Search results and search_apis listings are read in it, so an implementation that returns rows in whatever order the storage engine felt like — a SELECT with no ORDER BY — is not conformant.

@callback meta(handle(), ref()) :: result(OapiCodemode.SpecStore.Meta.t())

What the registry reads once, at registration.

@callback operation(handle(), ref(), op_id :: String.t()) ::
  result(OapiCodemode.Operation.t())

One operation, payload $refs preserved exactly as the document wrote them.

@callback pointer(
  handle(),
  ref(),
  pointer :: String.t(),
  max_bytes :: non_neg_integer() | :infinity
) :: result(json())

Any same-document "#/..." pointer, served from the canonical document.

The slow path, for refs that are not stored components. The returned term is bounded: a target whose encoded size exceeds max_bytes comes back {:error, :too_large}, which the resolver turns into $truncated. :infinity asks for the target whatever its size — an unbounded resolve names no ceiling of its own rather than invent one.

The measure is Jason-encoded bytes, the same measure OapiCodemode.Ingest caps a stored node by and OapiCodemode.Resolve charges a budget in, so a resolve's arithmetic and a store's refusals agree. A store may be stricter — refuse a target this measure would have allowed, because its own encoding is fatter or because it bounds the read before allocating — but never more lenient: a caller's budget is the one number keeping a 20 MB schema out of a sandbox, and a store that stretches it silently breaks that promise.

@callback put(handle(), OapiCodemode.Decomposed.t()) :: {:ok, ref()} | {:error, term()}

Persists a decomposed document and returns the ref for its projection.

Content-addressed and idempotent: %Decomposed{} carries the canonical bytes and their hash, so putting a document a store already holds returns the existing ref. A %Decomposed{} whose decomposer_version the store has no projection for is stored alongside the versions it has — refs handed out earlier keep reading what they always read.