gcf-python 2.5.0__tar.gz → 2.5.1__tar.gz

{gcf_python-2.5.0 → gcf_python-2.5.1}/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v2.5.1 (2026-08-07)
+
+- Decoders now reject a declared `[N]` section count that does not match the actual item count, in both directions, per SPEC Section 13 (Count Validation). A declared count smaller than the rows or entries present was previously read as a limit and the surplus was dropped; it is now an error. Covers the generic tabular, keyed-map, and root-array forms, the delta and full-set decoders, and the graph `## edges [N]` section. Valid payloads and encoding are unchanged.
+
 ## v2.5.0 (2026-08-07)
 
 ### Added

{gcf_python-2.5.0 → gcf_python-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gcf-python
-Version: 2.5.0
+Version: 2.5.1
 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/

{gcf_python-2.5.0 → gcf_python-2.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gcf-python"
-version = "2.5.0"
+version = "2.5.1"
 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.5.0 → gcf_python-2.5.1}/src/gcf/decode.py

@@ -45,6 +45,8 @@ def decode(input_text: str) -> Payload:
     sym_by_id: dict[int, Symbol] = {}
     current_distance = 0
     in_edges = False
+    declared_edges = -1
+    edges_declared = False
 
     for line in lines[1:]:
         line = line.rstrip("\r")
@@ -58,13 +60,29 @@ def decode(input_text: str) -> Payload:
         # Group header.
         if line.startswith("## "):
             group = line[3:]
-            # Strip bracket suffix: "edges [200]" -> "edges"
+            # Strip bracket suffix: "edges [200]" -> "edges", capturing the
+            # declared count so it can be enforced per Section 13.
+            declared_count = -1
             bracket_idx = group.find(" [")
             if bracket_idx >= 0:
+                bracket = group[bracket_idx + 2:]
                 group = group[:bracket_idx]
+                end = bracket.find("]")
+                if end >= 0:
+                    cnt_str = bracket[:end]
+                    if cnt_str != "?":  # "[?]" is a streaming deferred count (Section 8)
+                        try:
+                            declared_count = int(cnt_str)
+                        except ValueError:
+                            raise DecodeError(
+                                f"count_mismatch: invalid section count {cnt_str!r}"
+                            )
             if is_delta and group not in valid_delta_sections:
                 raise DecodeError(f"malformed_delta: invalid delta section {group!r}")
             in_edges = group == "edges"
+            if in_edges and declared_count >= 0:
+                declared_edges = declared_count
+                edges_declared = True
             if not in_edges:
                 if group == "targets":
                     current_distance = 0
@@ -91,6 +109,13 @@ def decode(input_text: str) -> Payload:
             symbols.append(sym)
             sym_by_id[sym_id] = sym
 
+    # Section 13: a declared [N] section count MUST match the actual item count.
+    # The graph edges section is the graph profile's only [N]-bearing section.
+    if edges_declared and len(p.edges) != declared_edges:
+        raise DecodeError(
+            f"count_mismatch: declared {declared_edges} edges, got {len(p.edges)}"
+        )
+
     p.symbols = symbols
     return p
 

{gcf_python-2.5.0 → gcf_python-2.5.1}/src/gcf/decode_generic.py

@@ -91,7 +91,14 @@ def decode_generic(input_text: str) -> Any:
         return parse_scalar(first[1:])
 
     if first.startswith("## ["):
-        arr, _ = _parse_array_from_header(content_lines, 0, 0, first[3:])
+        arr, consumed = _parse_array_from_header(content_lines, 0, 0, first[3:])
+        # A root array or keyed map spans the whole document, so any structural line
+        # past the consumed rows is a surplus item, not sibling content. The row loop
+        # stops at the declared count, so the count assert only catches the deficit
+        # case; surplus is caught here (SPEC Section 13: a mismatch, fewer OR more
+        # items than declared, is an error).
+        if consumed < len(content_lines):
+            raise ValueError("count_mismatch: declared count is fewer than the rows present")
         return arr
 
     result: dict[str, Any] = {}

{gcf_python-2.5.0 → gcf_python-2.5.1}/src/gcf/generic_delta.py

@@ -299,16 +299,23 @@ def decode_generic_full(text: str) -> tuple[GenericSet, str]:
     while i < len(lines):
         line = lines[i]
         if not line.startswith("## "):
-            i += 1
-            continue
+            # Only blank lines, comments, and the ##! summary trailer are valid
+            # outside a section; any other line is a surplus row past a declared
+            # section count (Section 13).
+            if line == "" or line.startswith("# ") or line.startswith("##! "):
+                i += 1
+                continue
+            raise ValueError(
+                f"count_mismatch: unexpected content after declared section rows: {line!r}"
+            )
         name, count, fields, key_field = _parse_section_header(line[3:])
         s.name, s.fields = name, fields
         if not s.key:
             s.key = key_field
         i += 1
-        for _ in range(count):
-            if i >= len(lines):
-                raise ValueError("delta_invalid: fewer rows than declared count")
+        for j in range(count):
+            if i >= len(lines) or lines[i].startswith("## "):
+                raise ValueError(f"count_mismatch: declared {count} rows, got {j}")
             s.rows.append(_parse_row(lines[i], fields))
             i += 1
     return s, hdr.get("pack_root", "")
@@ -335,8 +342,15 @@ def decode_generic_delta(text: str) -> GenericDeltaPayload:
     while i < len(lines):
         line = lines[i]
         if not line.startswith("## "):
-            i += 1
-            continue
+            # Only blank lines, comments, and the ##! summary trailer are valid
+            # outside a section; any other line is a surplus row past a declared
+            # section count (Section 13).
+            if line == "" or line.startswith("# ") or line.startswith("##! "):
+                i += 1
+                continue
+            raise ValueError(
+                f"count_mismatch: unexpected content after declared section rows: {line!r}"
+            )
         name, count, fields, key_field = _parse_section_header(line[3:])
         if not d.key and key_field:
             d.key = key_field
@@ -345,9 +359,9 @@ def decode_generic_delta(text: str) -> GenericDeltaPayload:
         i += 1
         if name in ("added", "changed"):
             rows = []
-            for _ in range(count):
-                if i >= len(lines):
-                    raise ValueError(f"delta_invalid: fewer rows than declared count in ## {name}")
+            for j in range(count):
+                if i >= len(lines) or lines[i].startswith("## "):
+                    raise ValueError(f"count_mismatch: declared {count} rows in ## {name}, got {j}")
                 rows.append(_parse_row(lines[i], fields))
                 i += 1
             if name == "added":
@@ -355,9 +369,9 @@ def decode_generic_delta(text: str) -> GenericDeltaPayload:
             else:
                 d.changed = rows
         elif name == "removed":
-            for _ in range(count):
-                if i >= len(lines):
-                    raise ValueError("delta_invalid: fewer identities than declared count in ## removed")
+            for j in range(count):
+                if i >= len(lines) or lines[i].startswith("## "):
+                    raise ValueError(f"count_mismatch: declared {count} identities in ## removed, got {j}")
                 d.removed.append(parse_scalar(lines[i], True))
                 i += 1
         else: