gcf-python 2.4.0__py3-none-any.whl → 2.5.1__py3-none-any.whl

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/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/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/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:

gcf/keyed_map.py

@@ -0,0 +1,86 @@
+"""GCF keyed-tabular map encoding (SPEC 7.2a).
+
+A JSON object whose values are all objects forming a losslessly-tabular set is
+encoded as a keyed table `## [N:]{key,...}`: the shared value fields are declared
+once in a header and each member is one positional row prefixed by its key. This
+is the object-valued analogue of Section 7.4 tabular array encoding. It is
+canonical (default-on): eligible maps always encode as keyed tables, with no
+option to disable.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def keyed_map_eligible(m: Any) -> tuple[list[str], list[Any], list[str], str] | None:
+    """Report whether an object is a keyed map of objects that should render as a
+    keyed table `## [N:]{key,...}` (SPEC 7.2a.1). Returns the ordered member keys,
+    the corresponding value objects, the ordered value-field union, and the
+    key-column label, or None when the object is not eligible.
+    """
+    if not isinstance(m, dict):
+        return None
+
+    keys = list(m.keys())
+    values = [m[k] for k in keys]
+
+    # A keyed map requires at least two members: the form factors the shared value
+    # fields into one header, which only pays off across multiple members. A
+    # single-member map yields a one-row table the same size as a section, so keying
+    # it would change canonical output for every nested single-member object (e.g.
+    # `{"data": {...}}` wrappers) with no benefit. Single-member objects use ordinary
+    # encoding; a single-key wrapper of a multi-member map therefore defers, and the
+    # inner map is keyed at its own level (SPEC 7.2a.1).
+    if len(keys) < 2:
+        return None
+
+    # Every value must be an object; build the ordered field union.
+    seen: set[str] = set()
+    value_fields: list[str] = []
+    for v in values:
+        if not isinstance(v, dict):
+            return None  # non-object value
+        for f in v:
+            if f not in seen:
+                seen.add(f)
+                value_fields.append(f)
+    if not value_fields:
+        return None  # all-empty value objects
+
+    # A keyed header needs at least one value field that can be a tabular column.
+    # A field name containing ">" cannot be a column (SPEC 7.4.6.1.4); if every
+    # value field contains ">", the keyed form would have only the key column,
+    # which is invalid. Such a map uses Section 7.2 section encoding instead, the
+    # object analogue of an array falling back to expanded form.
+    if not any(">" not in f for f in value_fields):
+        return None
+
+    # Key-column label: "key", made unique by prepending "_" on collision.
+    key_label = "key"
+    while key_label in seen:
+        key_label = "_" + key_label
+
+    return keys, values, value_fields, key_label
+
+
+def keyed_rows_to_map(rows: list[Any], fields: list[str]) -> dict[str, Any]:
+    """Reconstruct the map from decoded keyed-table rows: the first declared field
+    is the member key; the remaining fields form the value object (SPEC 7.2a.4).
+    """
+    if len(fields) < 2:
+        raise ValueError("keyed_map: header must declare at least two fields")
+    key_label = fields[0]
+    out: dict[str, Any] = {}
+    for r in rows:
+        if not isinstance(r, dict):
+            raise ValueError("keyed_map: row is not an object")
+        if key_label not in r:
+            raise ValueError(f"keyed_map: row missing key column {key_label!r}")
+        kv = r[key_label]
+        ks = kv if isinstance(kv, str) else str(kv)
+        if ks in out:
+            raise ValueError(f"keyed_map: duplicate member key {ks!r}")
+        value = {k: v for k, v in r.items() if k != key_label}
+        out[ks] = value
+    return out

gcf/scalar.py

@@ -6,10 +6,13 @@ import math
 import re
 from typing import Any
 
-_JSON_NUMBER_RE = re.compile(r"^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$")
+# \Z (end of string), not $, so a trailing newline does not count as the end:
+# in Python $ also matches just before a final \n, which would misclassify a
+# string like "5\n" as a number or "W\n" as a bare key and break round-trip.
+_JSON_NUMBER_RE = re.compile(r"^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?\Z")
 _NUMERIC_LIKE_RE = re.compile(r"^[+-]\.?\d|^\.\d|^0\d")
 _INLINE_ARRAY_RE = re.compile(r"\[[^\]]*\]\s*:")
-_BARE_KEY_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+_BARE_KEY_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*\Z")
 
 
 class _Missing:
@@ -29,6 +32,10 @@ def needs_quote(s: str) -> bool:
         return True
     if s in ("-", "~", "^", "true", "false"):
         return True
+    # A value shaped like an inline-schema attachment marker (^{...}) would decode
+    # as an attachment and lose the string, so it must be quoted (SPEC 2.4).
+    if len(s) >= 3 and s[0] == "^" and s[1] == "{" and s[-1] == "}":
+        return True
     if _JSON_NUMBER_RE.match(s):
         return True
     if _NUMERIC_LIKE_RE.match(s):
@@ -99,7 +106,8 @@ def format_number(f: float) -> str:
     if math.isinf(f):
         return "0"
     if f == 0.0:
-        return "-0" if math.copysign(1.0, f) < 0 else "0"
+        # Negative zero canonicalizes to 0 (SPEC 2.3.1): -0.0 equals 0.0 by value.
+        return "0"
     a = abs(f)
     if 1e-6 <= a < 1e21:
         # Use repr for shortest round-trippable form.

gcf/stream_generic.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import threading
 
-from .scalar import format_scalar
+from .scalar import format_scalar, format_key
 from typing import Any, Sequence
 
 
@@ -29,15 +29,52 @@ class GenericStreamEncoder:
         self._lock = threading.Lock()
         self._sections: list[tuple[str, int]] = []
         self._current: dict[str, Any] | None = None
+        self._err: Exception | None = None
+        self._w.write("GCF profile=generic\n")
 
     def begin_array(self, name: str, fields: Sequence[str]) -> None:
         """Start a tabular array section with deferred count [?]."""
         with self._lock:
+            if self._err is not None:
+                return
             if self._current is not None:
                 self._end_array_locked()
-            self._w.write(f"## {name} [?]{{{','.join(fields)}}}\n")
+            # A streaming tabular row has only flat columns; a field name containing
+            # ">" is a flattened path the stream cannot represent (SPEC 8.3, 7.4.6).
+            # Record the error and surface it at close().
+            for f in fields:
+                if ">" in f:
+                    self._err = ValueError(
+                        f"streaming field name {f!r} contains '>' "
+                        "(a flattened path is not representable in a streaming row)"
+                    )
+                    return
+            self._w.write(f"## {format_key(name)} [?]{{{_format_field_decl(fields)}}}\n")
             self._current = {"name": name, "fields": list(fields), "count": 0}
 
+    def begin_keyed_map(self, name: str, key_label: str, value_fields: Sequence[str]) -> None:
+        """Start a keyed-map section with deferred count [?:] (SPEC 7.2a).
+
+        key_label is the key column; value_fields are the value-object fields.
+        Each write_row value slice is [key_value, *value_fields]."""
+        with self._lock:
+            if self._err is not None:
+                return
+            if self._current is not None:
+                self._end_array_locked()
+            # A streaming value field name containing ">" is a flattened path a
+            # stream cannot represent (SPEC 8.3, 7.4.6). Record and surface at close().
+            for f in value_fields:
+                if ">" in f:
+                    self._err = ValueError(
+                        f"streaming field name {f!r} contains '>' "
+                        "(a flattened path is not representable in a streaming row)"
+                    )
+                    return
+            fields = [key_label] + list(value_fields)
+            self._w.write(f"## {format_key(name)} [?:]{{{_format_field_decl(fields)}}}\n")
+            self._current = {"name": name, "fields": fields, "count": 0}
+
     def write_row(self, values: Sequence[Any]) -> None:
         """Emit a single pipe-separated row immediately."""
         with self._lock:
@@ -71,8 +108,14 @@ class GenericStreamEncoder:
             self._w.write(f"{name}[{len(values)}]: {','.join(parts)}\n")
 
     def close(self) -> None:
-        """Emit the ##! summary trailer with final counts."""
+        """Emit the ##! summary trailer with final counts.
+
+        Raises any error recorded during encoding (e.g. a field name containing
+        ">", which is not representable in a flat streaming row per SPEC 8.3).
+        """
         with self._lock:
