feat: implement graph-profile PackRoot (gcf-pack-root-v1, SPEC 10.2)

Adds the graph content-addressing primitive (content-addressed sha256 over
canonical, independently-sorted S/E records with abbreviated kinds and
shortest-decimal scores), mirroring the Go reference byte-for-byte. The
conformance runner now exercises the shared graph-pack-root fixtures, which it
had been skipping - so this primitive was previously unimplemented and untested.
Verified: canonical bytes match the fixtures' canonicalBytes exactly and the
sha256 matches expected on all four fixtures, byte-identical across all six SDKs.

Author: blackwell-systems

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Fixes
 
+- Added the graph-profile PackRoot (`pack_root(symbols, edges)`, gcf-pack-root-v1, SPEC 10.2): the content-addressed sha256 over canonical, independently-sorted symbol/edge records, byte-identical to gcf-go/rust/typescript/swift/kotlin. The conformance runner now exercises the shared `graph-pack-root` fixtures, which it had been skipping (so this primitive was previously unimplemented and untested).
 - Buffered graph encoder now matches the reference byte-for-byte: symbols are ordered by distance then descending score with local IDs assigned in output order, and the header omits `budget`/`tokens`/`edges` when zero (previously symbols kept input order and zero-valued header fields were always emitted). The conformance runner now exercises the shared `graph-encode` fixtures (001-003), which it had been skipping - which is how this divergence went uncaught.
 - Buffered graph encoder: order edges by source ID, then target ID, then edge type (SPEC 16.1), instead of emitting them in input order. Decode-invariant (edges are a set) and does not affect `pack_root` (which sorts edge records independently), so no content addresses change. Pinned by shared fixture `graph-encode/003`. Streaming edges remain in producer-arrival order.
 - Decoder: reject an orphan `.field` attachment (a `.field` whose name is neither a `^`-marked column of its row nor a `>`-containing field name, SPEC 7.4.6.1.4) instead of silently absorbing it as an undeclared extra field. Such a stray attachment previously decoded to a record no encoder produces, silently injecting a field onto the last-parsed row (a lossless round-trip hole); now rejected per SPEC 16.5 (`orphan_attachment`).

src/gcf/__init__.py

@@ -56,6 +56,7 @@
     size_guard,
     DEFAULT_REANCHOR_N,
 )
+from .packroot import pack_root
 from .session import Session, encode_with_session
 from .decode_generic import decode_generic
 from .stream import StreamEncoder
@@ -84,6 +85,7 @@
     "GenericSet",
     "GenericDeltaPayload",
     "generic_pack_root",
+    "pack_root",
     "diff_generic_sets",
     "encode_generic_full",
     "encode_generic_delta",

src/gcf/packroot.py

@@ -0,0 +1,53 @@
+"""GCF graph-profile pack root (gcf-pack-root-v1, SPEC Section 10.2).
+
+Computes the canonical pack root hash for a graph snapshot (symbols + edges).
+Mirrors the gcf-go reference implementation (packroot.go); the shared conformance
+fixtures (graph-pack-root/) hold both to identical bytes and hashes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from .constants import KIND_ABBREV
+from .scalar import format_number
+from .types import Edge, Symbol
+
+
+def pack_root(symbols: list[Symbol], edges: list[Edge]) -> str:
+    """Canonical pack root for a graph snapshot (gcf-pack-root-v1, graph profile, 10.2).
+
+    Symbol and edge records are sorted independently by unsigned UTF-8 byte order,
+    then concatenated (all symbols, then all edges) and hashed with SHA-256. Two
+    implementations given the same logical graph MUST produce the same result.
+    """
+    # Build canonical symbol records.
+    sym_records: list[str] = []
+    for s in symbols:
+        kind = KIND_ABBREV.get(s.kind, s.kind)
+        score = format_number(float(s.score))
+        sym_records.append(
+            f"S\t{kind}\t{s.qualified_name}\t{score}\t{s.provenance}\t{s.distance}\n"
+        )
+
+    # Map qualified_name -> kind abbreviation for edge endpoint resolution.
+    sym_kind_map: dict[str, str] = {}
+    for s in symbols:
+        sym_kind_map[s.qualified_name] = KIND_ABBREV.get(s.kind, s.kind)
+
+    # Build canonical edge records.
+    edge_records: list[str] = []
+    for e in edges:
+        src_kind = sym_kind_map.get(e.source, "")
+        tgt_kind = sym_kind_map.get(e.target, "")
+        edge_records.append(
+            f"E\t{src_kind}\t{e.source}\t{tgt_kind}\t{e.target}\t{e.edge_type}\n"
+        )
+
+    # Sort independently by unsigned UTF-8 byte order.
+    sym_records.sort(key=lambda r: r.encode("utf-8"))
+    edge_records.sort(key=lambda r: r.encode("utf-8"))
+
+    canonical = "".join(sym_records) + "".join(edge_records)
+    digest = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+    return "sha256:" + digest

tests/test_conformance_v2.py

@@ -285,5 +285,29 @@ def _set(s):
             f"stream encode mismatch:\n  got: {got!r}\n  exp: {data['expected']!r}"
         )
 
+    elif op == "pack-root":
+        from gcf.packroot import pack_root
+        from gcf.types import Edge, Symbol
+
+        inp = data["input"]
+        symbols = [
+            Symbol(
+                qualified_name=s["qualifiedName"],
+                kind=s["kind"],
+                score=s["score"],
+                provenance=s["provenance"],
+                distance=s.get("distance", 0),
+            )
+            for s in inp.get("symbols", [])
+        ]
+        edges = [
+            Edge(source=e["source"], target=e["target"], edge_type=e["edgeType"])
+            for e in inp.get("edges", [])
+        ]
+        got = pack_root(symbols, edges)
+        assert got == data["expected"], (
+            f"graph pack-root mismatch:\n  got: {got}\n  exp: {data['expected']}"
+        )
+
     else:
         pytest.skip(f"unknown operation: {op}")