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

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

@@ -1,5 +1,21 @@
 # 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
+- Keyed-tabular map encoding (SPEC 7.2a): a JSON object whose values are all objects forming a tabular set is encoded as a keyed table (`## [N:]{key,...}`) - the shared value fields are declared once, with one key-prefixed row per member. Canonical by default, supported in nested and streaming positions, and integrated with generic delta using the map key as the identity.
+
+### Changed
+- Negative zero is canonicalized to `0` for both integer and floating-point values (SPEC 2.3.1).
+- Canonical-output alignment across all six SDKs: object key ordering, graph header fields, and symbol ordering follow the specification and reference implementation exactly.
+
+### Testing
+- Conformance runners assert re-encode idempotence (`encode(decode(x)) == x`) for the generic, graph, and delta profiles; a differential cross-SDK fuzz was added to the verification suite.
+
 ## v2.4.0 (2026-07-12)
 
 ### Fixes

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gcf-python
-Version: 2.4.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/
@@ -24,19 +24,39 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="assets/gcf-python-diagram.png" alt="gcf-python" width="100%">
+  <a href="https://gcformat.com/playground.html"><img src="https://img.shields.io/badge/playground-live-2563eb?style=for-the-badge" alt="Playground"></a>
+  <a href="https://gcformat.com/guide/benchmarks.html"><img src="https://img.shields.io/badge/benchmarks-2%2C500%2B%20evals-22c55e?style=for-the-badge" alt="Benchmarks"></a>
+  <a href="https://pypi.org/project/gcf-python/"><img src="https://img.shields.io/pypi/v/gcf-python?style=for-the-badge&logo=python&logoColor=white&color=3776AB" alt="PyPI"></a>
+  <a href="https://github.com/blackwell-systems/gcf-python/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-333?style=for-the-badge" alt="License"></a>
 </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>
+  <img src="https://raw.githubusercontent.com/blackwell-systems/gcf-python/main/assets/gcf-hero-wire-delta.png" alt="gcf-python" width="760">
 </p>
 
 # gcf-python
 
