# Changelog ## 0.5.0 — 2026-08-30 Specs are now stored decomposed and read lazily. Ingest no longer dereferences a whole document into one artifact the registry holds: it takes the document apart — canonical evidence, one row per operation, one per component, every payload `$ref` left where the document wrote it — and a registration binds the `{store, ref}` those pieces live at, reading one operation's refs per call. The same change reaches the sandbox: instead of a dereferenced document spliced into a search run, `search_apis` ships a slim operation index (id, method, path, summary, tags, parameter names) and the model calls `specs..describe(id | [ids])` for the schemas of the few operations it picked — a metered host round trip into the store. A large spec therefore costs a run its index rather than its document, and a host that keeps specs in a database of its own implements one behaviour instead of caching artifacts. ### Added - `OapiCodemode.SpecStore`: the behaviour between the library and wherever specs actually live. A `store` is `{module, handle}`, a `ref` is `{spec_id, decomposer_version}` naming one projection of one document, and the six callbacks are `put/2`, `meta/2`, `index/2`, `operation/3`, `components/3` (bulk, one call per breadth-first level of a resolve) and `pointer/4` (the slow path, byte-bounded). Module-level functions mirror the callbacks so callers hold a store instead of unpacking tuples. `%SpecStore.Meta{}` is what a registration reads once; `%SpecStore.OperationSummary{}` is one slim-index entry. - `OapiCodemode.SpecStore.ETS`: the implementation the library ships with — one `:set` table, `new/0` for the handle, rows gated on a `{:meta, ref}` commit marker written last so a projection mid-write is invisible rather than half-visible, and `delete_projection/2` to free one. - `OapiCodemode.SpecStoreCase`: the conformance suite, shipped in `lib/` so a host's own store is held to the same contract — `use OapiCodemode.SpecStoreCase` and supply `store_fixture/0`. It covers the `decompose → put → meta/index/operation/components` round trip, `put` of a known hash, two decomposer versions coexisting, concurrent `put`, `pointer/4`'s byte budget and array walk, absent component names, `:not_found` for an unknown ref or id, and index order. - `OapiCodemode.Resolve`: read-time `$ref` resolution — one stored operation row plus the store in, one usable operation out. A breadth-first *fetch* pass (a whole layer of refs per `components/3` call) followed by a depth-first *substitute* pass, so output is byte-identical to the whole-document expansion 0.4.0 shipped; `for: :request` resolves parameters and the request body, `for: :describe` also responses; `max_bytes:` bounds the resolved closure. Unfollowable refs stay readable as data: `%{"$circular" => name}`, `%{"$unresolved" => ref}`, and now `%{"$truncated" => true}` for a subtree that did not fit the budget. - `OapiCodemode.Pointer`: same-document JSON pointer resolution in one place (`Ingest`, `Deref` and a store's `pointer/4` all need the same answer), with `escape/1` and `unescape/1`. `resolve/3` takes `arrays: true` to walk numeric array-index tokens per RFC 6901 — off by default, so every existing caller keeps the maps-only 0.4.0 walk. - `OapiCodemode.Ingest.decompose/1` and `%OapiCodemode.Decomposed{}`: take a document apart into canonical evidence, the document's own fields, this decomposer's projection, one entry per operation and one per component, inlining nothing. Read-time resolution is the caller's job. - `OapiCodemode.Ingest.decomposer_version/0` and `OapiCodemode.Ingest.component_kinds/0`: the version a projection is stored under, and the component kinds a store therefore holds (everything standard except `examples`). - `OapiCodemode.Ingest.index_entry/1`: the single definition of a slim-index entry. The projection's `index_bytes` is the encoded size of exactly these entries, so an index builder must go through it rather than rebuild the shape. - `OapiCodemode.Ingest.Normalize.extract_body/1` and `parse_segments/1` are now public. The first means read-time resolution of a `$ref`'d `requestBody` reaches the same `%{"required", "content_type", "schema"}` shape as an inline body by construction; the second lets an `%OperationSummary{}` derive its match segments without persisting a second spelling of `path`. - `OapiCodemode.Registry.private_store/1`: the library-private `SpecStore.ETS` store `ingest_and_register/4` puts into, owned by the registry process. Exposed so a host can see what the convenience path did; see the warning under Changed before holding a ref into it. - `OapiCodemode.Registry.collect_unreferenced/2`: frees a projection in that private store which no live binding names. `ingest_and_register/4` calls it on the one path that can strand one — the `put` landed and `register/4` then refused (a name that is not a JS identifier, an index too large, a bad idempotency header) — so a refusal leaves the store exactly as it found it. - `OapiCodemode.Proxy.Matcher.nearest_ids/2`: the five operation ids nearest a given one by Jaro distance, so `describe` can name the near miss an unknown id usually is (the same self-correction the matcher already offers a request that matches no route). - `OapiCodemode.Tools.describe_limits/0`: the budgets a search run's `describe` is held to — 10 ids per call, 512 KB of resolved JSON per run. Public so the tool description states the numbers the callback enforces rather than a second copy of them. - `ApiConfig.max_resolve_bytes` (default `5_000_000`): a cap on the spec bytes one request may resolve. Sibling of `max_response_bytes`, which bounds what comes back from the API; this bounds what comes back from the spec store. Each stored row is capped at 1 MB, but a request resolves an operation's whole transitive `$ref` closure and nothing else capped that aggregate. Over-budget subtrees arrive as `{"$truncated": true}`, which validation reads as "no schema here" and lets through — a guardrail against a pathological spec, not a reason to refuse the model's request. - A `:resolve` phase for `[:oapi_codemode, :request, :error]` telemetry: the spec store failing to hand back an operation the index lists, or handing back one that disagrees with it. Our storage, not the model's request, so the message crossing back to the sandbox is fixed and the store's own reason goes to `Logger`. ### Changed - **Breaking: `OapiCodemode.register/4` binds a store, not an artifact.** It takes `{store, ref}` — a `OapiCodemode.SpecStore` module/handle pair and the `{spec_id, decomposer_version}` a `put/2` returned — and the registry holds that binding plus the runtime `ApiConfig` and a small cache (the slim index, pre-encoded for the sandbox, plus title, tags and security schemes). No spec bytes live in the registry, with one exception: `ingest_and_register/4` puts into the library-private ETS store the registry process owns, and those bytes are a store's, not a registration's — re-registering an api name through it frees the projection that name superseded. Registration reads the store exactly twice (`meta/2`, `index/2`) and refuses, rather than degrading, when: neither the config nor the document names a base URL (`:no_base_url`), the slim index exceeds 8 MB (`:index_too_large`), the ref names a `decomposer_version` this library did not derive (`{:unknown_decomposer_version, version}`), or the store's `index/2` does not encode to the `index_bytes` its `meta/2` reported (`{:index_bytes_mismatch, spliced, reported}`). - **Breaking: `OapiCodemode.ingest/1` returns `%OapiCodemode.Decomposed{}`.** It delegates to `Ingest.decompose/1`. `ingest_and_register/4` is unchanged from the outside: it decomposes and `put`s into the library-private ETS store, then registers the resulting binding. - **Breaking: the executor callback contract is named host callbacks.** `env.callbacks` is a map of name to an **arity-1** function over the JSON-decoded argument list (`fn [api_name, opts] -> ... end`, was `fn api_name, opts -> ... end`), and an executor exposes each one to the guest as `host.(...args)` — `:request` for execute runs, `:describe` for search runs. The `apis..request(opts)` sugar the model is taught is unchanged; it now forwards through `host.request`. A custom executor must build the `host` object and switch its callback invocation to the list form; a host testing with `Executor.Mock` calls `env.callbacks.request.([name, opts])`. - **Breaking: `search_apis`'s `specs.` global is `{operations, describe}`, not the dereferenced document.** `specs..operations` is the slim index — an array of `{id, method, path, summary, tags, params}`, no schemas — and `await specs..describe(id | [ids])` resolves the operations the model picked in full (parameter schemas, request body, responses, security), reading the spec store per call rather than shipping a document into the sandbox. Sandbox code that walked `specs..paths` must iterate `specs..operations` instead. `describe` is metered: at most 10 ids per call, one call charged per id against `:max_calls`, and 512 KB of resolved JSON per search run, after which it answers `{id, error: "describe budget exhausted"}`. Refusals — an unknown id (which names the nearest ids), a batch too big, a spent budget, an API outside the call's `:api_allowlist` — are data in the result, never raised errors, and an array of ids always answers an array of the same length in the same order, one entry per id: a batch over the cap refuses per id rather than handing back a bare error object a `.map()` would trip over. The numbers are `OapiCodemode.Tools.describe_limits/0`, which the tool description reads so it states what the callback enforces (the worked example included, which slices its batch to the cap). Metering comes first: a run that has spent its calls or its bytes refuses further describes before touching the registry, so a loop of them costs no lookups. - `Operation` gained `description`, `responses`, `deprecated` and `param_index`. `request_body` is now a union: either a `$ref` map kept verbatim for lazy resolution, or the extracted media-type shape. - `param_index` is filtered where the row is built, not where the index is projected: a parameter whose identity could not be resolved — a dangling `$ref`, a chain past the hop limit — has no entry, so `param_index` is exactly what the slim index publishes and `Ingest.index_entry/1` is a pure projection of the operation row. A store persists `param_index` and hands it back; it decides nothing about it. It is therefore no longer positionally aligned with `parameters`, which still carries every `$ref` verbatim. `OapiCodemode.SpecStoreCase` pins both ends. - **Behaviour change on malformed input.** Decomposition applies `Normalize`'s scalar coercions throughout, which slightly changes what ingesting does with a document that lies about its types: a non-string `operationId` is treated as absent (the id is derived instead of being carried through), a non-string `summary` or `description` becomes `nil` rather than the raw value, non-string elements of `tags` are dropped, and a non-list `security` is coerced rather than passed along. Well-formed documents are unaffected. - The proxy's per-request store read is bounded, ordered and cross-checked. Both policy checks now run *before* the read — the read-only refusal needs only the method, which the index entry carries, so a request this tool may not make costs zero store reads — the resolved closure is bounded by `max_resolve_bytes`, and the resolved operation's `path` is checked against the index entry's. The matcher bound path params against the index template, so a store that disagreed would have those bindings substituted into a different one: a credentialed request to a URL the model never named. That is a `:resolve`-phase error, with the disagreement logged. - The proxy passes `Resolve`'s plain atom-keyed map downstream rather than `struct!`-ing it into an `%Operation{}`: a stored operation holds `$ref`s, a resolved one holds markers and, under `for: :request`, no `responses` key at all, where the struct would have defaulted it to `nil` and made "we did not look" indistinguishable from "the document declared none". `Proxy.Validator` and `Proxy.Matcher` take either shape. - `OapiCodemode.Registry.private_store/1`'s handle is documented as collectible. The registry frees projections in that store which no live binding names, so a ref held where the registry cannot see it — `put` directly and kept, registered into a *second* registry, held across a re-registration of the name it was bound to — can start answering `{:error, :not_found}`. A stale read, never a wrong one. Hosts that want a retention policy of their own make their own `SpecStore.ETS`. - `OapiCodemode.SpecStore.OperationSummary` carries `segments`, derived from `path` (it is not part of the JSON entry), so the proxy can match against the registry's cached index and resolve only the one operation it is about to send. ### Removed - **Breaking: `OapiCodemode.Artifact` and the whole-document `ingest/1` pipeline.** Nothing dereferences a whole document at ingest any more: decomposition stores the pieces and `OapiCodemode.Resolve` follows the refs of the one operation being read. `OapiCodemode.Ingest.Deref` survives as the parity oracle the resolve suite checks lazy resolution against — tests only, not library code.