Fix

• Graph StreamEncoder now emits ##! summary trailer (was still using old ## _summary format from v1.4)

Install

go get github.com/blackwell-systems/gcf-go@v1.0.1

Reference implementation for GCF SPEC v2.0 Stable

133 conformance fixtures passing. 80M property-based round-trips with zero failures. 7.9M fuzz executions, 3 bugs found and fixed. Cross-language conformance matrix verified.

New

• scalar.go: common scalar grammar (quoting, escaping, parsing, number formatting)
• orderedmap.go: OrderedMap type preserving JSON key insertion order
• ParseJSONOrdered: ordered JSON parser for conformance-grade encoding
• Property-based round-trip tests (configurable via GCF_ITERATIONS env var)
• Fuzz targets for encoder and decoder with saved crash regression cases
• Conformance test runner for 133 fixtures
• Cross-language encode/decode matrix verification

Breaking changes from v0.6.0

• EncodeGeneric emits GCF profile=generic header
• DecodeGeneric requires GCF profile= header
• Strings colliding with typed literals are quoted ("true", "123", "-")
• Full JSON string escaping (\b, \f, \n, \r, \t, \uXXXX, surrogate pairs)
• Full JSON number grammar with exponent notation
• - for null, ~ for absent fields, ^ for nested attachments
• ##! summary trailer replaces ## _summary
• Graph encoder emits profile=graph, sorts symbols by score descending
• Graph encoder assigns IDs after sorting (sequential in output order)
• Session encoder uses session-stable IDs across calls

Lossless round-trip invariant

decodeGeneric(encodeGeneric(value)) == value for every JSON value. Proven by:

• 80M random and adversarial round-trips
• 7.9M fuzz executions (3 bugs found and fixed: negative zero, large integer precision, quoted brace in field declarations)
• Structural proof by construction (scalar injectivity + container injectivity)

Install

go get github.com/blackwell-systems/gcf-go@v1.0.0

What's new

Updated all documentation with multi-model benchmark data:

• 1,300+ LLM evaluations across 10 models, 3 providers, and 51 independent test runs
• 90.5% average comprehension accuracy (four models hit 100%: Sonnet, Gemini 2.5 Pro, Gemini 3.1 Pro, Gemini 3.5 Flash)
• 5/5 generation validity on every frontier model from Anthropic, OpenAI, and Google
• TOON's official decoder rejects LLM-generated output on 7 of 9 models tested
• GCF wins all 6 datasets on TOON's own benchmark
• Eval README updated (23 comprehension runs, 10 models, 3 providers)

Full benchmarks: https://gcformat.com/guide/benchmarks.html

CLI binaries (optional)

The attached binaries are the gcf CLI tool (gcf encode, gcf decode, gcf stats). These are optional. If you're using GCF as a Go library, you only need go get github.com/blackwell-systems/gcf-go. The CLI is for people who want to convert files from the command line without writing code.

What's new

DecodeGeneric

Parse any GCF text back to native Go values. Works with both generic profile and graph profile payloads. Full round-trip: EncodeGeneric -> GCF -> DecodeGeneric.

result, err := gcf.DecodeGeneric(gcfText)
// Returns map[string]any, []any, or primitives

GenericStreamEncoder

Zero-buffering streaming encoder for the generic profile. Write rows as data arrives with O(1) memory per row.

enc := gcf.NewGenericStreamEncoder(w)
enc.BeginArray("users", []string{"name", "email", "role"})
enc.WriteRow([]any{"alice", "alice@co.com", "admin"})
enc.WriteRow([]any{"bob", "bob@co.com", "user"})
enc.EndArray()
enc.Close() // emits ## _summary trailer

Also in this release

• Repositioned as drop-in JSON replacement for AI pipelines
• Multi-model eval: 12 runs across 6 models, GCF wins 11, ties 1

Full changelog: v0.5.0...v0.6.0

Streaming Encode (zero-buffering)

True input-side streaming for MCP servers that walk large graphs, paginate APIs, or read database cursors. Rows emit the instant they are produced with O(1) memory per row.

New API

Example

enc := gcf.NewStreamEncoder(w, "context_for_task", gcf.StreamOptions{TokenBudget: 5000})
enc.WriteSymbol(gcf.Symbol{QualifiedName: "pkg.Auth", Kind: "function", Score: 0.95, Provenance: "lsp", Distance: 0})
enc.WriteSymbol(gcf.Symbol{QualifiedName: "pkg.Server", Kind: "function", Score: 0.60, Provenance: "lsp", Distance: 1})
enc.WriteEdge(gcf.Edge{Source: "pkg.Server", Target: "pkg.Auth", EdgeType: "calls"})
enc.Close()

Output

GCF tool=context_for_task budget=5000
## targets
@0 fn pkg.Auth 0.95 lsp
## related
@1 fn pkg.Server 0.60 lsp
## edges [?]
@0<@1 calls
## _summary symbols=2 edges=1 sections=targets:1,related:1,edges:1

Design

• [?] deferred count marker: signals count will be in trailer
• ## _summary trailer: provides symbols, edges, and per-section counts after data
• Backward compatible: standard Decode() handles streaming output with no changes
• Thread-safe: concurrent WriteSymbol/WriteEdge calls are safe

Why this matters

MCP servers that buffer entire graph traversals before responding force the LLM to wait seconds seeing nothing. With streaming encode, the first symbols arrive in milliseconds. The server never buffers more than one record at a time.

TOON cannot do this. Their spec mandates [N] upfront with no deferred count or trailer mechanism. Their encodeLines() is output-side streaming only (value already fully in memory).

EncodeGeneric: primitive arrays inlined as name[N]: val1,val2,val3. Eliminates TOON's last benchmark win.

Full Changelog: v0.3.0...v0.4.0

Breaking changes

• Encode() now emits edges=N in header line
• Encode() now emits ## edges [N] section header (was ## edges)

Other

• Decode() updated to parse ## edges [N] format
• EncodeWithSession() updated to emit new format
• Comprehension eval expanded to 13 questions, achieves 13/13

Full Changelog: v0.1.2...v0.3.0

Fixed

• Decoder rejects headers missing required tool field (conformance)

Full Changelog: v0.1.1...v0.1.2

Added

• EncodeGeneric(data any) string: encode arbitrary Go values (maps, slices, structs) into GCF tabular format
• Tabular encoding: positional rows with pipe separators, section headers, nested field support
• Uniform array detection with 70% key overlap threshold

Fixed

• gofmt formatting on test files

Full Changelog: v0.1.0...v0.1.1

GCF v0.1.0

Token-optimized wire format for LLM tool responses. First stable release.

What's included

• Encode/Decode: Full GCF round-trip (Payload, Symbol, Edge types)
• Session deduplication: 92.7% token savings by 5th call in a conversation
• Delta encoding: 81.2% savings on re-queries where context changed slightly
• CLI: gcf encode, gcf decode, gcf stats commands
• 16 kind abbreviations: function→fn, interface→iface, etc.
• Thread-safe Session type

Performance

• 84% fewer tokens than JSON
• 34% fewer tokens than TOON (on TOON's own benchmark)
• 100% LLM comprehension accuracy at 500 symbols (JSON: 66.7%)

Install

go install github.com/blackwell-systems/gcf-go/cmd/gcf@v0.1.0

Or download a binary below.

Also available

• TypeScript: npm install @blackwell-systems/gcf
• Python: pip install gcf-py
• Docs: https://blackwell-systems.github.io/gcf/
• Spec: https://github.com/blackwell-systems/gcf