feat(context): add opt-in GCF compression as a drop-in alternative to TOON - #83
Merged
veerareddyvishal144 merged 3 commits intoJul 17, 2026
Conversation
… TOON Adds a GCF (Graph Compact Format) encoder for the large-JSON context compression Lynkr already does with TOON. Same adapter contract as src/context/toon.js: encode-only, fail-open, read-only context, never touches tool-protocol payloads. Only the encoder differs. - Off by default (GCF_ENABLED=false); takes precedence over TOON when on. - Round-trip verify (GCF_VERIFY, default on): decodes each encoding and keeps the original JSON unless it reproduces the input exactly, making the compression provably lossless per payload. - Never-grow guard using the target model's token count, with a byte fast-path to skip tokenizing on the hot path. - Config mirrors TOON_*: GCF_ENABLED, GCF_MIN_BYTES, GCF_FAIL_OPEN, GCF_LOG_STATS, GCF_VERIFY. - @blackwell-systems/gcf: MIT, zero runtime deps. Tests: test/gcf-compression.test.js (6 cases: disabled no-op, fail-open, never-grow, verify-mismatch, protocol-field preservation, text-block compression).
Contributor
|
@blackwell-systems Hi |
Contributor
Author
|
Thanks! Just pushed the |
Contributor
|
Thank you I shall merge this PR |
vishalveerareddy123
pushed a commit
that referenced
this pull request
Jul 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds GCF (Graph Compact Format) as an opt-in alternative to the TOON encoder Lynkr already uses for large-JSON context compression. Same contract as the TOON adapter (encode-only, fail-open, read-only context, never touches tool-protocol payloads); only the encoder differs. Off by default (
GCF_ENABLED=false); takes precedence over TOON when enabled.Two reasons to offer it as an option:
1. Correctness — GCF is lossless by design, and this PR verifies it per payload. TOON's round-trip is not guaranteed. A 100k-case fuzz of the reference
@toon-format/toonshows a 7.47% round-trip failure rate — 1.73% of it silent data corruption (wrong value, no error thrown), the rest decode crashes. The failing inputs are deeply-nested / ragged structures; flat uniform records round-trip clean. Lynkr's compressor doesn't constrain payload shape and currently does no round-trip check, so a silent corruption on a nested payload would reach the model undetected. This adapter addsGCF_VERIFY(default on): it decodes each encoding and keeps the original JSON unless it reproduces the input exactly.Reproduce:
eval/toon-fuzz.mjs· 10M-case log2. Compression — ties TOON on flat records, wins on nested. TOON re-declares a nested object's schema per row, so on nested tool results it can encode larger than minified JSON; GCF path-flattens. Benchmark (50-record payloads, o200k, GCF round-trip verified):
{id,label,value}meta+metricsSafety: opt-in, mutually exclusive with TOON, fail-open (keeps JSON if the encoder is missing/throws), never-grow guard (keeps JSON unless the target model's token count actually drops), and the round-trip verify above.
@blackwell-systems/gcfis MIT with zero runtime deps.Config (mirrors
TOON_*):GCF_ENABLED,GCF_MIN_BYTES,GCF_FAIL_OPEN,GCF_LOG_STATS,GCF_VERIFY.In production elsewhere: GCF ships as an opt-in format in Chrome DevTools MCP, is vendored into OmniRoute's headroom compression engine, replaced TOON in NetClaw, and was merged into Speakeasy's
oq. Full list: gcformat.com/ecosystem/adopters.Format + research: spec and playground at gcformat.com (vs-TOON, benchmarks); the format and its underlying tokenizer/attention research are documented in the whitepaper (DOI 10.5281/zenodo.20579817, attention papers linked therein).
Future — delta encoding (phase 2, not in this PR): across turns in a session Lynkr re-sends overlapping structured context; GCF's generic delta profile encodes only changed rows between turns (keyed row diff, content-addressed), which neither JSON nor TOON can do. Lynkr already tracks sessions, so this state could hang off the existing session model. This PR is the stateless foundation a delta layer would build on.
This is opt-in and additive — TOON stays the default and is untouched, GCF only activates behind
GCF_ENABLED. Happy to adjust the design, flag names, defaults, or scope to fit the project's conventions.