+            if self._err is not None:
+                raise self._err
             if self._current is not None:
                 self._end_array_locked()
             if not self._sections:
@@ -87,5 +130,13 @@ class GenericStreamEncoder:
         self._current = None
 
 
+def _format_field_decl(fields: Sequence[str]) -> str:
+    """Quote each field name per Section 2.4 (via format_key), matching the
+    buffered tabular header. The streaming header previously joined field names
+    raw, so a name containing a delimiter or quote produced an invalid or
+    ambiguous field declaration (SPEC 8.3)."""
+    return ",".join(format_key(f) for f in fields)
+
+
 def _format_value(v: Any) -> str:
     return format_scalar(v, "|")

{gcf_python-2.4.0.dist-info → gcf_python-2.5.1.dist-info}/METADATA

@@ -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.5.1.dist-info/RECORD

@@ -0,0 +1,22 @@
+gcf/__init__.py,sha256=dZkdcjbG-dcolg_7TBROjRq3opftDGU423ankMIOhyA,2616
+gcf/__main__.py,sha256=EpvBz1yc8H0D5OJ1zy2tYke-kRzvudKa4DEbfeW14ao,71
+gcf/cli.py,sha256=UEe1CAZn-rKGNIo_ap8-oez3ucl6DSRbsdv6RDnzygY,5256
+gcf/constants.py,sha256=cmZ8YJSOB0im_eyfN8v4UvrLpBC6Fuf4cfcKZGbutxY,638
+gcf/decode.py,sha256=TP58_7UBhfeI0o9zpNgtQvAnLQGhNt0RaUjku7Ke75A,7162
+gcf/decode_generic.py,sha256=OTNhryeAFfE5izpP6dD0DtBzcC_Jht1-vLg51gjnZ28,30510
+gcf/delta.py,sha256=oviQ9WsDRYXPXE8bw6SFutmzMRIvu-U_Zzw-39Nd5Ic,8053
+gcf/encode.py,sha256=OYGDyF3oP2I8Y2PrPL_5yDVURqB0mghtqlOGyDEd-Fs,4081
+gcf/generic.py,sha256=1c53utF2GcD8lS_wks2opQw08hMz4KGL-7C8g7JB5bA,21577
+gcf/generic_delta.py,sha256=5KSUT_QUeH7OILLWfu9JveaXRSrqRIi3c6E8WjlgC4Q,18785
+gcf/keyed_map.py,sha256=qCwhehXB1FQ2iYCPhcvXOqGwrVqdXhGYZGxv56CSUgc,3644
+gcf/packroot.py,sha256=0rZY7TEVcLzA8XhoIOc6_g9lbRCn-MUr54YTRVhzsO4,2019
+gcf/scalar.py,sha256=NMf-ZJzTOGk1JLvydqYPRxUH80u2Sr_bonwRHXTYd5U,9856
+gcf/session.py,sha256=rPqR4xsHKpi_G37t1ODwkTUdHhVAGa3Uig8F60h34Ms,5335
+gcf/stream.py,sha256=3eyzmLMZPyEGC1MS9pujxio2x_t7rCL-eNuJ4DjYkaA,5938
+gcf/stream_generic.py,sha256=h2mJ-jI-c1H2L0uoQVhrvDc7uJEcOwS1MB51k4SCPNM,5775
+gcf/types.py,sha256=AWm-LQoSqLHAYtEjcAxWQZqJ4JXqNreLUKO2mJFgNMA,1465
+gcf_python-2.5.1.dist-info/METADATA,sha256=1qFB-VBVxd0CX6s0k5WprCNE2BoYE4cFu_T5PJ5ptZQ,16068
+gcf_python-2.5.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+gcf_python-2.5.1.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
+gcf_python-2.5.1.dist-info/licenses/LICENSE,sha256=2Fit9wnaIe--RMSAgyQqxC5hfZTyZqn4fIdBtp9qPDw,1072
+gcf_python-2.5.1.dist-info/RECORD,,

