gcf-python 2.2.1__py3-none-any.whl → 2.3.0__py3-none-any.whl

gcf/__init__.py

@@ -39,6 +39,23 @@ from .decode import DecodeError, decode
 from .delta import encode_delta
 from .encode import encode
 from .generic import encode_generic, GenericOptions
+from .generic_delta import (
+    GenericSet,
+    GenericDeltaPayload,
+    generic_pack_root,
+    diff_generic_sets,
+    encode_generic_full,
+    encode_generic_delta,
+    decode_generic_full,
+    decode_generic_delta,
+    verify_generic_delta,
+    GenericDeltaSession,
+    ReanchorPolicy,
+    ReanchorMode,
+    fixed_n,
+    size_guard,
+    DEFAULT_REANCHOR_N,
+)
 from .session import Session, encode_with_session
 from .decode_generic import decode_generic
 from .stream import StreamEncoder
@@ -64,6 +81,21 @@ __all__ = [
     "encode_generic",
     "GenericOptions",
     "encode_with_session",
+    "GenericSet",
+    "GenericDeltaPayload",
+    "generic_pack_root",
+    "diff_generic_sets",
+    "encode_generic_full",
+    "encode_generic_delta",
+    "decode_generic_full",
+    "decode_generic_delta",
+    "verify_generic_delta",
+    "GenericDeltaSession",
+    "ReanchorPolicy",
+    "ReanchorMode",
+    "fixed_n",
+    "size_guard",
+    "DEFAULT_REANCHOR_N",
 ]
 
-__version__ = "1.0.0"
+__version__ = "2.3.0"

gcf/generic.py

