gcf-python 2.3.0__tar.gz → 2.4.0__tar.gz

{gcf_python-2.3.0 → gcf_python-2.4.0}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## v2.4.0 (2026-07-12)
+
+### Fixes
+
+- The conformance runner now hard-fails on any unhandled operation (instead of silently skipping it) and exercises session, delta, roundtrip, and pack-root fixtures end to end; the graph delta wire decode and verify path is now covered, so no operations remain allow-listed.
+- Implemented the graph delta wire decoder and verifier (`decode_delta` / `verify_delta`): parse a `GCF profile=graph delta=true` wire back into removed/added symbols and edge changes, apply them atomically to a base snapshot, recompute `pack_root`, and reject a wrong `new_root` with `root_mismatch` (SPEC 10.4). The `## added` encoder now emits the trailing `distance` field (SPEC 3.4.1, Section 10.1). The shared `graph-delta` fixtures now run end to end: 001 (encode, gains the trailing distance), 002 (verified apply), 003 (`root_mismatch` rejection).
+- **Session encoding correctness fix.** `encode_with_session` assigned per-response local IDs instead of stable session-global IDs, so the cross-call dedup references (`@N  # previously transmitted`) pointed at the wrong symbols, and the header emitted zero-valued `budget`/`tokens`/`edges`. Both are fixed to match the reference; graph session output is now byte-identical across all six SDKs. This had gone undetected because the conformance runner skipped the shared graph-session fixtures (now wired).
+- 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`).
+- 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`).
+- Graph streaming trailer: the edge count is now always the last `counts` entry, even when the stream has no edges (positional `counts=2,1,0`; labeled `counts=…,edges:0`). A zero-edge stream previously dropped it, violating the SPEC §8.4 / §8.4.1 rule that the edge count is always present and last (the invariant that keeps the positional form unambiguous). The graph trailer is decoder-ignored, so this changes producer output only.
+
+### Streaming: opt-in labeled trailer counts (SPEC §8.4.1)
+
+- New `labeled_trailer_counts` keyword on `StreamEncoder`. When set, the `##! summary` graph streaming trailer emits `counts=` in the labeled form `label:count` per group (e.g. `counts=targets:2,related:1,edges:3`) instead of the default positional values-only form (`counts=2,1,3`). Default false is byte-identical to prior output.
+- Opt-in and non-breaking: a producer-side comprehension aid for known weak consumers. The trailer counts remain informational (decoder-ignored) in both forms; neither changes the decoded payload. Mirrors the `gcf-go` reference.
+
+### Conformance and docs
+
+- Streaming graph trailer now emits `distance_N` group counts in pure group-header emission order (dropping a fixed `targets,related,extended` prefix), matching the other SDKs and deterministic per SPEC 16.1. Byte-identical for contract-conformant (ascending-distance) input; pinned by shared fixtures `streaming-v2/010`–`011`.
+- The conformance runner now executes the `graph-stream-encode` fixtures (streaming-encode parity, previously decode-only): fixture 004 (positional trailer) and 005 (labeled trailer).
+- README: corrected the streaming example trailer from the defunct `## _summary … sections=` to the real `##! summary … counts=`; README now leads with the project diagram.
+- Added a generic-delta fuzz test (decoder never crashes; string round-trip).
+
 ## v2.3.0 (2026-07-12)
 
 ### Generic-profile delta encoding (SPEC §10a)
@@ -18,6 +44,7 @@
 - Unit suite mirroring `gcf-go`: self-proving round-trip (diff -> encode -> apply -> recomputed root), determinism / row-order invariance, no-type-collision canonicalization, every invariant/error path, full-payload wire round-trip, the complete server -> wire -> consumer end-to-end loop, and malformed-wire-fails-closed.
 - Conformance runner support for `generic-pack-root`, `generic-delta`, `generic-delta-verify`, `generic-delta-decode` (12 shared fixtures); verified to produce identical pack roots and delta wire to `gcf-go`.
 - Session helper suite (`test_generic_delta_session.py`) mirroring `gcf-go`: FixedN cadence pattern, size-guard triggering, schema-change forced full, FixedN(15)-over-30-turns count, and the load-bearing consumer-stays-in-sync check under both policies. Conformance runner support for `generic-delta-session` (3 shared fixtures: fixed-N, size-guard, schema-change).