gcf_python-2.4.0.dist-info/RECORD

@@ -1,21 +0,0 @@
-gcf/__init__.py,sha256=dZkdcjbG-dcolg_7TBROjRq3opftDGU423ankMIOhyA,2616
-gcf/__main__.py,sha256=EpvBz1yc8H0D5OJ1zy2tYke-kRzvudKa4DEbfeW14ao,71
-gcf/cli.py,sha256=UEe1CAZn-rKGNIo_ap8-oez3ucl6DSRbsdv6RDnzygY,5256
-gcf/constants.py,sha256=cmZ8YJSOB0im_eyfN8v4UvrLpBC6Fuf4cfcKZGbutxY,638
-gcf/decode.py,sha256=nD8bXYhoeHQQ3LCeAJQOAgFuob-V_6us4mcBYtL_bBc,5978
-gcf/decode_generic.py,sha256=ozYmGiZu9S1zTGsN1PuMTF8soV53eq1v5PXMx2YNgWQ,27888
-gcf/delta.py,sha256=oviQ9WsDRYXPXE8bw6SFutmzMRIvu-U_Zzw-39Nd5Ic,8053
-gcf/encode.py,sha256=OYGDyF3oP2I8Y2PrPL_5yDVURqB0mghtqlOGyDEd-Fs,4081
-gcf/generic.py,sha256=t0Px1fAoWsmFFeICbL65LL8UTGFfnbh4PCanvMMKqYs,18198
-gcf/generic_delta.py,sha256=GU7CNumz3PQhC0Xs5pO30Nb3ACvSorHEQMu-4kazpFM,17838
-gcf/packroot.py,sha256=0rZY7TEVcLzA8XhoIOc6_g9lbRCn-MUr54YTRVhzsO4,2019
-gcf/scalar.py,sha256=MZay-KIROvaFHet-g2-pBghahT1bf_5bxZjG4yTZkSo,9329
-gcf/session.py,sha256=rPqR4xsHKpi_G37t1ODwkTUdHhVAGa3Uig8F60h34Ms,5335
-gcf/stream.py,sha256=3eyzmLMZPyEGC1MS9pujxio2x_t7rCL-eNuJ4DjYkaA,5938
-gcf/stream_generic.py,sha256=RnqqiPSu5joJa-7e58QbbzSGfvxBICA587A3aArjZvE,3250
-gcf/types.py,sha256=AWm-LQoSqLHAYtEjcAxWQZqJ4JXqNreLUKO2mJFgNMA,1465
-gcf_python-2.4.0.dist-info/METADATA,sha256=xDum3Ytd_7KX6SP8940MQDWL08VAwmbdkQuc-nkzN6M,13115
-gcf_python-2.4.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-gcf_python-2.4.0.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
-gcf_python-2.4.0.dist-info/licenses/LICENSE,sha256=2Fit9wnaIe--RMSAgyQqxC5hfZTyZqn4fIdBtp9qPDw,1072
-gcf_python-2.4.0.dist-info/RECORD,,