refactor(rdf): delegate canonicalization to the diffable-rdf library

[jdsika]

Delegate RDF canonicalization to diffable-rdf

Stacked on #25 (conformance evidence), which is stacked on #24 (--diff-stable). Review that order.

What this does

Deletes linkml_runtime/utils/rdf_canonicalize.py's implementation and calls diffable-rdf instead. canonicalize_rdf_graph keeps its signature; nothing that imports it changes. Net −196 lines.

This is the step linkml#3295 asked for. The module was extracted into a standalone library at @cmungall's request — "the implementation should live elsewhere... independent rdflib sidecar library?" and "This should be implemented somewhere upstream of linkml, after which we'll happily consider a PR" — but linkml kept its copy, and the two drifted. #25 measured the drift. This closes it.

Why now

#25 found ten correctness properties where the two copies disagree. Nine held only in the library. One held only in linkml — the library dropped @base on the degraded path — and that one was the blocker: adopting the library would have been a regression for rdflib_dumper.dumps(..., prefix_map={"@base": ...}), which the metamodel exercises.

That is fixed in diffable-rdf 0.4.0 (ASCS-eV/diffable-rdf#60), pinned by #24. With no gap running toward linkml, delegation is a pure improvement.

The fix is worth a sentence because the naive version is wrong. rdflib's relativize() is a string prefix strip, not RFC 3986 §5.2.2 component resolution, so carrying a base of http://ex.org/vocab# rewrites http://ex.org/vocab#Thing and every unrelated IRI that merely starts with those characters. Rejecting bases by shape does not work either — http://ex.org/a/b and http://ex.org/d?q=1 corrupt too. The library carries the base, re-parses, and keeps it only if every absolute IRI of the source survives. RFC 3986 specifies resolution and never relativization, so verification is the only sound test.

What linkml gains

Each was a strict xfail on the linkml side in #25 and is now unmarked:

	Property	Was
1	A base ending in # doesn't rewrite unrelated IRIs	silent corruption — parses, means something else
2	A shared rdf:List tail isn't duplicated	silent corruption — 9 triples in, 11 out
3	nt refuses a relative IRI	wrote a file its own parser rejects
4	U+2028/U+2029/U+0085/U+000B/U+000C/U+001C–1E in literals survive	str.splitlines() split on them mid-literal
5–7	Degraded RDF/XML, degraded Turtle, json-ld are byte-identical across processes	traversal-ordered; ns1/ns2 names moved
8	Exactly one trailing newline, every format	varied by serializer
9	A Dataset is refused, not flattened	Dataset is a Graph subclass, so named graphs were silently merged

Behaviour changes

Two, both deliberate:

• nt for a graph containing a relative IRI now raises ValueError. N-Triples 1.1 §2.2 permits only absolute IRIs. The old code emitted the file anyway, and rdflib's own parser rejected it. There is no valid document to produce, so refusing is the only honest answer. This is the one change that could break a caller, and it breaks them at write time instead of at read time.
• json-ld is canonicalized rather than handed to rdflib, so it no longer emits a fallback warning.

All four RDF generators (gen-owl, gen-rdf, gen-shacl, gen-shex) produce byte-identical output. 1736 generator tests and 1855 runtime tests pass unchanged.

The one piece of real code left

linkml reports degradation with warnings.warn so a schema author running gen-owl sees it without configuring logging first. The library uses logging, which is silent by default. A naive delegation loses the signal.

_DegradedPathWarnings bridges them, and four tests pin the properties that makes load-bearing:

• the warning is attributed to the caller's line, not to the adapter (this is why records are collected and re-emitted on exit rather than warned from emit — the distance from warnings.warn to the caller is otherwise eight logging frames plus a library depth that differs per message, so no fixed stacklevel works);
• the library's logger is left as it was found, including when the adapter had to raise its level to see anything;
• a caller who did configure logging still receives the record — the adapter adds a mechanism, it does not remove one;
• warnings survive an exception, so the degradation that preceded a failure still reaches you.

Review notes

• test_rdf_canonicalize_defects.py still parametrizes over both entry points with every case unmarked. That is the evidence this changed nothing it should not have, and it keeps a future re-fork from going unnoticed.
• Three tests in test_rdf_canonicalize.py changed target rather than assertion. Two monkeypatched rdf_canon_mod.ox, which was always really pyoxigraph — they now patch ox directly and no longer depend on module internals. The third asserted an unrelated ValueError propagates using "Invalid base IRI" as its example; the library correctly treats that as a base problem and recovers from it, so the example is now a genuinely unrelated error and the recovery got its own test.

References

Extraction request: linkml#3295. Determinism and diff-stability lineage: linkml#3702, linkml#3481, linkml#3212, linkml#696, linkml#3516, linkml#3721. Merged: linkml#3407, linkml#3696, linkml#3518, linkml#3524, linkml#3703.