Spec v3.1.1

Patch release. Clarifies encoder quoting rules in Section 2.4 for edge cases involving bracket-colon patterns in string values. Conformance fixture added.

v3.1.0

Spec v3.1.0

Spec change

tool field is now optional in the graph profile header. Previously required, now SHOULD be present for MCP tool responses but is not enforced. This enables non-MCP use cases (Neo4j queries, knowledge graphs, ontologies, agent memory) without inventing a tool name.

Conformance

• 157 fixtures (was 156): added graph-decode/003_no_tool_field.json, removed errors-v2/022_missing_graph_tool.json
• All 6 implementations at full conformance (157/157)
• 23.25B+ round-trips verified across 6 languages, zero failures:

Language	Round-trips	Status
Rust	23,000,000,000+	PASS
Go	200,000,000	PASS
TypeScript	20,000,000	PASS
Swift	20,000,000	PASS
Python	10,000,000	PASS
Kotlin	10,000,000	PASS

Bug fixes (all 6 implementations)

• Quote strings containing commas in scalar values
• Decode v2-format indented attachments in tabular rows
• Reject duplicate attachments on the same row
• Reject orphan attachments on rows without ^ cells

Playground

• Multi-format support: compare tab now accepts JSON, YAML, and TOML input
• TOON error state: TOON column shows red error panel for non-JSON inputs (TOON cannot encode YAML, TOML, or CSV)
• Encode tab: accepts JSON, YAML, TOML, CSV, and MessagePack (base64) input
• Decode tab: outputs as JSON, YAML, TOML, CSV, or MessagePack (base64)
• Presets for all formats including MessagePack binary data

Upgrade

All 6 implementations are releasing v2.1.0 with these changes. Drop-in upgrade, no breaking changes.

• Go: go get github.com/blackwell-systems/gcf-go@v1.2.0
• Rust: gcf = "2.1.0" in Cargo.toml
• TypeScript: npm install @blackwell-systems/gcf@2.1.0
• Python: pip install gcf==2.1.0
• Swift: update package dependency to 2.1.0
• Kotlin: update JitPack dependency to 2.1.0

GCF Specification v3.0.0: Inline Schema Encoding

Inline Schema Encoding

The single largest token efficiency improvement since GCF's initial release. Nested objects with 3+ scalar fields are now encoded positionally with a one-time schema declaration.

Before (v2):

## orders [2]{id,total,customer}
@0 1|99.99|^
  .customer {}
    name=Alice
    email=alice@test.com
    tier=premium

After (v3):

## orders [2]{id,total,customer}
@0 1|99.99|^{name,email,tier}
Alice|alice@test.com|premium
@1 2|49.99|^
Bob|bob@test.com|standard

Breaking Changes

• Attachment lines no longer indented (same depth as parent row)
• Inline object fields use positional encoding without field-name prefix
• Objects with 3+ scalar fields encoded with ^{fields} inline schema
• No backwards compatibility with v2 indented attachments

New Features

• Inline object schema: first row declares field order with ^{fields}, subsequent rows use bare ^
• Shared array schemas: identical nested arrays omit {fields} after first row
• MinInlineFields=3: threshold prevents overhead on small objects
• 15 new conformance fixtures, 156 total

Numbers

Metric	Value
Comprehension (standard workloads)	100% on every frontier model
Comprehension (code graphs)	90.7% (vs TOON 68.5%, JSON 53.6%)
Token efficiency (15 datasets)	-25.5% vs TOON, -53% vs JSON
Fuzz iterations	1.006 billion, zero failures
Scale test (1000 orders)	GCF fits (47K), JSON impossible (161K)
LLM evaluations	1,700+ across 10+ models, 3 providers
Implementations	6 languages, all passing

Migration

encodeGeneric / encode_generic now produces v3 output. Decoders accept v3 only (no v2 indented attachment fallback).

Libraries: Go (v1.1.0), TypeScript (v2.0.0), Python (v2.0.0), Kotlin (v2.0.0), Rust (v2.0.0), Swift (v2.0.0)

GCF Specification v2.0

Specification v2.0

Lossless generic profile rewrite addressing 11 correctness findings. This is the real v1 baseline; prior versions (v1.0-v1.4) are considered pre-stable development.

Breaking changes

• Mandatory GCF profile=generic / GCF profile=graph header
• Scalar quoting obligation: strings colliding with typed literals must be quoted
• Full JSON string escaping (\b, \f, \n, \r, \t, \uXXXX, surrogate pairs)
• Full JSON number grammar with exponent notation
• Null (-) vs missing (~) distinction in tabular rows
• ^ attachment marker for nested values in tabular rows
• Quoted keys for non-identifier key names
• Expanded per-item form with = / {} / [N] type markers
• Root scalars (=value), anonymous root arrays (## [N])
• ##! summary trailer replaces ## _summary
• Duplicate key rejection, normative indentation, count validation

Conformance

• 133 fixtures across 10 categories
• Go reference implementation passes all 133 fixtures
• 20M property-based round-trips with zero failures
• 7.9M fuzz executions with zero crashes

Status: Draft (Stable after cross-language conformance matrix passes)

v1.4

Streaming Encoding Extension (Section 6b)

• [?] deferred count marker for section headers
• ## _summary trailer provides counts after data
• Zero-buffering encode with O(1) memory per row
• Backward compatible (old decoders treat _summary as empty section)
• 5 streaming conformance fixtures (61 total)

Other changes

• Streaming guide (docs/guide/streaming.md)
• Proxy guide updated with streaming progress and roadmap
• Updated benchmark numbers across all docs

v1.3

Primitive array inlining in tabular profile. GCF now wins all 6 datasets on TOON's benchmark.

v1.2

edges [N] section header and edges=N header field

Comprehension eval showed LLMs miscounted edges because edge lines share the @ prefix with symbol lines. Adding [N] to the edges section header fixes this: GCF achieves 13/13 accuracy (was 12/13).

Changes

• edges=N field added to graph profile header
• Edge section header: ## edges [N] (e.g. ## edges [200])
• Grammar updated: group-header allows [count] without field-decl
• Encoder conformance: MUST emit edges header field and ## edges [N]
• Decoder conformance: MUST parse ## edges [N] (strip bracket suffix)
• All 11 conformance fixtures with edges updated
• Swift and Kotlin added to implementations list (6 official)