@@ -14,8 +14,8 @@ class GenericOptions:
     no_flatten: bool = False
     """When True, disables promotion of fixed-shape nested objects to path
     columns (e.g. "customer>name"). Nested objects use attachment syntax
-    instead. Set when targeting open-weight models that show lower
-    comprehension on flattened encoding."""
+    instead. Open-weight models currently comprehend the expanded form
+    better; this gap is expected to close."""
 
 
 def encode_generic(data: Any, opts: GenericOptions | None = None) -> str:
@@ -171,7 +171,15 @@ def _analyze_flattenable(
     canonical_shape: dict[str, str] | None = None  # key -> "scalar" | "nested"
 
     for item in arr:
-        if field_name not in item or item[field_name] is None:
+        if field_name not in item:
+            continue
+        # A nested (non-top-level) null cannot be flattened losslessly: its leaves
+        # would encode as absent ("~") and unflatten back to a missing key, not None.
+        # Bail to the attachment path. A top-level None is fine (emits "-" and
+        # reconstructs via the all-null rule), so just skip the row from shape analysis.
+        if item[field_name] is None:
+            if parent_path != "":
+                return None
             continue
         v = item[field_name]
         if not isinstance(v, dict):

gcf/generic_delta.py

@@ -0,0 +1,487 @@
+"""GCF generic-profile delta encoding (SPEC Section 10a).
+
+Producer + consumer. Mirrors the gcf-go reference implementation; the shared
+conformance fixtures (generic-pack-root/, generic-delta/) hold both to identical
+bytes and hashes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from .scalar import (
+    format_key,
+    format_number,
+    format_scalar,
+    parse_scalar,
+    quote_string,
+    split_respecting_quotes,
+)
+
+
+@dataclass
+class GenericSet:
+    """A keyed record set: the unit generic-profile delta operates on (Section 10a).
+
+    Rows are order-agnostic (set semantics); ``fields`` carries the declared column
+    order for the wire form; ``key`` names the identity column (the ``@id`` / ``key=``);
+    ``name`` is the tabular section name for a full payload.
+    """
+
+    key: str
+    fields: list[str]
+    rows: list[dict[str, Any]]
+    name: str = "rows"
+
+
+@dataclass
+class GenericDeltaPayload:
+    key: str
+    fields: list[str]
+    base_root: str = ""
+    new_root: str = ""
+    added: list[dict[str, Any]] = field(default_factory=list)
+    changed: list[dict[str, Any]] = field(default_factory=list)
+    removed: list[Any] = field(default_factory=list)
+    tool: str = ""
+    delta_tokens: int = 0
+    full_tokens: int = 0
+
+
+def _canonical_cell(v: Any) -> str:
+    """Canonicalize one value for the pack-root record (Section 10a.3).
+
+    Decoupled from the wire cell encoder: collision-free and record-safe, not
+    round-trippable. Typed literals stay bare (null is ``-``, booleans true/false,
+    numbers canonical); strings are ALWAYS quoted so they cannot collide with a
+    typed literal and any tab/newline inside is escaped.
+    """
+    if v is None:
+        return "-"
+    if isinstance(v, bool):  # must precede int: bool is a subclass of int
+        return "true" if v else "false"
+    if isinstance(v, (int, float)):
+        return format_number(float(v))
+    if isinstance(v, str):
+        return quote_string(v)
+    return quote_string(str(v))
+
+
+def generic_pack_root(s: GenericSet) -> str:
+    """Canonical pack root for a keyed set (gcf-pack-root-v1, generic profile, 10a.3).
+
+    Records and fields are sorted by unsigned UTF-8 byte order to match every SDK.
+    """
+    sorted_fields = sorted(s.fields, key=lambda x: x.encode("utf-8"))
+    records: list[str] = []
+    for row in s.rows:
+        parts = ["R"]
+        for f in sorted_fields:
+            parts.append(f)
+            parts.append(_canonical_cell(row.get(f)))
+        records.append("\t".join(parts) + "\n")
+    records.sort(key=lambda r: r.encode("utf-8"))
+    digest = hashlib.sha256("".join(records).encode("utf-8")).hexdigest()
+    return "sha256:" + digest
+
+
+def _index_by_key(s: GenericSet) -> dict[str, dict[str, Any]]:
+    m: dict[str, dict[str, Any]] = {}
+    for row in s.rows:
+        ident = _canonical_cell(row.get(s.key))
+        if ident in m:
+            raise ValueError(f"delta_invalid: duplicate identity {ident} for key {s.key!r}")
+        m[ident] = row
+    return m
+
+
+def _rows_equal(a: dict[str, Any], b: dict[str, Any], fields: list[str]) -> bool:
+    return all(_canonical_cell(a.get(f)) == _canonical_cell(b.get(f)) for f in fields)
+
+
+def diff_generic_sets(base: GenericSet, nxt: GenericSet) -> GenericDeltaPayload:
+    """Compute the delta from ``base`` to ``nxt`` (the blessed producer path).
+
+    Centralizes the keyed-diff invariants: identity uniqueness, added-not-in-base,
+    changed-must-exist, whole-row replacement, unchanged rows omitted. Output is
+    sorted by identity for reproducibility (10a.6). Schema change or a missing key
+    raises (caller must send full, 10a.7).
+    """
+    if not nxt.key:
+        raise ValueError("delta_invalid: no identity key")
+    if nxt.key != base.key or list(base.fields) != list(nxt.fields):
+        raise ValueError("delta_invalid: schema change (send full)")
+
+    base_by_id = _index_by_key(base)
+    next_by_id = _index_by_key(nxt)
+
+    d = GenericDeltaPayload(
+        key=nxt.key,
+        fields=list(nxt.fields),
+        base_root=generic_pack_root(base),
+        new_root=generic_pack_root(nxt),
+    )
+    for ident, row in next_by_id.items():
+        brow = base_by_id.get(ident)
+        if brow is None:
+            d.added.append(row)
+        elif not _rows_equal(brow, row, nxt.fields):
+            d.changed.append(row)
+        # equal rows are omitted (silence = "keep it", 10a.5)
+    for ident, brow in base_by_id.items():
+        if ident not in next_by_id:
+            d.removed.append(brow.get(nxt.key))
+
+    d.added.sort(key=lambda r: _canonical_cell(r.get(d.key)))
+    d.changed.sort(key=lambda r: _canonical_cell(r.get(d.key)))
+    d.removed.sort(key=_canonical_cell)
+    return d
+
+
+def _field_decl(fields: list[str], key: str) -> str:
+    return ",".join(("@" + format_key(f)) if f == key else format_key(f) for f in fields)
+
+
+def _encode_row(row: dict[str, Any], fields: list[str]) -> str:
+    return "|".join(format_scalar(row.get(f), "|") for f in fields)
+
+
+def encode_generic_full(s: GenericSet, tool: str = "") -> str:
+    """Emit a delta-participating full base payload: key= header, @id field, rows."""
+    name = s.name or "rows"
+    header = "GCF profile=generic"
+    if tool:
+        header += f" tool={tool}"
+    header += f" pack_root={generic_pack_root(s)} key={s.key}"
+    lines = [header, f"## {name} [{len(s.rows)}]{{{_field_decl(s.fields, s.key)}}}"]
+    lines += [_encode_row(row, s.fields) for row in s.rows]
+    return "\n".join(lines) + "\n"
+
+
+def encode_generic_delta(d: GenericDeltaPayload) -> str:
+    """Serialize a delta payload (10a.2). Sections ordered added/changed/removed."""
+    header = "GCF profile=generic"
+    if d.tool:
+        header += f" tool={d.tool}"
+    header += f" delta=true base_root={d.base_root} new_root={d.new_root} key={d.key}"
+    if d.full_tokens > 0:
+        savings = 100.0 * (1.0 - d.delta_tokens / d.full_tokens)
+        header += f" savings={savings:.0f}%"
+    lines = [header]
+    if d.added:
+        lines.append(f"## added [{len(d.added)}]{{{_field_decl(d.fields, d.key)}}}")
+        lines += [_encode_row(r, d.fields) for r in d.added]
+    if d.changed:
+        lines.append(f"## changed [{len(d.changed)}]{{{_field_decl(d.fields, d.key)}}}")
+        lines += [_encode_row(r, d.fields) for r in d.changed]
+    if d.removed:
+        lines.append(f"## removed [{len(d.removed)}]{{@{d.key}}}")
+        lines += [format_scalar(idv, "|") for idv in d.removed]
+    return "\n".join(lines) + "\n"
+
+
+def verify_generic_delta(base: GenericSet, d: GenericDeltaPayload, expected_new_root: str) -> GenericSet:
+    """Apply a delta to a base set and verify the result hashes to expected_new_root.
+
+    Atomic (10a.5): the whole payload is validated before any mutation; on failure the
+    base is left untouched and a ValueError is raised.
+    """
+    if generic_pack_root(base) != d.base_root:
+        raise ValueError("base_mismatch: base root does not equal delta base_root")
+    base_by_id = _index_by_key(base)
+
+    for idv in d.removed:
+        if _canonical_cell(idv) not in base_by_id:
+            raise ValueError(f"delta_invalid: removing identity {_canonical_cell(idv)} not in base")
+    for row in d.added:
+        if _canonical_cell(row.get(d.key)) in base_by_id:
+            raise ValueError(f"delta_invalid: adding identity {_canonical_cell(row.get(d.key))} that already exists")
+    for row in d.changed:
+        if _canonical_cell(row.get(d.key)) not in base_by_id:
+            raise ValueError(f"delta_invalid: changing identity {_canonical_cell(row.get(d.key))} not in base")
+
+    work = dict(base_by_id)
+    for idv in d.removed:
+        work.pop(_canonical_cell(idv), None)
+    for row in d.added:
+        work[_canonical_cell(row.get(d.key))] = row
+    for row in d.changed:
+        work[_canonical_cell(row.get(d.key))] = row
+
+    result = GenericSet(key=base.key, fields=list(base.fields), rows=list(work.values()), name=base.name)
+    got = generic_pack_root(result)
+    if got != expected_new_root:
+        raise ValueError(f"root_mismatch: computed {got}, expected {expected_new_root}")
+    return result
+
+
+# --- consumer-side wire parsing ---
+
+
+def _parse_header_fields(header: str) -> dict[str, str]:
+    m: dict[str, str] = {}
+    for tok in header.split():
+        if "=" in tok:
+            k, _, v = tok.partition("=")
+            if k:
+                m[k] = v
+    return m
+
+
+def _parse_count(s: str) -> int:
+    if s == "0":
+        return 0
+    if not s or s[0] == "0" or not s.isdigit():
+        raise ValueError(f"invalid_count: {s}")
+    return int(s)
+
+
+def _split_delta_field_decl(decl: str) -> tuple[list[str], str]:
+    if len(decl) < 2 or decl[0] != "{" or decl[-1] != "}":
+        raise ValueError(f"invalid field declaration: {decl}")
+    inner = decl[1:-1]
+    if inner == "":
+        return [], ""
+    fields: list[str] = []
+    key_field = ""
+    for raw in split_respecting_quotes(inner, ","):
+        f = raw.strip()
+        is_key = False
+        if f.startswith("@"):
+            f = f[1:]
+            is_key = True
+        if len(f) >= 2 and f[0] == '"' and f[-1] == '"':
+            from .scalar import parse_quoted_string
+
+            f = parse_quoted_string(f)
+        if is_key:
+            key_field = f
+        fields.append(f)
+    return fields, key_field
+
+
+def _parse_section_header(content: str) -> tuple[str, int, list[str], str]:
+    bi = content.find(" [")
+    if bi < 0:
+        raise ValueError(f"delta_invalid: section header without count: {content!r}")
+    name = content[:bi].strip()
+    rest = content[bi + 1:]  # "[N]{...}"
+    if not rest or rest[0] != "[":
+        raise ValueError(f"delta_invalid: malformed section header: {content!r}")
+    close = rest.find("]")
+    if close < 0:
+        raise ValueError(f"delta_invalid: unterminated count: {content!r}")
+    count = _parse_count(rest[1:close])
+    fields, key_field = _split_delta_field_decl(rest[close + 1:])
+    return name, count, fields, key_field
+
+
+def _parse_row(line: str, fields: list[str]) -> dict[str, Any]:
+    cells = split_respecting_quotes(line, "|")
+    if len(cells) != len(fields):
+        raise ValueError(f"delta_invalid: row has {len(cells)} cells, expected {len(fields)}: {line!r}")
+    return {f: parse_scalar(cells[i], True) for i, f in enumerate(fields)}
+
+
+def decode_generic_full(text: str) -> tuple[GenericSet, str]:
+    """Parse a delta-participating full base payload into (GenericSet, pack_root)."""
+    lines = text.rstrip("\n").split("\n")
+    if not lines:
+        raise ValueError("empty payload")
+    hdr = _parse_header_fields(lines[0])
+    if hdr.get("profile") != "generic":
+        raise ValueError("not a generic payload")
+    s = GenericSet(key=hdr.get("key", ""), fields=[], rows=[])
+    i = 1
+    while i < len(lines):
+        line = lines[i]
+        if not line.startswith("## "):
+            i += 1
+            continue
+        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")
+            s.rows.append(_parse_row(lines[i], fields))
+            i += 1
+    return s, hdr.get("pack_root", "")
+
+
+def decode_generic_delta(text: str) -> GenericDeltaPayload:
+    """Parse a delta payload (10a.2) into a GenericDeltaPayload for application."""
+    lines = text.rstrip("\n").split("\n")
+    if not lines:
+        raise ValueError("empty payload")
+    hdr = _parse_header_fields(lines[0])
+    if hdr.get("profile") != "generic":
+        raise ValueError("not a generic payload")
+    if hdr.get("delta") != "true":
+        raise ValueError("not a delta payload")
+    d = GenericDeltaPayload(
+        key=hdr.get("key", ""),
+        fields=[],
+        base_root=hdr.get("base_root", ""),
+        new_root=hdr.get("new_root", ""),
+        tool=hdr.get("tool", ""),
+    )
+    i = 1
+    while i < len(lines):
+        line = lines[i]
+        if not line.startswith("## "):
+            i += 1
+            continue
+        name, count, fields, key_field = _parse_section_header(line[3:])
+        if not d.key and key_field:
+            d.key = key_field
+        if not d.fields and name in ("added", "changed"):
+            d.fields = fields
+        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}")
+                rows.append(_parse_row(lines[i], fields))
+                i += 1
+            if name == "added":
+                d.added = rows
+            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")
+                d.removed.append(parse_scalar(lines[i], True))
+                i += 1
+        else:
+            raise ValueError(f"delta_invalid: unknown delta section {name!r}")
+    return d
+
+
+# --- producer-side re-anchor session helper (SPEC Section 10a.8) ---
+#
+# GenericDeltaSession manages the re-anchor cadence for a stream of
+# generic-profile updates. It is thin sugar over the primitives: each ``next``
+# emits either a compact delta or, on its chosen cadence, a full re-anchor,
+# updating its held base. It introduces NO new wire syntax: every payload it
+# emits is exactly what ``encode_generic_full`` or ``encode_generic_delta``
+# produce, and the decoder accepts them cadence-agnostically. N and the size
+# guard are the helper's knobs; they are never wire fields. (Section 10a.8 is
+# non-normative producer policy.)
+
+
+# The working default cadence for FixedN (SPEC Section 10a.8).
+DEFAULT_REANCHOR_N = 15
+
+
+class ReanchorMode(Enum):
+    """Selects the session's cadence policy."""
+
+    FIXED_N = 0  # re-anchor every N turns
+    SIZE_GUARD = 1  # re-anchor once cumulative delta reaches the full payload's size
+
+
+@dataclass
+class ReanchorPolicy:
+    """Selects when a :class:`GenericDeltaSession` re-anchors.
+
+    Construct it with :func:`fixed_n` or :func:`size_guard`.
+    """
+
+    mode: ReanchorMode = ReanchorMode.FIXED_N
+    n: int = 0  # turns between anchors; FixedN only
+
+
+def fixed_n(n: int) -> ReanchorPolicy:
+    """Re-anchor every ``n`` turns. ``n <= 0`` falls back to ``DEFAULT_REANCHOR_N``."""
+    if n <= 0:
+        n = DEFAULT_REANCHOR_N
+    return ReanchorPolicy(mode=ReanchorMode.FIXED_N, n=n)
+
+
+def size_guard() -> ReanchorPolicy:
+    """Re-anchor once the cumulative delta bytes since the last anchor reach the
+    current full payload's byte size: it re-anchors more under heavy churn, rarely
+    under light churn, and bounds the delta spent between anchors to about one full
+    payload. Production-recommended.
+    """
+    return ReanchorPolicy(mode=ReanchorMode.SIZE_GUARD)
+
+
+def _byte_len(s: str) -> int:
+    """UTF-8 byte length, matching Go's ``len(string)`` (bytes, not code points)."""
+    return len(s.encode("utf-8"))
+
+
+class GenericDeltaSession:
+    """Holds the current base and re-anchor state for a producer loop.
+
+    Not safe for concurrent use. Call :meth:`current_full` to get the initial
+    full payload to transmit, then :meth:`next` for each subsequent state.
+    """
+
+    def __init__(self, base: GenericSet, tool: str, policy: ReanchorPolicy) -> None:
+        if policy.mode == ReanchorMode.FIXED_N and policy.n <= 0:
+            policy = ReanchorPolicy(mode=policy.mode, n=DEFAULT_REANCHOR_N)
+        self._base = base
+        self._tool = tool
+        self._policy = policy
+        self._turn = 0
+        self._cum = 0  # cumulative delta bytes since the last anchor
+
+    @property
+    def turn(self) -> int:
+        """The number of :meth:`next` calls so far (the initial full is turn 0)."""
+        return self._turn
+
+    def current_full(self) -> str:
+        """Return the full payload for the current base (:func:`encode_generic_full`).
+
+        Send this first to establish the base; it is also a valid manual re-anchor.
+        """
+        return encode_generic_full(self._base, self._tool)
+
+    def _reanchor(self, nxt: GenericSet) -> str:
+        wire = encode_generic_full(nxt, self._tool)
+        self._base = nxt
+        self._cum = 0
+        return wire
+
+    def next(self, nxt: GenericSet) -> tuple[str, bool]:
+        """Advance the session by one turn to ``nxt``.
+
+        Returns ``(wire, is_full)``: the wire to transmit and whether it is a full
+        re-anchor (``True``) or a delta (``False``). A schema change forces a full
+        (Section 10a.7). The held base becomes ``nxt`` either way. The wire is
+        byte-identical to calling ``encode_generic_full`` / ``encode_generic_delta``
+        directly. May raise on duplicate identity / no key (propagated from
+        :func:`diff_generic_sets`).
+        """
+        self._turn += 1
+
+        # Schema change (or a fresh key) cannot be expressed as a delta -> full.
+        if nxt.key != self._base.key or list(self._base.fields) != list(nxt.fields):
+            return self._reanchor(nxt), True
+
+        d = diff_generic_sets(self._base, nxt)
+        delta_wire = encode_generic_delta(d)
+
+        if self._policy.mode == ReanchorMode.SIZE_GUARD:
+            reanchor = self._cum + _byte_len(delta_wire) >= _byte_len(
+                encode_generic_full(nxt, self._tool)
+            )
+        else:  # FIXED_N
+            reanchor = self._turn % self._policy.n == 0
+
+        if reanchor:
+            return self._reanchor(nxt), True
+        self._base = nxt
+        self._cum += _byte_len(delta_wire)
+        return delta_wire, False

