fix: buffered graph encoder byte-matches reference; run graph-encode fixtures

Python's buffered graph encoder diverged from the reference on two axes, hidden
because its conformance runner skipped all graph-encode fixtures:
- symbols were emitted in input order, not sorted by distance then descending
  score (IDs are now assigned in output order);
- the header always emitted budget=/tokens=/edges= even when zero.
Both fixed to match Go/rust/ts/swift/kotlin. The conformance runner now builds a
graph Payload and byte-compares graph-encode 001/002/003 (previously skipped),
so this class of divergence is now caught. Full suite green.

Author: blackwell-systems

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Fixes
 
+- 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`).
 - Decoder: reject an orphan positional inline body (a pipe-delimited line with no eligible `^{}` attachment-marker cell) instead of silently dropping it. The object-body parser previously skipped any unrecognized line, so a stray positional body (e.g. a second `Bob|b@t.com` after a row's one inline cell was filled) vanished with no error (silent data loss); now rejected per SPEC 16.5 (`orphan_inline_attachment`).

src/gcf/encode.py

@@ -17,25 +17,37 @@ def encode(p: Payload) -> str:
     """
     parts: list[str] = []
 
-    # Build symbol index for edge references.
+    # Group symbols by distance (sorted by score descending within each group),
+    # then assign local IDs in output order so they are sequential in the wire
+    # (SPEC 16.1).
+    groups = _group_by_distance(p.symbols)
     sym_index: dict[str, int] = {}
-    for i, s in enumerate(p.symbols):
-        sym_index[s.qualified_name] = i
+    next_id = 0
+    for _distance, g_symbols in groups:
+        for s in g_symbols:
+            sym_index[s.qualified_name] = next_id
+            next_id += 1
 
     # Count valid edges (both endpoints in symbol index).
     valid_edges = sum(
         1 for e in p.edges
         if e.source in sym_index and e.target in sym_index
     )
 
-    # Header line.
-    header = f"GCF profile=graph tool={p.tool} budget={p.token_budget} tokens={p.tokens_used} symbols={len(p.symbols)} edges={valid_edges}"
+    # Header line (SPEC 16.1): omit budget/tokens/edges when zero, matching the
+    # reference encoder.
+    header = f"GCF profile=graph tool={p.tool}"
+    if p.token_budget > 0:
+        header += f" budget={p.token_budget}"
+    if p.tokens_used > 0:
+        header += f" tokens={p.tokens_used}"
+    header += f" symbols={len(p.symbols)}"
+    if valid_edges > 0:
+        header += f" edges={valid_edges}"
     if p.pack_root:
         header += f" pack_root={p.pack_root}"
     parts.append(header)
 
-    # Group symbols by distance.
-    groups = _group_by_distance(p.symbols)
     group_names = ["targets", "related", "extended"]
 
     for g_distance, g_symbols in groups:
@@ -79,15 +91,17 @@ def encode(p: Payload) -> str:
 
 
 def _group_by_distance(symbols: list[Symbol]) -> list[tuple[int, list[Symbol]]]:
-    """Group symbols by distance, preserving order."""
+    """Group symbols by distance ascending, sorted by score descending within each
+    group (stable), matching the reference encoder so IDs are assigned canonically."""
     if not symbols:
         return []
 
+    ordered = sorted(symbols, key=lambda s: (s.distance, -s.score))
     groups: list[tuple[int, list[Symbol]]] = []
     current_distance: int | None = None
     current_symbols: list[Symbol] = []
 
-    for s in symbols:
+    for s in ordered:
         if current_distance is None or current_distance != s.distance:
             if current_symbols:
                 groups.append((current_distance, current_symbols))  # type: ignore[arg-type]

tests/test_conformance_v2.py

@@ -95,7 +95,37 @@ def test_conformance(rel_path, data):
     if op == "encode":
         expected = data["expected"]
         if expected.startswith("GCF profile=graph"):
-            pytest.skip("graph encode test")
+            # Buffered graph encode (distinct from generic encode and the streaming
+            # encoder). Build a graph Payload from the fixture and byte-compare.
+            from gcf.encode import encode as encode_graph
+            from gcf.types import Edge, Payload, Symbol
+
+            inp = data["input"]
+            payload = Payload(
+                tool=inp.get("tool", ""),
+                token_budget=inp.get("tokenBudget", 0),
+                tokens_used=inp.get("tokensUsed", 0),
+                pack_root=inp.get("packRoot", ""),
+                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 = encode_graph(payload)
+            assert got == expected, (
+                f"graph encode mismatch:\n  got: {got!r}\n  exp: {expected!r}"
+            )
+            return
         got = encode_generic(data["input"])
         # v3 encoder produces different byte output for attachment/array fixtures.
         v3_affected = any(rel_path.startswith(d) for d in ("attachments/", "arrays/"))