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.<api>.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 puts 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.<name>(...args) — :request for execute runs, :describe for search runs. The apis.<name>.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.<api> global is {operations, describe}, not the dereferenced document. specs.<api>.operations is the slim index — an array of {id, method, path, summary, tags, params}, no schemas — and await specs.<api>.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.<api>.paths must iterate specs.<api>.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 $refs, 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.