{gcf_python-2.2.1.dist-info → gcf_python-2.3.0.dist-info}/METADATA

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: gcf-python
-Version: 2.2.1
-Summary: The AI-native wire format for structured data. 50-92% fewer tokens than JSON. 100% comprehension on every frontier model. Zero dependencies.
+Version: 2.3.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://blackwell-systems.github.io/gcf/
+Project-URL: Documentation, https://gcformat.com/
 Project-URL: Specification, https://github.com/blackwell-systems/gcf
 Author: Blackwell Systems
 License: MIT
 License-File: LICENSE
-Keywords: gcf,graph,llm,mcp,token-efficient,wire-format
-Classifier: Development Status :: 4 - Beta
+Keywords: agents,delta,gcf,graph,llm,mcp,multi-turn,token-efficient,wire-format
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -32,7 +32,7 @@ Description-Content-Type: text/markdown
 
 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.2%, JSON 53.4%). 2,400+ LLM evaluations. Zero training.**
+**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.**
 
 Docs: [gcformat.com](https://gcformat.com/) · [Playground](https://gcformat.com/playground.html) · [GCF vs TOON](https://gcformat.com/guide/vs-toon.html)
 
@@ -182,6 +182,44 @@ Output:
 
 Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows. Nested dicts use `## key` section headers.
 
+## Generic-Profile Delta (multi-turn)
+
+In an agent loop the same keyed table gets re-queried turn after turn. Instead of re-sending the whole table each time, send only the changed rows (SPEC §10a):
+
+```python
+from gcf import GenericSet, diff_generic_sets, encode_generic_delta, verify_generic_delta
+
+base = GenericSet(key="id", fields=["id", "status"], rows=[
+    {"id": 1001, "status": "pending"},
+    {"id": 1002, "status": "shipped"},
+])
+nxt = GenericSet(key="id", fields=["id", "status"], rows=[
+    {"id": 1001, "status": "shipped"},   # changed
+    {"id": 1003, "status": "pending"},   # added (1002 removed)
+])
+
+d = diff_generic_sets(base, nxt)
+wire = encode_generic_delta(d)                       # ## added / ## changed / ## removed
+held = verify_generic_delta(base, d, d.new_root)     # atomic apply + new_root verification
+```
+
+Opt-in and bilateral, keyed on content-addressed pack roots. By the 5th overlapping call, ~97% fewer tokens than re-sending JSON.
+
+### Re-anchor session helper
+
+`GenericDeltaSession` manages the delta/re-anchor cadence for you: each `next()` returns either a compact delta or, on its cadence, a full re-anchor (which re-grounds the consumer), updating its held base.
+
+```python
+from gcf import GenericDeltaSession, fixed_n, size_guard
+
+sess = GenericDeltaSession(base, tool="orders", policy=size_guard())
+wire = sess.current_full()                # transmit the base once to establish it
+for snapshot in stream:                   # each turn's current GenericSet
+    wire, is_full = sess.next(snapshot)    # a compact delta, or a periodic full re-anchor
+```
+
+`fixed_n(15)` re-anchors every N turns; `size_guard()` (recommended) re-anchors once the cumulative delta reaches a full payload's size. It introduces no new wire syntax and the decoder stays cadence-agnostic, so a re-anchor is just the protocol's "full" outcome on a schedule.
+
 ## API
 
 | Function | Description |
@@ -190,7 +228,11 @@ Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows.
 | `encode_generic(data: Any) -> str` | Encode any value to GCF tabular format |
 | `decode(input_text: str) -> Payload` | Parse GCF text back to a Payload |
 | `encode_with_session(p: Payload, s: Session) -> str` | Encode with session deduplication |
-| `encode_delta(d: DeltaPayload) -> str` | Encode a delta (added/removed only) |
+| `encode_delta(d: DeltaPayload) -> str` | Encode a graph delta (added/removed only) |
+| `diff_generic_sets(base, next) -> GenericDeltaPayload` | Diff two keyed record sets (generic profile) |
+| `encode_generic_delta(d) -> str` / `decode_generic_delta(s)` | Generic-profile delta wire (§10a) |
+| `verify_generic_delta(base, d, root) -> GenericSet` | Atomic apply + `new_root` verification |
+| `GenericDeltaSession(base, tool, policy)` | Producer-side re-anchor cadence helper (§10a.8) |
 | `Session()` | Create a new session tracker (thread-safe) |
 
 ## Types
@@ -200,7 +242,9 @@ Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows.
 | `Payload` | Full GCF payload: tool, budget, symbols, edges, pack root |
 | `Symbol` | Graph node: qualified name, kind, score, provenance, distance |
 | `Edge` | Directed relationship: source, target, edge type |
-| `DeltaPayload` | Diff between two packs: added/removed symbols and edges |
+| `DeltaPayload` | Diff between two graph packs: added/removed symbols and edges |
+| `GenericSet` / `GenericDeltaPayload` | Keyed record set and its generic-profile diff (§10a) |
+| `GenericDeltaSession` | Stateful producer that schedules delta vs full re-anchor (§10a.8) |
 | `Session` | Thread-safe tracker for multi-call deduplication |
 | `KIND_ABBREV` / `KIND_EXPAND` | Bidirectional kind abbreviation dicts |
 
@@ -210,7 +254,7 @@ Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows.
 
 | | GCF | TOON | JSON |
 |---|---|---|---|
-| **Comprehension** (23 runs, 10 models) | **91.2%** | 68.2% | 53.4% |
+| **Comprehension** (23 runs, 10 models) | **91.2%** | 68.8% | 54.1% |
 | **Generation** (28 runs, 9 models) | **5/5** | 1.0/5 | 5.0/5 |
 | **Input tokens** (500 symbols) | **11,090** | 16,378 | 53,341 |
 | **Output tokens** (100 symbols) | **5,976** | 8,937 | 16,121 |
@@ -236,7 +280,11 @@ 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 173 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. All implementations at v2.2.0+ (Go v1.3.0). Cross-language 6x6 matrix verified.
+**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.
+
+## 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)
 
 ## License
 

{gcf_python-2.2.1.dist-info → gcf_python-2.3.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-gcf/__init__.py,sha256=AlIvWioau3i54BViE2rZsNuXCpQKD9tzwA7_jOKq2u4,1776
+gcf/__init__.py,sha256=WtDoZGghWL_LuNRGmB1uyfxQAs7zOAAMnwwfJK4vd-Y,2499
 gcf/__main__.py,sha256=EpvBz1yc8H0D5OJ1zy2tYke-kRzvudKa4DEbfeW14ao,71
 gcf/cli.py,sha256=UEe1CAZn-rKGNIo_ap8-oez3ucl6DSRbsdv6RDnzygY,5256
 gcf/constants.py,sha256=cmZ8YJSOB0im_eyfN8v4UvrLpBC6Fuf4cfcKZGbutxY,638
@@ -6,14 +6,15 @@ gcf/decode.py,sha256=nD8bXYhoeHQQ3LCeAJQOAgFuob-V_6us4mcBYtL_bBc,5978
 gcf/decode_generic.py,sha256=ZlFZqwenOzCnvbJijKscb6aQHoHQ81qoHBkaalVbqqo,26381
 gcf/delta.py,sha256=f90UC6zejXH-ujyU_OViWDCqnxLXk3i6Qion-RJGHY4,1670
 gcf/encode.py,sha256=CcqMSNmojrQAAw2X3MNfw8YR6l4rNw9hWDqwmf846oA,2929
-gcf/generic.py,sha256=I06-vcVtcCg38X6uaoTMy7ipWiIFLaBMgQpTtuGvg2o,17763
+gcf/generic.py,sha256=t0Px1fAoWsmFFeICbL65LL8UTGFfnbh4PCanvMMKqYs,18198
+gcf/generic_delta.py,sha256=GU7CNumz3PQhC0Xs5pO30Nb3ACvSorHEQMu-4kazpFM,17838
 gcf/scalar.py,sha256=MZay-KIROvaFHet-g2-pBghahT1bf_5bxZjG4yTZkSo,9329
 gcf/session.py,sha256=6-wytNGaBkgqH7uTar7ojUFYNwIMeEVAZhuV-s-upZM,4704
 gcf/stream.py,sha256=1Kt_a2daKpYHlWP1lnDJ4g549pUt9rc-U0xbARbXRKQ,5174
 gcf/stream_generic.py,sha256=RnqqiPSu5joJa-7e58QbbzSGfvxBICA587A3aArjZvE,3250
 gcf/types.py,sha256=AWm-LQoSqLHAYtEjcAxWQZqJ4JXqNreLUKO2mJFgNMA,1465
-gcf_python-2.2.1.dist-info/METADATA,sha256=izqgkRxKLUVqw5_sZqcs50i9kMAP3NRZnY8EuBDLVt8,9802
-gcf_python-2.2.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-gcf_python-2.2.1.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
-gcf_python-2.2.1.dist-info/licenses/LICENSE,sha256=2Fit9wnaIe--RMSAgyQqxC5hfZTyZqn4fIdBtp9qPDw,1072
-gcf_python-2.2.1.dist-info/RECORD,,
+gcf_python-2.3.0.dist-info/METADATA,sha256=IVEaubFtiRRpdcLqbYoPoibNEu-ueoaW--v9g_PhFpE,13040
+gcf_python-2.3.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+gcf_python-2.3.0.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
+gcf_python-2.3.0.dist-info/licenses/LICENSE,sha256=2Fit9wnaIe--RMSAgyQqxC5hfZTyZqn4fIdBtp9qPDw,1072
+gcf_python-2.3.0.dist-info/RECORD,,

{gcf_python-2.2.1.dist-info → gcf_python-2.3.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.30.1
+Generator: hatchling 1.31.0
 Root-Is-Purelib: true
 Tag: py3-none-any