Use referencing for resolve.py's URI and retrieval layer

[LukasOro]

src/oold/validation/resolve.py is about 500 lines covering document loading, $ref dereferencing and schema bounding. referencing is already a dependency and is already used for the meta-schema registry in src/oold/validation/meta_store.py, so part of this is hand-rolled where a library the project already ships would do.

What the module does, and what referencing covers

Responsibility	Covered by referencing
Normalise dict / Path / str / JSON text / URL to a base URI	yes, largely
Remote fetch with disk cache and offline=True	no
dereference() producing a materialised graph with shared and circular refs	no, resolution is lazy during validation
bound_schema() cutting that graph into a finite tree	no

The last two are why the module exists in this form: instance generation and round-trip need a concrete finite document, not lazy lookup at validation time.

Work

• Move the URI normalisation and retrieval layer onto referencing, keeping Resolver's cache and offline behaviour as the retrieve hook
• Leave dereference() and bound_schema() in place unless a replacement provides the same graph semantics
• Measure the reduction; if it is small, close this and record why

Constraint

$ref resolution feeds every check, so all parity verdicts must be re-checked: OOLD_SCHEMA_DIR=../oold-schema uv run pytest -m parity. Cut markers from bound_schema() are observable in generated instances, so the round-trip fixtures are also a gate.

Raised from review of #114 (comment).

[simontaurus]

Agreed on deferring, and the split looks right: referencing covers URI normalisation and retrieval, not dereference()'s materialised graph or bound_schema()'s finite cut.

Worth recording why the second half is not a gap in referencing but a different job. referencing resolves lazily, on demand, during validation - which is the correct model for validating. Generation and round-trip need the opposite: one concrete, finite document, with shared and circular refs already materialised, because a faker cannot follow a lazy pointer and a round-trip has to compare two whole documents.

So the realistic outcome is referencing underneath for load and resolve, with the graph and bounding layer kept on top, rather than the module disappearing. Sizing that honestly needs a prototype - the estimate in the description is not measured.

Worth doing after #118, since both touch the resolver and #118 has a clear answer already.

[LukasOro]

Agreed, and the framing is better than mine. "Lazy on demand is the correct model for validating; generation and round-trip need the opposite" states the reason the second half is a different job rather than a gap, which the table in the description only implied.

Conceded on the estimate: the ~500 lines and the four-row split in the description are read off the code, not measured against a prototype. Nothing in the issue should be taken as a size claim until someone has actually put referencing underneath and looked at what is left.

Order recorded: #120, then #118, then this. Both this and 118 touch the resolver, and 118 now has a settled answer while this one does not, so doing them the other way round would mean rebasing a prototype onto a rewritten module.

One thing to add to the acceptance criteria while it is fresh: #128. There is currently no fixture that makes Resolver fetch anything over HTTP - 25 same-directory references in the corpus, 6 cross-directory, zero remote - so the retrieval layer this issue moves onto referencing has no test covering it. That should be fixed before the swap, not after, or the swap is unverifiable.

[LukasGold]

Measured. The reduction is small, so closing on this issue's own instruction: "Measure the reduction; if it is small, close this and record why."

What holds

referencing is a dependency, listed four times in pyproject.toml, and meta_store.py already uses it: it imports Registry and Resource and builds a registry with a retrieve hook at meta_store.py:316.

Three of the four rows in the table above are correct, and they are the load-bearing ones:

• the disk cache and offline=True are not in referencing
• dereference() materialises a complete graph, while referencing resolves each $ref only at the point of use
• bound_schema() cuts that graph into a finite tree, which referencing does not do

Instance generation and round-trip need a concrete finite document, so lazy resolution cannot serve them. That is the correct reading and it is why the module exists in this shape.

What does not hold

The first row says referencing covers URI normalisation "yes, largely". It does not.

load() dispatches on the kind of input: a dict, a Path, raw JSON text, or a URL, each producing a ResolvedSchema with the right base URI. referencing has no equivalent, because it begins after you already hold the contents.

uri_to_path() converts a file:// URI back to a local path, using Path.from_uri on Python 3.13 and a hand-written fallback on 3.10 to 3.12, where nturl2path is deprecated exactly in the range the fallback still runs. referencing does not do this either.

So the row that promised the reduction is the one that was wrong.

The measurement

What referencing can genuinely take over:

Function	Lines
resolve_ref()	25
apply_json_pointer()	20

About 45 lines of 536, so roughly 8 percent, and both are thin wrappers over urljoin and pointer traversal rather than anything subtle.

The file also grew, in the half that cannot move

The description says "about 500 lines". It is 536 now. #143 added http_get_json_if_changed and its conditional-request handling, about 63 lines, all of it in the retrieval layer that referencing does not cover. The replaceable slice did not grow; the rest did.

Prerequisite, for the record

#128 was a hard prerequisite for this issue and is now done (#139): Resolver's fetch, disk cache and offline refusal finally have tests that exercise them. That removes the reason this could not be attempted, and it does not change the answer. It does mean a future attempt would at least be verifiable.

Closing

Not because it is wrong to want this, but because the measurement says the trade is bad: about 45 lines removed, a new indirection through a registry in the one module where every check's $ref resolution passes, and dereference() and bound_schema() staying regardless.

Reopen with a prototype if the measurement looks wrong. That is the evidence this needs, and it is what the issue asked for.