+- Generic-delta fuzz (`test_generic_delta_fuzz.py`), mirroring `gcf-go`: the decoder never crashes on arbitrary/mutated input, and arbitrary UTF-8 string cells (including multi-byte and control characters) survive the full-wire round-trip with the pack root preserved.
 
 ## v2.2.2 (2026-07-10)
 

{gcf_python-2.3.0 → gcf_python-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gcf-python
-Version: 2.3.0
+Version: 2.4.0
 Summary: The AI-native wire format for structured data. 50-92% fewer tokens than JSON, with multi-turn delta encoding for agent loops. 100% comprehension on every frontier model. Zero dependencies.
 Project-URL: Homepage, https://github.com/blackwell-systems/gcf-python
 Project-URL: Documentation, https://gcformat.com/
@@ -23,6 +23,10 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 
+<p align="center">
+  <img src="assets/gcf-python-diagram.png" alt="gcf-python" width="100%">
+</p>
+
 <p align="center">
   <a href="https://github.com/blackwell-systems"><img src="https://raw.githubusercontent.com/blackwell-systems/blackwell-docs-theme/main/badge-trademark.svg" alt="Blackwell Systems"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
@@ -119,7 +123,7 @@ enc = StreamEncoder(sys.stdout, "context_for_task", token_budget=5000)
 enc.write_symbol(Symbol(qualified_name="pkg.Auth", kind="function", score=0.95, provenance="lsp", distance=0))
 enc.write_symbol(Symbol(qualified_name="pkg.Server", kind="function", score=0.60, provenance="lsp", distance=1))
 enc.write_edge(Edge(source="pkg.Server", target="pkg.Auth", edge_type="calls"))
-enc.close()  # emits ## _summary trailer
+enc.close()  # emits ##! summary trailer
 ```
 
 Output:
@@ -131,7 +135,7 @@ GCF tool=context_for_task budget=5000
 @1 fn pkg.Server 0.60 lsp
 ## edges [?]
 @0<@1 calls
-## _summary symbols=2 edges=1 sections=targets:1,related:1,edges:1
+##! summary symbols=2 edges=1 counts=1,1,1
 ```
 
 The writer is any object with a `write(s: str)` method. Thread-safe. Standard `decode()` handles streaming output with no changes.

{gcf_python-2.3.0 → gcf_python-2.4.0}/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/gcf-python-diagram.png" alt="gcf-python" width="100%">
+</p>
+
 <p align="center">
   <a href="https://github.com/blackwell-systems"><img src="https://raw.githubusercontent.com/blackwell-systems/blackwell-docs-theme/main/badge-trademark.svg" alt="Blackwell Systems"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
@@ -94,7 +98,7 @@ enc = StreamEncoder(sys.stdout, "context_for_task", token_budget=5000)
 enc.write_symbol(Symbol(qualified_name="pkg.Auth", kind="function", score=0.95, provenance="lsp", distance=0))
 enc.write_symbol(Symbol(qualified_name="pkg.Server", kind="function", score=0.60, provenance="lsp", distance=1))
 enc.write_edge(Edge(source="pkg.Server", target="pkg.Auth", edge_type="calls"))
-enc.close()  # emits ## _summary trailer
+enc.close()  # emits ##! summary trailer
 ```
 
 Output:
@@ -106,7 +110,7 @@ GCF tool=context_for_task budget=5000
 @1 fn pkg.Server 0.60 lsp
 ## edges [?]
 @0<@1 calls
-## _summary symbols=2 edges=1 sections=targets:1,related:1,edges:1
+##! summary symbols=2 edges=1 counts=1,1,1
 ```
 
 The writer is any object with a `write(s: str)` method. Thread-safe. Standard `decode()` handles streaming output with no changes.

{gcf_python-2.3.0 → gcf_python-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gcf-python"
-version = "2.3.0"
+version = "2.4.0"
 description = "The AI-native wire format for structured data. 50-92% fewer tokens than JSON, with multi-turn delta encoding for agent loops. 100% comprehension on every frontier model. Zero dependencies."
 readme = "README.md"
 license = {text = "MIT"}

{gcf_python-2.3.0 → gcf_python-2.4.0}/src/gcf/__init__.py

@@ -36,7 +36,7 @@ Specification: https://github.com/blackwell-systems/gcf
 
 from .constants import KIND_ABBREV, KIND_EXPAND
 from .decode import DecodeError, decode
-from .delta import encode_delta
+from .delta import decode_delta, encode_delta, verify_delta
 from .encode import encode
 from .generic import encode_generic, GenericOptions
 from .generic_delta import (
@@ -56,6 +56,7 @@ from .generic_delta import (
     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
@@ -75,15 +76,18 @@ __all__ = [
     "StreamEncoder",
     "Symbol",
     "decode",
+    "decode_delta",
     "decode_generic",
     "encode",
     "encode_delta",
+    "verify_delta",
     "encode_generic",
     "GenericOptions",
     "encode_with_session",
     "GenericSet",
     "GenericDeltaPayload",
     "generic_pack_root",
+    "pack_root",
     "diff_generic_sets",
     "encode_generic_full",
     "encode_generic_delta",

{gcf_python-2.3.0 → gcf_python-2.4.0}/src/gcf/decode_generic.py

@@ -177,7 +177,14 @@ def _parse_object_body(
                         i += 1
                         continue
 
-        i += 1
+        # An object-body line that is not a `## ` section, a `key=value` field, or
+        # an inline array is not valid content and MUST NOT be silently skipped
+        # (that dropped data, a lossless round-trip hole). A pipe-delimited line is
+        # a stray positional inline body with no eligible `^` cell (SPEC 16.5,
+        # orphan_inline_attachment); any other unrecognized line is likewise rejected.
+        if "|" in content:
+            raise ValueError(f"orphan_inline_attachment: {content}")
+        raise ValueError(f"invalid_line: unexpected content in object body: {content!r}")
     return i - start
 
 
@@ -521,6 +528,11 @@ def _parse_tabular_body(
         if row_has_id:
             inline_idx = 0
 
+            # Columns that carry a `^` marker cell in this row legitimately expect
+            # a `.field` body. Any other `.field` is an orphan (Section 16.5) unless
+            # its name contains `>` (the flatten-fallback attachment, Section 7.4.6.1.4).
+            expected_att = set(traditional_att_fields) | set(inline_att_fields)
+
             while i < len(lines):
                 a_line = lines[i]
                 a_content: str | None = None
@@ -541,6 +553,14 @@ def _parse_tabular_body(
                     att_name, after_name = _parse_attachment_name(rest)
                     after_name_stripped = after_name.lstrip()
 
+                    # Orphan attachment: a `.field` with no matching `^` cell in this
+                    # row is only legitimate for a `>`-named field (Section 7.4.6.1.4).
+                    # Any other unmatched attachment is rejected rather than silently
+                    # injected as an undeclared extra field, which would decode to a
+                    # record no encoder produces (Section 16.5, lossless round-trip).
+                    if att_name not in expected_att and ">" not in att_name:
+                        raise ValueError(f"orphan_attachment: {att_name}")
+
                     # Prefixed inline data.
                     ifs = inline_schemas.get(att_name)
                     if ifs and not after_name_stripped.startswith("{}") and not after_name_stripped.startswith("["):

gcf_python-2.4.0/src/gcf/delta.py

@@ -0,0 +1,237 @@
+"""GCF delta encoding: only added/removed symbols for incremental delivery."""
+
+from .constants import KIND_ABBREV, KIND_EXPAND
+from .packroot import pack_root
+from .types import DeltaPayload, Edge, Symbol
+
+
+def encode_delta(d: DeltaPayload) -> str:
+    """Encode a DeltaPayload into GCF delta format.
+
+    Args:
+        d: The delta payload to encode.
+
+    Returns:
+        GCF delta-formatted text string.
+    """
+    parts: list[str] = []
+
+    # Header.
+    savings = 0.0
+    if d.full_tokens > 0:
+        savings = 100.0 * (1.0 - d.delta_tokens / d.full_tokens)
+
+    parts.append(
+        f"GCF profile=graph tool={d.tool} delta=true base_root={d.base_root} "
+        f"new_root={d.new_root} tokens={d.delta_tokens} savings={savings:.0f}%"
+    )
+
+    # Removed symbols: short references (consumer already has the full declaration).
+    if d.removed:
+        parts.append("## removed")
+        for s in d.removed:
+            kind = KIND_ABBREV.get(s.kind, s.kind)
+            parts.append(f"{kind} {s.qualified_name}")
+
+    # Added symbols: full declarations (consumer doesn't have these).
+    if d.added:
+        parts.append("## added")
+        for i, s in enumerate(d.added):
+            kind = KIND_ABBREV.get(s.kind, s.kind)
+            parts.append(
+                f"@{i} {kind} {s.qualified_name} {s.score:.2f} {s.provenance} {s.distance}"
+            )
+
+    # Removed edges.
+    if d.removed_edges:
+        parts.append("## edges_removed")
+        for e in d.removed_edges:
+            parts.append(f"{e.source} -> {e.target} {e.edge_type}")
+
+    # Added edges.
+    if d.added_edges:
+        parts.append("## edges_added")
+        for e in d.added_edges:
+            parts.append(f"{e.source} -> {e.target} {e.edge_type}")
+
+    return "\n".join(parts) + "\n"
+
+
+def _expand_kind(k: str) -> str:
+    """Reverse a kind abbreviation to its full form (identity if unknown)."""
+    return KIND_EXPAND.get(k, k)
+
+
+def _parse_delta_edge(line: str) -> Edge:
+    """Parse a `source -> target type` delta edge line."""
+    idx = line.find(" -> ")
+    if idx < 0:
+        raise ValueError(f"malformed_delta: edge line missing ' -> ': {line!r}")
+    source = line[:idx]
+    rest = line[idx + 4 :].split()
+    if len(rest) != 2:
+        raise ValueError(
+            f"malformed_delta: edge line {line!r} must be 'source -> target type'"
+        )
+    return Edge(source=source, target=rest[0], edge_type=rest[1])
+
+
+def decode_delta(wire: str) -> DeltaPayload:
+    """Parse a GCF graph delta wire payload back into a DeltaPayload.
+
+    Kind abbreviations on removed/added lines are expanded to their full form so the
+    result matches a base snapshot's symbol identities. Raises ValueError containing
+    ``malformed_delta`` on bad lines or unknown sections.
+    """
+    lines = wire.rstrip("\n").split("\n")
+    if not lines or lines[0] == "":
+        raise ValueError("missing_header: empty delta payload")
+    header = lines[0].rstrip("\r")
+    if not header.startswith("GCF profile=graph"):
+        raise ValueError(
+            "missing_profile: delta header must begin with 'GCF profile=graph'"
+        )
+
+    d = DeltaPayload()
+    for field in header.split():
+        kv = field.split("=", 1)
+        if len(kv) != 2:
+            continue
+        key, value = kv
+        if key == "tool":
+            d.tool = value
+        elif key == "base_root":
+            d.base_root = value
+        elif key == "new_root":
+            d.new_root = value
+
+    section = ""
+    for raw in lines[1:]:
+        line = raw.rstrip("\r")
+        if line == "":
+            continue
+        if line.startswith("## "):
+            section = line[3:].strip()
+            if section not in ("removed", "added", "edges_removed", "edges_added"):
+                raise ValueError(f"malformed_delta: unknown section {section!r}")
+            continue
+        if section == "removed":
+            parts = line.split()
+            if len(parts) != 2:
+                raise ValueError(
+                    f"malformed_delta: removed line {line!r} must be 'kind qname'"
+                )
+            d.removed.append(
+                Symbol(kind=_expand_kind(parts[0]), qualified_name=parts[1])
+            )
+        elif section == "added":
+            parts = line.split()
+            if len(parts) != 6:
+                raise ValueError(
+                    f"malformed_delta: added line {line!r} must be "
+                    "'@id kind qname score provenance distance'"
+                )
+            try:
+                score = float(parts[3])
+            except ValueError:
+                raise ValueError(f"malformed_delta: invalid added score {parts[3]!r}")
+            try:
+                dist = int(parts[5])
+            except ValueError:
+                raise ValueError(
+                    f"malformed_delta: invalid added distance {parts[5]!r}"
+                )
+            d.added.append(
+                Symbol(
+                    kind=_expand_kind(parts[1]),
+                    qualified_name=parts[2],
+                    score=score,
+                    provenance=parts[4],
+                    distance=dist,
+                )
+            )
+        elif section in ("edges_removed", "edges_added"):
+            e = _parse_delta_edge(line)
+            if section == "edges_removed":
+                d.removed_edges.append(e)
+            else:
+                d.added_edges.append(e)
+        else:
+            raise ValueError(
+                f"malformed_delta: data line {line!r} before any section header"
+            )
+    return d
+
+
+def verify_delta(
+    base_symbols: list[Symbol],
+    base_edges: list[Edge],
+    removed: list[Symbol],
+    added: list[Symbol],
+    removed_edges: list[Edge],
+    added_edges: list[Edge],
+    expected_new_root: str,
+) -> tuple[list[Symbol], list[Edge]]:
+    """Apply a delta to a base snapshot and verify the resulting pack root.
+
+    Symbols are matched by identity ``(kind, qualified_name)``; edges by
+    ``(source, target, edge_type)``. Raises ValueError containing ``delta_invalid``
+    when removing a symbol/edge that does not exist or adding one that already exists,
+    and ``root_mismatch`` when the recomputed pack root differs from
+    ``expected_new_root``. On success returns the applied ``(symbols, edges)``.
+    """
+    sym_map: dict[tuple[str, str], Symbol] = {}
+    for s in base_symbols:
+        sym_map[(s.kind, s.qualified_name)] = s
+
+    for s in removed:
+        key = (s.kind, s.qualified_name)
+        if key not in sym_map:
+            raise ValueError(
+                f"delta_invalid: removing symbol {s.kind} {s.qualified_name} "
+                "that does not exist in base"
+            )
+        del sym_map[key]
+
+    for s in added:
+        key = (s.kind, s.qualified_name)
+        if key in sym_map:
+            raise ValueError(
+                f"delta_invalid: adding symbol {s.kind} {s.qualified_name} "
+                "that already exists"
+            )
+        sym_map[key] = s
+
+    result_symbols = list(sym_map.values())
+
+    edge_map: dict[tuple[str, str, str], Edge] = {}
+    for e in base_edges:
+        edge_map[(e.source, e.target, e.edge_type)] = e
+
+    for e in removed_edges:
+        key = (e.source, e.target, e.edge_type)
+        if key not in edge_map:
+            raise ValueError(
+                f"delta_invalid: removing edge {e.source} -> {e.target} "
+                f"{e.edge_type} that does not exist"
+            )
+        del edge_map[key]
+
+    for e in added_edges:
+        key = (e.source, e.target, e.edge_type)
+        if key in edge_map:
+            raise ValueError(
+                f"delta_invalid: adding edge {e.source} -> {e.target} "
+                f"{e.edge_type} that already exists"
+            )
+        edge_map[key] = e
+
+    result_edges = list(edge_map.values())
+
+    computed_root = pack_root(result_symbols, result_edges)
+    if computed_root != expected_new_root:
+        raise ValueError(
+            f"root_mismatch: computed {computed_root}, expected {expected_new_root}"
+        )
+
+    return result_symbols, result_edges

{gcf_python-2.3.0 → gcf_python-2.4.0}/src/gcf/encode.py

@@ -17,10 +17,16 @@ 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(
@@ -28,14 +34,20 @@ def encode(p: Payload) -> str:
         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:
@@ -52,17 +64,25 @@ def encode(p: Payload) -> str:
             kind = KIND_ABBREV.get(s.kind, s.kind)
             parts.append(f"@{idx} {kind} {s.qualified_name} {s.score:.2f} {s.provenance}")
 
-    # Edges section.
+    # Edges section. Order edges by source ID then target ID (then edge type
+    # for parallel edges) so the wire is canonical regardless of the order
+    # edges were provided (SPEC 16.1). Edge reordering is decode-invariant
+    # (edges are a set) and does not affect pack_root, which sorts edge records
+    # independently.
     if p.edges:
-        edge_lines: list[str] = []
+        resolved: list[tuple[int, int, str, str]] = []
         for e in p.edges:
             src_idx = sym_index.get(e.source)
             tgt_idx = sym_index.get(e.target)
             if src_idx is None or tgt_idx is None:
                 continue
-            line = f"@{tgt_idx}<@{src_idx} {e.edge_type}"
-            if e.status and e.status != "unchanged":
-                line += f" {e.status}"
+            resolved.append((src_idx, tgt_idx, e.edge_type, e.status))
+        resolved.sort(key=lambda r: (r[0], r[1], r[2]))
+        edge_lines: list[str] = []
+        for src_idx, tgt_idx, edge_type, status in resolved:
+            line = f"@{tgt_idx}<@{src_idx} {edge_type}"
+            if status and status != "unchanged":
+                line += f" {status}"
             edge_lines.append(line)
         parts.append(f"## edges [{len(edge_lines)}]")
         parts.extend(edge_lines)
@@ -71,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]

gcf_python-2.4.0/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

{gcf_python-2.3.0 → gcf_python-2.4.0}/src/gcf/session.py

@@ -77,22 +77,32 @@ def encode_with_session(p: Payload, sess: Session | None = None) -> str:
 
     parts: list[str] = []
 
-    # Build local ID mapping for this response.
+    # Build session-stable ID mapping (matching the reference encoder):
+    # previously transmitted symbols keep their existing session-global ID;
+    # new symbols get the next available session IDs in payload order. These
+    # are NOT per-call local indices, so IDs stay stable across calls within a
+    # session (see graph-session conformance fixtures).
     local_index: dict[str, int] = {}
-    for i, s in enumerate(p.symbols):
-        local_index[s.qualified_name] = i
-
-    # Count valid edges.
-    valid_edges = sum(
-        1 for e in p.edges
-        if e.source in local_index and e.target in local_index
-    )
-
-    # Header with session=true marker.
-    header = (
-        f"GCF profile=graph tool={p.tool} budget={p.token_budget} tokens={p.tokens_used} "
-        f"symbols={len(p.symbols)} edges={valid_edges} session=true"
-    )
+    for s in p.symbols:
+        if sess.transmitted(s.qualified_name):
+            local_index[s.qualified_name] = sess.get_id(s.qualified_name)
+    next_new = sess.size()
+    for s in p.symbols:
+        if not sess.transmitted(s.qualified_name):
+            local_index[s.qualified_name] = next_new
+            next_new += 1
+
+    # Header with session=true marker. 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 p.edges:
+        header += f" edges={len(p.edges)}"
+    header += " session=true"
     if p.pack_root:
         header += f" pack_root={p.pack_root}"
     parts.append(header)
@@ -128,7 +138,7 @@ def encode_with_session(p: Payload, sess: Session | None = None) -> str:
 
     # Edges section.
     if p.edges:
-        parts.append(f"## edges [{valid_edges}]")
+        parts.append(f"## edges [{len(p.edges)}]")
         for e in p.edges:
             src_idx = local_index.get(e.source)
             tgt_idx = local_index.get(e.target)