-Python implementation of [GCF](https://gcformat.com/) — the most token-efficient wire format for LLMs. A drop-in alternative to JSON and TOON for any structured data.
+Python implementation of [GCF](https://gcformat.com/), the most token-efficient wire format for LLMs. A drop-in alternative to JSON and TOON for any structured data.
 
-**100% comprehension on every frontier model tested. 29% fewer tokens than TOON, 56% fewer than JSON across 16 datasets. 91.2% on structurally complex code graphs (vs TOON 68.8%, JSON 54.1%). 2,400+ LLM evaluations. Zero training.**
+<p align="center">
+  <img src="https://raw.githubusercontent.com/blackwell-systems/gcf-python/main/assets/divider-wave-2.png" alt="" width="100%">
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/blackwell-systems/gcf-python/main/assets/gcf-python-diagram.png" alt="gcf-python" width="80%">
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/blackwell-systems/gcf-python/main/assets/divider.png" alt="" width="100%">
+</p>
+
+**Built for the agentic loop, where the same structured context crosses the model boundary turn after turn.** A single payload is 50-92% smaller than JSON, but GCF also deduplicates repeated structure across turns and sends only deltas when context changes, so by the 5th overlapping call each response costs 99% fewer tokens than JSON, and a 10-call session runs 94.4% cheaper than re-sending JSON every turn. Session dedup and delta both need local IDs and a multi-turn design that neither JSON nor TOON has.
+
+- **100% comprehension on every frontier model**, zero training. 29% fewer tokens than TOON and 56% fewer than JSON across 16 datasets; 91.2% on structurally complex code graphs (vs TOON 68.8%, JSON 54.1%).
+- **Proven lossless** across 43,000,000,000+ round-trips in 5 formats and 6 languages. Zero runtime dependencies.
+- **One format, four properties no other single format holds at once:** schema-free, lossless, token-compact (50-92% vs JSON), and model-readable with zero training. JSON is verbose, Protobuf needs a schema, MessagePack is binary, and TOON isn't reliably lossless.
+
+2,500+ LLM evaluations. [Full benchmarks](https://gcformat.com/guide/benchmarks.html).
 
 Docs: [gcformat.com](https://gcformat.com/) · [Playground](https://gcformat.com/playground.html) · [GCF vs TOON](https://gcformat.com/guide/vs-toon.html)
 
@@ -109,7 +129,7 @@ out1 = encode_with_session(payload1, sess)  # full declarations
 out2 = encode_with_session(payload2, sess)  # reused symbols as "@N  # previously transmitted"
 ```
 
-By the 5th call in a session: 92.7% token savings vs JSON.
+By the 5th call in a session: 86% fewer tokens than JSON from dedup alone, 99% stacked with delta encoding.
 
 ## Streaming Encode
 
@@ -254,7 +274,7 @@ for snapshot in stream:                   # each turn's current GenericSet
 
 ## Benchmarks
 
-2,400+ LLM evaluations across 10 models, 3 providers, and 51 independent test runs.
+2,500+ LLM evaluations across 11 models, 4 providers, and 50+ independent test runs.
 
 | | GCF | TOON | JSON |
 |---|---|---|---|
@@ -284,11 +304,23 @@ GCF wins 15/16 datasets on the expanded [token efficiency benchmark](https://git
 
 **Zero runtime dependencies. Permanently.** All six implementations depend only on their language's standard library. No transitive dependencies. No supply chain risk. This is a permanent commitment: GCF will never take on external runtime dependencies. MIT licensed. All implementations support both generic profile (`encodeGeneric`) and graph profile (`encode`). CLI included in all 6 languages.
 
-**Specification:** [SPEC v3.2 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 174 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. All implementations at v2.2.1+ (Go v1.3.1). Cross-language 6x6 matrix verified.
+**Specification:** [SPEC v3.4.1 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 204 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. All implementations at v2.4.0+ (Go v1.5.0). Cross-language 6x6 matrix verified.
 
 ## Adopted by
 
-[Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) (46K stars, Google Chrome DevTools team) · [Speakeasy](https://speakeasy.com) (API tooling, customers include Google, Verizon, Mistral AI, DocuSign, Vercel) · [OmniRoute](https://omniroute.online) (6.1K stars) · [NetClaw](https://github.com/automateyournetwork/netclaw) (556 stars) · [ctx](https://github.com/stevesolun/ctx) (510 stars) · [NeuroNest](https://neuronest.cc) · [Open Data Products SDK](https://opendataproducts.org/sdk/) (Linux Foundation) · [Raycast](https://raycast.com/blackwell-systems/json-to-gcf-converter) · [and more](https://gcformat.com/ecosystem/adopters.html)
+| Project | |
+|---------|--|
+| **[Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)** | 47K★ · the Google Chrome DevTools team's MCP server; exposes live browser state (DOM, network, console, performance) to AI coding agents |
+| **[Speakeasy](https://speakeasy.com)** | OpenAPI tooling (customers include Google, Verizon, Mistral AI, DocuSign, Vercel); GCF is a native output format in their `oq` CLI |
+| **[OmniRoute](https://omniroute.online)** | 17K★ · AI gateway, registry, and proxy between AI clients and model providers; GCF vendored into its compression engine |
+| **[NetClaw](https://github.com/automateyournetwork/netclaw)** | 610★ · AI-powered network automation (113 skills, 66 MCP integrations); replaced TOON with GCF across every MCP server |
+| **[ctx](https://github.com/stevesolun/ctx)** | 552★ · real-time context selector for Claude Code; surfaces only the relevant tools from a 103K-node knowledge graph |
+| **[Lynkr](https://github.com/Fast-Editor/Lynkr)** | 531★ · local LLM gateway for AI coding clients; GCF as a drop-in tool-result compressor alongside TOON |
+| **[Open Data Products SDK](https://opendataproducts.org/sdk/)** | Linux Foundation · Python toolkit and MCP server for data-product standards; GCF sidecars for agent context |
+| **[NeuroNest](https://neuronest.cc)** | agent-first IDE; first commercial GCF adoption, across four encoding surfaces with session dedup and delta |
+| **[Raycast](https://raycast.com/blackwell-systems/json-to-gcf-converter)** | JSON-to-GCF Converter extension in the Raycast Store, for the macOS productivity launcher |
+
+[See all adopters →](https://gcformat.com/ecosystem/adopters.html)
 
 ## License
 

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

@@ -1,17 +1,37 @@
 <p align="center">
-  <img src="assets/gcf-python-diagram.png" alt="gcf-python" width="100%">
+  <a href="https://gcformat.com/playground.html"><img src="https://img.shields.io/badge/playground-live-2563eb?style=for-the-badge" alt="Playground"></a>
+  <a href="https://gcformat.com/guide/benchmarks.html"><img src="https://img.shields.io/badge/benchmarks-2%2C500%2B%20evals-22c55e?style=for-the-badge" alt="Benchmarks"></a>
+  <a href="https://pypi.org/project/gcf-python/"><img src="https://img.shields.io/pypi/v/gcf-python?style=for-the-badge&logo=python&logoColor=white&color=3776AB" alt="PyPI"></a>
+  <a href="https://github.com/blackwell-systems/gcf-python/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-333?style=for-the-badge" alt="License"></a>
 </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>
+  <img src="https://raw.githubusercontent.com/blackwell-systems/gcf-python/main/assets/gcf-hero-wire-delta.png" alt="gcf-python" width="760">
 </p>
 
 # gcf-python
 
-Python implementation of [GCF](https://gcformat.com/) — the most token-efficient wire format for LLMs. A drop-in alternative to JSON and TOON for any structured data.
+Python implementation of [GCF](https://gcformat.com/), the most token-efficient wire format for LLMs. A drop-in alternative to JSON and TOON for any structured data.
 
-**100% comprehension on every frontier model tested. 29% fewer tokens than TOON, 56% fewer than JSON across 16 datasets. 91.2% on structurally complex code graphs (vs TOON 68.8%, JSON 54.1%). 2,400+ LLM evaluations. Zero training.**
+<p align="center">
+  <img src="https://raw.githubusercontent.com/blackwell-systems/gcf-python/main/assets/divider-wave-2.png" alt="" width="100%">
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/blackwell-systems/gcf-python/main/assets/gcf-python-diagram.png" alt="gcf-python" width="80%">
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/blackwell-systems/gcf-python/main/assets/divider.png" alt="" width="100%">
+</p>
+
+**Built for the agentic loop, where the same structured context crosses the model boundary turn after turn.** A single payload is 50-92% smaller than JSON, but GCF also deduplicates repeated structure across turns and sends only deltas when context changes, so by the 5th overlapping call each response costs 99% fewer tokens than JSON, and a 10-call session runs 94.4% cheaper than re-sending JSON every turn. Session dedup and delta both need local IDs and a multi-turn design that neither JSON nor TOON has.
+
+- **100% comprehension on every frontier model**, zero training. 29% fewer tokens than TOON and 56% fewer than JSON across 16 datasets; 91.2% on structurally complex code graphs (vs TOON 68.8%, JSON 54.1%).
+- **Proven lossless** across 43,000,000,000+ round-trips in 5 formats and 6 languages. Zero runtime dependencies.
+- **One format, four properties no other single format holds at once:** schema-free, lossless, token-compact (50-92% vs JSON), and model-readable with zero training. JSON is verbose, Protobuf needs a schema, MessagePack is binary, and TOON isn't reliably lossless.
+
+2,500+ LLM evaluations. [Full benchmarks](https://gcformat.com/guide/benchmarks.html).
 
 Docs: [gcformat.com](https://gcformat.com/) · [Playground](https://gcformat.com/playground.html) · [GCF vs TOON](https://gcformat.com/guide/vs-toon.html)
 
@@ -84,7 +104,7 @@ out1 = encode_with_session(payload1, sess)  # full declarations
 out2 = encode_with_session(payload2, sess)  # reused symbols as "@N  # previously transmitted"
 ```
 
-By the 5th call in a session: 92.7% token savings vs JSON.
+By the 5th call in a session: 86% fewer tokens than JSON from dedup alone, 99% stacked with delta encoding.
 
 ## Streaming Encode
 
@@ -229,7 +249,7 @@ for snapshot in stream:                   # each turn's current GenericSet
 
 ## Benchmarks
 
-2,400+ LLM evaluations across 10 models, 3 providers, and 51 independent test runs.
+2,500+ LLM evaluations across 11 models, 4 providers, and 50+ independent test runs.
 
 | | GCF | TOON | JSON |
 |---|---|---|---|
@@ -259,11 +279,23 @@ GCF wins 15/16 datasets on the expanded [token efficiency benchmark](https://git
 
 **Zero runtime dependencies. Permanently.** All six implementations depend only on their language's standard library. No transitive dependencies. No supply chain risk. This is a permanent commitment: GCF will never take on external runtime dependencies. MIT licensed. All implementations support both generic profile (`encodeGeneric`) and graph profile (`encode`). CLI included in all 6 languages.
 
-**Specification:** [SPEC v3.2 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 174 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. All implementations at v2.2.1+ (Go v1.3.1). Cross-language 6x6 matrix verified.
+**Specification:** [SPEC v3.4.1 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 204 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. All implementations at v2.4.0+ (Go v1.5.0). Cross-language 6x6 matrix verified.
 
 ## Adopted by
 
-[Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) (46K stars, Google Chrome DevTools team) · [Speakeasy](https://speakeasy.com) (API tooling, customers include Google, Verizon, Mistral AI, DocuSign, Vercel) · [OmniRoute](https://omniroute.online) (6.1K stars) · [NetClaw](https://github.com/automateyournetwork/netclaw) (556 stars) · [ctx](https://github.com/stevesolun/ctx) (510 stars) · [NeuroNest](https://neuronest.cc) · [Open Data Products SDK](https://opendataproducts.org/sdk/) (Linux Foundation) · [Raycast](https://raycast.com/blackwell-systems/json-to-gcf-converter) · [and more](https://gcformat.com/ecosystem/adopters.html)
+| Project | |
+|---------|--|
+| **[Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)** | 47K★ · the Google Chrome DevTools team's MCP server; exposes live browser state (DOM, network, console, performance) to AI coding agents |
+| **[Speakeasy](https://speakeasy.com)** | OpenAPI tooling (customers include Google, Verizon, Mistral AI, DocuSign, Vercel); GCF is a native output format in their `oq` CLI |
+| **[OmniRoute](https://omniroute.online)** | 17K★ · AI gateway, registry, and proxy between AI clients and model providers; GCF vendored into its compression engine |
+| **[NetClaw](https://github.com/automateyournetwork/netclaw)** | 610★ · AI-powered network automation (113 skills, 66 MCP integrations); replaced TOON with GCF across every MCP server |
+| **[ctx](https://github.com/stevesolun/ctx)** | 552★ · real-time context selector for Claude Code; surfaces only the relevant tools from a 103K-node knowledge graph |
+| **[Lynkr](https://github.com/Fast-Editor/Lynkr)** | 531★ · local LLM gateway for AI coding clients; GCF as a drop-in tool-result compressor alongside TOON |
+| **[Open Data Products SDK](https://opendataproducts.org/sdk/)** | Linux Foundation · Python toolkit and MCP server for data-product standards; GCF sidecars for agent context |
+| **[NeuroNest](https://neuronest.cc)** | agent-first IDE; first commercial GCF adoption, across four encoding surfaces with session dedup and delta |
+| **[Raycast](https://raycast.com/blackwell-systems/json-to-gcf-converter)** | JSON-to-GCF Converter extension in the Raycast Store, for the macOS productivity launcher |
+
+[See all adopters →](https://gcformat.com/ecosystem/adopters.html)
 
 ## License
 

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

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

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import Any
 
 from .decode import decode
+from .keyed_map import keyed_rows_to_map
 from .scalar import (
     parse_scalar, parse_quoted_string, split_respecting_quotes, split_field_decl,
     is_bare_key, MISSING, ATTACHMENT,
@@ -72,7 +73,7 @@ def decode_generic(input_text: str) -> Any:
         if trimmed.startswith("##! "):
             summary_line = trimmed
             continue
-        if trimmed.startswith("## ") and "[?]" in trimmed:
+        if trimmed.startswith("## ") and ("[?]" in trimmed or "[?:]" in trimmed):
             deferred_count += 1
         content_lines.append(line)
 
@@ -90,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] = {}
@@ -134,7 +142,7 @@ def _parse_object_body(
 
         if content.startswith("## "):
             hdr = content[3:]
-            bi = hdr.find(" [")
+            bi = _find_bracket_start(hdr)
             if bi >= 0:
                 name = _parse_key_from_header(hdr[:bi])
                 _check_dup(out, name)
@@ -233,10 +241,24 @@ def _parse_array_from_header(
         raise ValueError("invalid_count")
     count_str = bp[1:close]
     after = bp[close + 1:]
+
+    # A keyed map is marked by `:` after the count inside the bracket (`[N:]`).
+    # The decoder reconstructs a JSON object, not an array (SPEC 7.2a.2).
+    keyed = count_str.endswith(":")
+    if keyed:
+        count_str = count_str[:-1]
+        if not after.startswith("{"):
+            raise ValueError("keyed_map: missing field declaration")
+
     count = -1
     if count_str != "?":
         count = _parse_count(count_str)
 
+    # A keyed map has at least one member; an empty object is encoded per
+    # Section 7.7, never as [0:] (SPEC 7.2a.4).
+    if keyed and count == 0:
+        raise ValueError("keyed_map: zero count [0:] is invalid (an empty object uses Section 7.7)")
+
     if count == 0 and not after.startswith("{") and not after.startswith(":"):
         return [], 1
 
@@ -259,6 +281,8 @@ def _parse_array_from_header(
         rows, consumed = _parse_tabular_body(lines, header_line + 1, depth, fields, count)
         if count >= 0 and len(rows) != count:
             raise ValueError(f"count_mismatch: declared {count}, got {len(rows)}")
+        if keyed:
+            return keyed_rows_to_map(rows, fields), consumed + 1
         return rows, consumed + 1
 
     items, consumed = _parse_expanded_body(lines, header_line + 1, depth)
@@ -267,6 +291,27 @@ def _parse_array_from_header(
     return items, consumed + 1
 
 
+def _find_bracket_start(s: str) -> int:
+    # Find " [" (the named-array count bracket) that is OUTSIDE any quoted name,
+    # so a quoted section/key name containing " [" (e.g. `## "a [1] b"`) is not
+    # misread as a named-array header. Mirrors _find_closing_brace's quote tracking.
+    in_quote = False
+    escaped = False
+    for i, c in enumerate(s):
+        if escaped:
+            escaped = False
+            continue
+        if c == "\\" and in_quote:
+            escaped = True
+            continue
+        if c == '"':
+            in_quote = not in_quote
+            continue
+        if not in_quote and c == " " and i + 1 < len(s) and s[i + 1] == "[":
+            return i
+    return -1
+
+
 def _find_closing_brace(s: str) -> int:
     in_quote = False
     escaped = False
@@ -633,8 +678,22 @@ def _parse_tabular_body(
                     if extra_name in attachment_values:
                         raise ValueError(f"duplicate_attachment: {extra_name}")
 
+        # Reconstruct the row in declared field-union order. A flattened group is
+        # emitted at the position of its first path column, so the nested object
+        # reappears where the original field was, not appended at the end (SPEC
+        # 7.4.6.1 step 7 and the key-order preservation requirement, SPEC 52, 931).
+        nested = _unflatten_paths(path_column_map, flat_values, flat_absent) if path_column_map else {}
+        emitted_groups: set[str] = set()
         row: dict[str, Any] = {}
         for f in fields:
+            if f in path_column_map:
+                top = path_column_map[f][0]
+                if top in emitted_groups:
+                    continue
+                emitted_groups.add(top)
+                if top in nested:  # omitted when the whole group is absent
+                    row[top] = nested[top]
+                continue
             if f in missing_fields:
                 continue
             if f in cell_values:
@@ -645,10 +704,6 @@ def _parse_tabular_body(
         for k, v in attachment_values.items():
             if k not in row:
                 row[k] = v
-        # Unflatten path columns into nested objects.
-        if path_column_map:
-            nested = _unflatten_paths(path_column_map, flat_values, flat_absent)
-            row.update(nested)
 
         rows.append(row)
 
@@ -745,7 +800,7 @@ def _validate_summary_counts(
     current_count = 0
     for line in content_lines:
         trimmed = line.lstrip()
-        if trimmed.startswith("## ") and "[?]" in trimmed:
+        if trimmed.startswith("## ") and ("[?]" in trimmed or "[?:]" in trimmed):
             if in_deferred:
                 actual_counts.append(current_count)
             in_deferred = True

{gcf_python-2.4.0 → gcf_python-2.5.1}/src/gcf/generic.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass
 from typing import Any
 
 from .scalar import format_scalar, format_key
+from .keyed_map import keyed_map_eligible
 
 
 @dataclass
@@ -30,6 +31,11 @@ def _encode_root_value(v: Any, out: list[str], opts: GenericOptions) -> None:
     if v is None:
         out.append("=-")
     elif isinstance(v, dict):
+        km = keyed_map_eligible(v)
+        if km is not None:
+            keys, values, value_fields, key_label = km
+            _encode_keyed_map("", False, keys, values, value_fields, key_label, out, 0, opts)
+            return
         _encode_object(v, out, 0, opts)
     elif isinstance(v, list):
         _encode_root_array(v, out, opts)
@@ -42,6 +48,11 @@ def _encode_object(d: dict, out: list[str], depth: int, opts: GenericOptions) ->
     for key, value in d.items():
         fk = format_key(key)
         if isinstance(value, dict):
+            km = keyed_map_eligible(value)
+            if km is not None:
+                keys, values, value_fields, key_label = km
+                _encode_keyed_map(key, True, keys, values, value_fields, key_label, out, depth, opts)
+                continue
             out.append(f"{prefix}## {fk}")
             _encode_object(value, out, depth + 1, opts)
         elif isinstance(value, list):
@@ -165,8 +176,9 @@ def _analyze_flattenable(
     arr: list[dict], field_name: str, parent_path: str
 ) -> list[dict] | None:
     """Analyze whether a field can be flattened. Returns list of leaf descriptors or None."""
-    # Field names containing ">" cannot be flattened (would create ambiguous paths).
-    if ">" in field_name:
+    # A field name that is empty or contains ">" cannot be flattened: it would create an
+    # ambiguous path column the decoder treats as literal (SPEC 7.4.6.1.3).
+    if field_name == "" or ">" in field_name:
         return None
     canonical_shape: dict[str, str] | None = None  # key -> "scalar" | "nested"
 
@@ -192,7 +204,7 @@ def _analyze_flattenable(
         if canonical_shape is None:
             canonical_shape = {}
             for k in keys:
-                if ">" in k:
+                if k == "" or ">" in k:  # empty/">" -> ambiguous path (SPEC 7.4.6.1.3)
                     return None
                 val = v[k]
                 if isinstance(val, list):
@@ -272,8 +284,53 @@ def _resolve_key_chain(item: Any, keys: list[str]) -> tuple[Any, bool]:
     return current, True
 
 
+# ── Keyed map encoding (SPEC 7.2a) ───────────────────────────────────────
+
+
+def _keyed_header_prefix(name: str, named: bool, depth: int) -> str:
+    """Build the keyed-table header prefix up to the count bracket. named
+    distinguishes an anonymous root keyed map (`## `) from a named member whose
+    name may itself be the empty string (`## ""`), which format_key quotes so it
+    round-trips as a distinct level rather than collapsing into the anonymous
+    root form (SPEC 7.2a.1)."""
+    prefix = _indent(depth)
+    if not named:
+        return f"{prefix}## "
+    return f"{prefix}## {format_key(name)} "
+
+
+def _encode_keyed_map(
+    name: str, named: bool, keys: list[str], values: list[Any],
+    value_fields: list[str], key_label: str, out: list[str], depth: int, opts: GenericOptions
+) -> None:
+    """Emit a keyed table for a map of objects. Routes through _encode_tabular
+    with the keyed bracket so nested-value handling (flatten/inline/attachment/
+    null/absent) is inherited unchanged. name is empty for a root/anonymous map."""
+    _encode_keyed_map_with_prefix(
+        _keyed_header_prefix(name, named, depth), keys, values,
+        value_fields, key_label, out, depth, opts,
+    )
+
+
+def _encode_keyed_map_with_prefix(
+    header_prefix: str, keys: list[str], values: list[Any],
+    value_fields: list[str], key_label: str, out: list[str], depth: int, opts: GenericOptions
+) -> None:
+    """Emit `<header_prefix>[N:]{...}` and the keyed rows, reusing _encode_tabular.
+    Each value object is augmented with the key column and encoded as a tabular
+    row; the key column is declared first."""
+    fields = [key_label] + value_fields
+    arr: list[dict] = []
+    for k, v in zip(keys, values):
+        aug = dict(v)
+        aug[key_label] = k
+        arr.append(aug)
+    _encode_tabular(header_prefix, arr, fields, out, depth, opts, keyed=True)
+
+
 def _encode_tabular(
-    header_prefix: str, arr: list[dict], fields: list[str], out: list[str], depth: int, opts: GenericOptions
+    header_prefix: str, arr: list[dict], fields: list[str], out: list[str], depth: int,
+    opts: GenericOptions, keyed: bool = False
 ) -> None:
     prefix = _indent(depth)
 
@@ -320,7 +377,8 @@ def _encode_tabular(
             shared_arr_schemas[f] = sas
 
     header_fields = ",".join(col["header"] for col in columns)
-    out.append(f"{header_prefix}[{len(arr)}]{{{header_fields}}}")
+    br = ":]" if keyed else "]"
+    out.append(f"{header_prefix}[{len(arr)}{br}{{{header_fields}}}")
 
     for i, item in enumerate(arr):
         cells: list[str] = []
@@ -401,8 +459,15 @@ def _encode_tabular(
                 else:
                     _encode_attachment_array(prefix, fk, att_val, out, depth + 2, opts)
             elif isinstance(att_val, dict):
-                out.append(f"{prefix}.{fk} {{}}")
-                _encode_object(att_val, out, depth + 2, opts)
+                km = keyed_map_eligible(att_val)
+                if km is not None:
+                    keys, values, value_fields, key_label = km
+                    _encode_keyed_map_with_prefix(
+                        f"{prefix}.{fk} ", keys, values, value_fields, key_label, out, depth + 2, opts,
+                    )
+                else:
+                    out.append(f"{prefix}.{fk} {{}}")
+                    _encode_object(att_val, out, depth + 2, opts)
             else:
                 # Scalar attachment (e.g. field names containing ">").
                 if att_val is None:
@@ -467,6 +532,13 @@ def _encode_expanded(header_prefix: str, arr: list, out: list[str], depth: int,
     out.append(f"{header_prefix}[{len(arr)}]")
     for i, item in enumerate(arr):
         if isinstance(item, dict):
+            km = keyed_map_eligible(item)
+            if km is not None:
+                keys, values, value_fields, key_label = km
+                _encode_keyed_map_with_prefix(
+                    f"{prefix}@{i} ", keys, values, value_fields, key_label, out, depth + 1, opts,
+                )
+                continue
             out.append(f"{prefix}@{i} {{}}")
             _encode_object(item, out, depth + 1, opts)
         elif isinstance(item, list):

{gcf_python-2.4.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: