gcf-python 2.2.1__tar.gz → 2.3.0__tar.gz

{gcf_python-2.2.1 → gcf_python-2.3.0}/.github/workflows/ci.yml

@@ -13,7 +13,11 @@ jobs:
       matrix:
         python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
     steps:
+      # Check out gcf-python and the shared-fixtures gcf repo as SIBLINGS so the
+      # conformance runner's ../gcf/tests/conformance path resolves on CI.
       - uses: actions/checkout@v4
+        with:
+          path: gcf-python
       - uses: actions/checkout@v4
         with:
           repository: blackwell-systems/gcf
@@ -22,9 +26,13 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - run: pip install -e ".[dev]" || pip install -e . && pip install pytest
+        working-directory: gcf-python
       - name: Unit tests
         run: pytest tests/ -v --ignore=tests/test_conformance_v2.py --ignore=tests/test_roundtrip_v2.py
-      - name: Conformance tests (133 fixtures)
+        working-directory: gcf-python
+      - name: Conformance tests (shared fixtures)
         run: pytest tests/test_conformance_v2.py -v
+        working-directory: gcf-python
       - name: Property-based round-trip (100K random + 100K adversarial)
         run: pytest tests/test_roundtrip_v2.py -v
+        working-directory: gcf-python

{gcf_python-2.2.1 → gcf_python-2.3.0}/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## v2.3.0 (2026-07-12)
+
+### Generic-profile delta encoding (SPEC §10a)
+
+- Full producer + consumer implementation of generic-profile delta, byte-for-byte interoperable with `gcf-go`:
+  - `GenericSet` (keyed record set), `GenericDeltaPayload`
+  - `generic_pack_root` (`gcf-pack-root-v1`, generic profile) with a purpose-built cell canonicalization decoupled from the wire cell encoder: collision-free (null/bool/number bare, strings always quoted) and record-safe. Fields and records sort by UTF-8 byte order to match Go's `sort.Strings`.
+  - `diff_generic_sets` (the blessed producer path; centralizes the keyed-diff invariants), `encode_generic_full`, `encode_generic_delta`
+  - `decode_generic_full`, `decode_generic_delta` (consumer wire parsing)
+  - `verify_generic_delta` (atomic apply + `new_root` verification)
+  - Re-anchor session helper (SPEC §10a.8): `GenericDeltaSession` (`current_full`, `next`) with `ReanchorPolicy` / `fixed_n(n)` / `size_guard()` cadence policies and `DEFAULT_REANCHOR_N = 15`. Producer-side sugar over the primitives; introduces no new wire syntax (every emission is exactly `encode_generic_full` / `encode_generic_delta` output). Re-anchor cadence is byte-for-byte identical to `gcf-go` (size guard uses UTF-8 byte length to match Go's `len(string)`), verified by the shared `generic-delta-session` conformance fixtures.
+- Delta is opt-in and bilateral; the existing `encode_generic` path is unchanged (backward compatible).
+
+### Tests
+
+- Unit suite mirroring `gcf-go`: self-proving round-trip (diff -> encode -> apply -> recomputed root), determinism / row-order invariance, no-type-collision canonicalization, every invariant/error path, full-payload wire round-trip, the complete server -> wire -> consumer end-to-end loop, and malformed-wire-fails-closed.
+- Conformance runner support for `generic-pack-root`, `generic-delta`, `generic-delta-verify`, `generic-delta-decode` (12 shared fixtures); verified to produce identical pack roots and delta wire to `gcf-go`.
+- Session helper suite (`test_generic_delta_session.py`) mirroring `gcf-go`: FixedN cadence pattern, size-guard triggering, schema-change forced full, FixedN(15)-over-30-turns count, and the load-bearing consumer-stays-in-sync check under both policies. Conformance runner support for `generic-delta-session` (3 shared fixtures: fixed-N, size-guard, schema-change).
+
+## v2.2.2 (2026-07-10)
+
+### Fixes
+
+- **Losslessness (nested null):** a nested object that is null at an intermediate level (e.g. `{"meta": {"owner": None}}`) is no longer flattened. Previously its leaves encoded as absent (`~`) and unflattened to a missing key, silently dropping the null. Such fields now fall back to the attachment mechanism; a top-level `None` still flattens losslessly (emits `-`, reconstructs via the all-null rule). Enforced by the shared conformance fixtures `flatten/017`–`019`. Prototype pollution does not affect Python (dicts have no mutable prototype).
+
+### Tests
+
+- `test_flatten_roundtrip`: aligned arrays whose shared fields are fixed-shape nested objects with a field or an intermediate nested level sometimes null/absent — the shape the prior scalar-only generator never produced, leaving the flatten/unflatten path unexercised. Verified to fail on the pre-fix encoder and pass on the fix.
+
 ## v2.2.1 (2026-06-23)
 
 ### Flatten Opt-Out

{gcf_python-2.2.1 → gcf_python-2.3.0}/PKG-INFO

@@ -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 → gcf_python-2.3.0}/README.md

@@ -7,7 +7,7 @@
 
 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)
 
@@ -157,6 +157,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 |
@@ -165,7 +203,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
@@ -175,7 +217,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 |
 
@@ -185,7 +229,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 |
@@ -211,7 +255,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 → gcf_python-2.3.0}/pyproject.toml

@@ -4,17 +4,17 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gcf-python"
-version = "2.2.1"
-description = "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"
+description = "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."
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.9"
 authors = [
     { name = "Blackwell Systems" },
 ]
-keywords = ["gcf", "llm", "mcp", "token-efficient", "graph", "wire-format"]
+keywords = ["gcf", "llm", "mcp", "token-efficient", "graph", "wire-format", "delta", "multi-turn", "agents"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
@@ -32,7 +32,7 @@ gcf = "gcf.cli:main"
 
 [project.urls]
 Homepage = "https://github.com/blackwell-systems/gcf-python"
-Documentation = "https://blackwell-systems.github.io/gcf/"
+Documentation = "https://gcformat.com/"
 Specification = "https://github.com/blackwell-systems/gcf"
 
 [tool.hatch.build.targets.wheel]

{gcf_python-2.2.1 → gcf_python-2.3.0}/src/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_python-2.2.1 → gcf_python-2.3.0}/src/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):