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

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

@@ -1,5 +1,43 @@
 # Changelog
 
+## 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
+
+- 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 +56,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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gcf-python
-Version: 2.3.0
+Version: 2.5.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/
@@ -24,15 +24,39 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 
 <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>
+  <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">
+  <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.
+
+<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.
 
-**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.**
+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)
 
@@ -105,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
 
@@ -119,7 +143,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 +155,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.
@@ -250,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 |
 |---|---|---|---|
@@ -280,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.3.0 → gcf_python-2.5.0}/README.md

@@ -1,13 +1,37 @@
 <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>
+  <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">
+  <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.
+
+<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.
 
-**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.**
+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)
 
@@ -80,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
 
@@ -94,7 +118,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 +130,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.
@@ -225,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 |
 |---|---|---|---|
@@ -255,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.3.0 → gcf_python-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gcf-python"
-version = "2.3.0"
+version = "2.5.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.5.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.5.0}/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)
 
@@ -134,7 +135,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)
@@ -177,7 +178,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
 
 
@@ -226,10 +234,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
 
@@ -252,6 +274,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)
@@ -260,6 +284,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
@@ -521,6 +566,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 +591,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("["):
@@ -613,8 +671,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:
@@ -625,10 +697,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)
 
@@ -725,7 +793,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