RDFC-1.0 canonical graph digest — pgrdf.graph_digest(graph): graph identity that survives reload

[styk-tv]

Why

A sha256 over exported N-Triples is a digest of one stored copy, not of the graph. Blank
nodes are existential variables — their labels are minted per parse — so loading the same file
twice produces different bytes for identical structure, forever. SHACL makes this the common
case, not an edge case: every sh:property constraint hangs off a blank node.

Measured on a 948-triple SHACL ontology: 531 of 948 triples involve a blank node (130
distinct). Two independently-loaded copies of the same file differed by 6 bytes — entirely
blank-node label-length variance — while being structurally identical. Any downstream scheme
that pins graph identity to a byte digest reports false divergence on every reload.

Client-side approximations exist (first-degree blank-node neighbourhood signatures). Their
verdict is asymmetric by construction: unequal digests prove difference, equal digests are
only evidence of isomorphism — symmetric blank-node structures can collide. Only canonical
relabelling closes that gap, and the engine is the right seat for it.

What

pgrdf.graph_digest(graph_id bigint) -> text — the sha256 of the graph's asserted triples
after RDF Dataset Canonicalization (RDFC-1.0 / URDNA2015) canonical blank-node relabelling,
serialized as sorted canonical N-Triples.

• Asserted-only by default; an include_inferred variant may follow.
• Optionally expose the canonical serialization itself (pairs with pgrdf.export_graph / import_graph — native portable dump+restore (proven at 120M) #36 export_graph).
• Document the complexity honestly: RDFC-1.0 is worst-case exponential on adversarial
  blank-node automorphism structures; real ontologies are far from that. A guard (node-count /
  recursion budget) that raises rather than degrades keeps the fail-closed direction.

Acceptance

• Reload test: load the same source file into two fresh graphs → graph_digest equal, byte
  digests of the two exports unequal.
• Negative control: two genuinely different graphs → unequal digests.
• Regression: digest stable across dump/restore round-trip.

Non-goals

Does not replace byte digests — those remain correct for copy verification (expect_sha256
import guards). This adds the identity plane a byte digest cannot express.

Related: #36 (native export), and the companion issue on load-time source-byte digests.

[styk-tv]

Second consumer registered while the design is fresh: severance / re-composition.

When a graph set is exported from one store and germinated in another, blank-node labels re-mint, so byte digests make every severed cross-graph edge unmatchable forever (the F1-class relabelling measured in this issue's body). Structural equality across stores is exactly what re-binding a severed edge must prove: an exported kernel's declared dependencies carry pins, and reconnection in a new substrate happens by matching what one side offers against what the other's unbound edges require.

Until this lands, cross-store re-match verdicts are evidence-grade (first-degree signatures — sound for DIFFERENT, only likely for equal), so any re-binding protocol needs an explicit agreement step on top. With RDFC-1.0 the match becomes proof.

This raises the weight of the acceptance test already in the body — same file, two graphs → equal canonical digests, unequal byte digests — from correctness check to the load-bearing property of the whole re-composition path.

[styk-tv]

Shipped in v0.6.32 (PR #126, merge c20c555) — tag pushed, chain running.

What landed: pgrdf.graph_digest(graph_id) -> text — full RDFC-1.0 in-engine over our own quad rows: first-degree hashing, related-hash, the complete hash-n-degree gossip-path tie-breaker with temporary issuers and lexicographic early-abort, canonical issuance, sorted canonical N-Triples, sha256. Algorithm label rdfc-1.0-sha256. Asserted triples only.

The finding worth more than the feature: conformance was proven at the strictest grade available — our digest equals sha256 of the W3C suite's own expected canonical documents, byte-for-byte, on the first run (ten vendored cases, dual-license attribution in tests/fixtures/rdfc10/LICENSE.md). And the poison graph (test074, a NegativeEvalTest) hits our resource budgets and raises pgRDF#117 — which is precisely conforming: the spec expects implementations to refuse adversarial automorphic structures under resource limits. The fail-closed doctrine and W3C conformance turned out to be the same requirement.

Education: a byte digest identifies a stored copy; this digest identifies meaning. Isomorphic graphs — same structure, any blank-node labels — produce equal values; unequal values prove difference. Downstream consumers pinning adoptions or re-matching severed dependencies across stores upgrade from evidence-grade (first-degree, collision-possible) to proof-grade the moment they cite this digest — with the standing rule that a pin without its algorithm label is a future mystery.

Deferred: batch/streaming digest of multiple graphs (compute is per-graph, on demand); skolemization as an alternative identity strategy was considered and not pursued — canonical relabelling keeps the store untouched.