gcf-python 2.7.1__py3-none-any.whl → 2.8.0__py3-none-any.whl

gcf/__init__.py

@@ -39,6 +39,7 @@ from .decode import DecodeError, decode
 from .delta import decode_delta, encode_delta, verify_delta
 from .encode import encode
 from .generic import encode_generic, GenericOptions
+from .constant_grouping import encode_generic_grouped
 from .generic_delta import (
     GenericSet,
     GenericDeltaPayload,
@@ -82,6 +83,7 @@ __all__ = [
     "encode_delta",
     "verify_delta",
     "encode_generic",
+    "encode_generic_grouped",
     "GenericOptions",
     "encode_with_session",
     "GenericSet",

gcf/constant_grouping.py

@@ -0,0 +1,549 @@
+"""GCF v3.6.0 tabular column optimizations for the generic profile: constant-column
+factoring (SPEC 7.4.7) and value-grouping (SPEC 7.4.8).
+
+Constant-column factoring is mandatory canonical and lives in the encoder
+(_encode_tabular, generic.py); the decode side and the opt-in grouped encoder are
+here. The wire output of encode_generic_grouped is byte-identical to the Go reference
+EncodeGenericGrouped.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .scalar import (
+    MISSING,
+    format_key,
+    format_scalar,
+    is_bare_key,
+    needs_quote,
+    parse_quoted_string,
+    parse_scalar,
+    quote_string,
+    split_respecting_quotes,
+)
+
+
+class FieldEntry:
+    """One parsed entry of a tabular field declaration. A plain field has only a
+    name. A constant column (SPEC 7.4.7) carries an unparsed value token after an
+    unquoted "=". A key column (SPEC 7.4.8.1, 10a.1) carries a leading "@"."""
+
+    __slots__ = ("name", "is_key", "is_const", "const_tok")
+
+    def __init__(self, name: str = "", is_key: bool = False, is_const: bool = False, const_tok: str = ""):
+        self.name = name
+        self.is_key = is_key
+        self.is_const = is_const
+        self.const_tok = const_tok
+
+
+def _quoted_string_end(s: str) -> int:
+    """Index just past the closing quote of a quoted string starting at s[0], or -1
+    if unterminated."""
+    escaped = False
+    i = 1
+    while i < len(s):
+        if escaped:
+            escaped = False
+            i += 1
+            continue
+        if s[i] == "\\":
+            escaped = True
+            i += 1
+            continue
+        if s[i] == '"':
+            return i + 1
+        i += 1
+    return -1
+
+
+def _split_name_value(r: str) -> tuple[str, str | None]:
+    """Parse a field entry's name and optional "=value" tail. The name is a Section
+    2a key (bare or quoted); the "=" that introduces a constant value is the first
+    unquoted "=" after the (possibly quoted) name. A None value means the entry is a
+    plain field (no "=")."""
+    if r == "":
+        raise ValueError("malformed_header_field: empty field entry")
+    if r[0] == '"':
+        end = _quoted_string_end(r)
+        if end < 0:
+            raise ValueError("unterminated_quote: field name")
+        nm = parse_quoted_string(r[:end])
+        after = r[end:]
+        if after == "":
+            return nm, None
+        if after[0] == "=":
+            return nm, after[1:]
+        raise ValueError("malformed_header_field: unexpected characters after quoted field name")
+    idx = r.find("=")
+    if idx >= 0:
+        nm = r[:idx]
+        if nm == "":
+            raise ValueError("malformed_header_field: empty field name")
+        if not is_bare_key(nm):
+            raise ValueError(f"invalid field name: {nm}")
+        return nm, r[idx + 1:]
+    if not is_bare_key(r):
+        raise ValueError(f"invalid field name: {r}")
+    return r, None
+
+
+def parse_field_entries(decl_str: str) -> list[FieldEntry]:
+    """Parse a {...} field declaration supporting "@" key markers and "name=value"
+    constant columns. Commas, and the "=" boundary, are parsed respecting quoted
+    names and quoted values (SPEC 7.4.7.2, mirroring 2a.3)."""
+    if len(decl_str) < 2 or decl_str[0] != "{" or decl_str[-1] != "}":
+        raise ValueError(f"invalid field declaration: {decl_str}")
+    inner = decl_str[1:-1]
+    if inner == "":
+        return []
+    raw = split_respecting_quotes(inner, ",")
+    entries: list[FieldEntry] = []
+    for r in raw:
+        r = r.strip()
+        e = FieldEntry()
+        if r.startswith("@"):
+            e.is_key = True
+            r = r[1:]
+        nm, val = _split_name_value(r)
+        e.name = nm
+        if val is not None:
+            e.is_const = True
+            e.const_tok = val
+        entries.append(e)
+    seen: set[str] = set()
+    for e in entries:
+        if e.name in seen:
+            raise ValueError(f"duplicate_field_name: {e.name}")
+        seen.add(e.name)
+    return entries
+
+
+def parse_const_value(tok: str) -> Any:
+    """Parse a constant-column value token into a scalar (SPEC 7.4.7.2). The absent
+    marker and empty/attachment tokens are rejected."""
+    if tok == "":
+        raise ValueError("invalid_const_value: empty constant value (the empty string is always quoted)")
+    if tok == "~":
+        raise ValueError("invalid_const_value: absent marker ~ is not valid in a field declaration")
+    # Reject only a complete attachment marker, mirroring the encoder's Section 2.4
+    # quoting predicate (bare "^", or "^{...}" ending in "}"). A "^{"-prefixed token with
+    # no closing "}" (e.g. "^{abc") is a literal string the encoder leaves bare, so the
+    # decoder must accept it as a scalar.
+    if tok == "^" or (len(tok) >= 3 and tok[0] == "^" and tok[1] == "{" and tok[-1] == "}"):
+        raise ValueError("invalid_const_value: attachment marker is not a scalar")
+    return parse_scalar(tok, tabular_context=False)
+
+
+def format_const_value(v: Any) -> str:
+    """Format a scalar as a constant-column header value (SPEC 7.4.7.2): the Section
+    2.4 obligation plus quoting when the value contains "}" (the "," case is already
+    covered by needs_quote). Null is "-"."""
+    if v is None:
+        return "-"
+    if isinstance(v, str):
+        if needs_quote(v) or "}" in v:
+            return quote_string(v)
+        return v
+    return format_scalar(v)
+
+
+def _path_top_level(name: str) -> tuple[str, bool]:
+    """Top-level group key of a flattened path column (SPEC 7.4.6) and True when the
+    name is a valid path (contains ">" with all segments non-empty), mirroring
+    _parse_tabular_body's path-column detection."""
+    if ">" not in name:
+        return "", False
+    parts = name.split(">")
+    for p in parts:
+        if p == "":
+            return "", False
+    return parts[0], True
+
+
+def decode_constant_array(lines, header_line, depth, entries, count, parse_tabular_body):
+    """Parse a tabular array whose field declaration contains one or more constant
+    columns (SPEC 7.4.7). Parse the rows with the bare (per-record) fields only, then
+    rebuild each record in declaration order, inserting each constant at its position.
+    Returns (records, lines_consumed_including_header)."""
+    bare_fields: list[str] = []
+    const_vals: dict[str, Any] = {}
+    for e in entries:
+        if e.is_const:
+            const_vals[e.name] = parse_const_value(e.const_tok)
+            continue
+        bare_fields.append(e.name)
+    if not bare_fields:
+        raise ValueError("no_bare_column: every field is constant; a row must carry at least one per-record column")
+    rows, consumed = parse_tabular_body(lines, header_line + 1, depth, bare_fields, count)
+    if count >= 0 and len(rows) != count:
+        raise ValueError(f"count_mismatch: declared {count}, got {len(rows)}")
+
+    # Plan the output-key order over all entries, mirroring _parse_tabular_body: a bare
+    # path column (contains ">") collapses to its top-level key at the first occurrence,
+    # a plain field keeps its name, and a constant contributes its name at its position.
+    plan: list[tuple[str, bool]] = []  # (name, is_const)
+    in_plan: set[str] = set()
+    seen_group: set[str] = set()
+    for e in entries:
+        if e.is_const:
+            plan.append((e.name, True))
+            in_plan.add(e.name)
+            continue
+        top, ok = _path_top_level(e.name)
+        if ok:
+            if top not in seen_group:
+                seen_group.add(top)
+                plan.append((top, False))
+                in_plan.add(top)
+            continue
+        plan.append((e.name, False))
+        in_plan.add(e.name)
+
+    out: list[Any] = []
+    for r in rows:
+        rm = r if isinstance(r, dict) else {}
+        nm: dict[str, Any] = {}
+        for name, is_const in plan:
+            if is_const:
+                nm[name] = const_vals[name]
+                continue
+            if name in rm:
+                nm[name] = rm[name]
+        # Append any keys the record carries that were not in the plan (flatten-fallback
+        # attachments, Section 7.4.6.1.4), in the record's own order.
+        for k, v in rm.items():
+            if k not in in_plan:
+                nm[k] = v
+        out.append(nm)
+    return out, consumed + 1
+
+
+def _parse_header_key(s: str) -> str:
+    """Parse a Section 2a key (bare or quoted) that occupies the whole of s."""
+    if s == "":
+        raise ValueError("empty key")
+    if s[0] == '"':
+        end = _quoted_string_end(s)
+        if end != len(s):
+            raise ValueError(f"malformed quoted key: {s}")
+        return parse_quoted_string(s)
+    if not is_bare_key(s):
+        raise ValueError(f"invalid key: {s}")
+    return s
+
+
+def _index_unquoted_eq(s: str) -> int:
+    """Index of the first "=" outside a quoted string, or -1."""
+    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 c == "=" and not in_quote:
+            return i
+    return -1
+
+
+def _parse_count_value(s: str) -> int:
+    """Count grammar (Section 4): decimal with no leading zero (except "0")."""
+    if s == "0":
+        return 0
+    if not s or s[0] == "0":
+        raise ValueError(f"invalid_count: {s}")
+    try:
+        n = int(s)
+    except ValueError:
+        raise ValueError(f"invalid_count: {s}")
+    if str(n) != s:
+        raise ValueError(f"invalid_count: {s}")
+    return n
+
+
+def _parse_group_subheader(content: str) -> tuple[str, Any, int]:
+    """Parse a line of the form `{col}={value} [{count}]` (SPEC 7.4.8.3). The value
+    runs from the first unquoted "=" to the final " [" that begins the count. Returns
+    (col, value, count)."""
+    if not content.endswith("]"):
+        raise ValueError("invalid_group_header: subheader missing count bracket")
+    cnt_open = content.rfind(" [")
+    if cnt_open < 0:
+        raise ValueError("invalid_group_header: subheader missing count bracket")
+    count_str = content[cnt_open + 2: len(content) - 1]
+    try:
+        n = _parse_count_value(count_str)
+    except ValueError:
+        raise ValueError(f"invalid_count: {count_str}")
+    if n == 0:
+        raise ValueError("invalid_count: a group names at least one record")
+    col_eq_val = content[:cnt_open]
+    eq = _index_unquoted_eq(col_eq_val)
+    if eq < 0:
+        raise ValueError("invalid_group_header: subheader missing '='")
+    try:
+        col_name = _parse_header_key(col_eq_val[:eq])
+    except ValueError as err:
+        raise ValueError(f"invalid_group_header: {err}")
+    val_tok = col_eq_val[eq + 1:]
+    v = parse_const_value(val_tok)
+    return col_name, v, n
+
+
+def decode_grouped_array(lines, header_line, depth, entries, group_clause, count):
+    """Parse a value-grouped tabular array (SPEC 7.4.8). group_clause is the trimmed
+    text after the field declaration's "}" (beginning with "group=").
+    Returns (records, lines_consumed)."""
+    if not group_clause.startswith("group="):
+        raise ValueError("invalid_group_header: malformed group clause")
+    try:
+        group_col = _parse_header_key(group_clause[len("group="):].strip())
+    except ValueError as err:
+        raise ValueError(f"invalid_group_header: {err}")
+
+    key_count = 0
+    key_name = ""
+    for e in entries:
+        if e.is_key:
+            key_count += 1
+            key_name = e.name
+    if key_count != 1:
+        raise ValueError("invalid_group_header: a grouped section requires exactly one @ key column")
+
+    # Validate the grouping column: present, not the key, not a constant column.
+    group_entry: FieldEntry | None = None
+    for e in entries:
+        if e.name == group_col:
+            group_entry = e
+            break
+    if group_entry is None:
+        raise ValueError(f'invalid_group_header: group column "{group_col}" is not a declared field')
+    if group_entry.is_key:
+        raise ValueError(f'invalid_group_header: group column "{group_col}" is the key column')
+    if group_entry.is_const:
+        raise ValueError(f'invalid_group_header: group column "{group_col}" is a constant column')
+
+    # Per-record (bare) fields are the non-constant fields other than the grouping
+    # column; the key column is included.
+    bare_fields: list[str] = []
+    const_vals: dict[str, Any] = {}
+    for e in entries:
+        if e.is_const:
+            const_vals[e.name] = parse_const_value(e.const_tok)
+            continue
+        if e.name == group_col:
+            continue
+        bare_fields.append(e.name)
+
+    indent = "  " * depth
+    records: list[Any] = []
+    seen_groups: set[str] = set()
+    seen_keys: set[str] = set()
+    total = 0
+    i = header_line + 1
+    while i < len(lines):
+        content = lines[i]
+        if depth > 0:
+            if not content.startswith(indent):
+                break
+            content = content[len(indent):]
+        if content.startswith("## ") or content.startswith("##!"):
+            break
+
+        col, group_val, gcount = _parse_group_subheader(content)
+        if col != group_col:
+            raise ValueError(
+                f'invalid_group_header: subheader column "{col}" does not match group column "{group_col}"'
+            )
+        gkey = format_scalar(group_val)
+        if gkey in seen_groups:
+            raise ValueError(f"duplicate_group: {gkey}")
+        seen_groups.add(gkey)
+        i += 1
+
+        for _n in range(gcount):
+            if i >= len(lines):
+                raise ValueError(f'count_mismatch: group "{gkey}" declared {gcount} rows, found fewer')
+            row_content = lines[i]
+            if depth > 0:
+                if not row_content.startswith(indent):
+                    raise ValueError(f'count_mismatch: group "{gkey}" declared {gcount} rows, found fewer')
+                row_content = row_content[len(indent):]
+            if row_content.startswith("## ") or row_content.startswith("##!"):
+                raise ValueError(f'count_mismatch: group "{gkey}" declared {gcount} rows, found fewer')
+            cells = split_respecting_quotes(row_content, "|")
+            if len(cells) != len(bare_fields):
+                raise ValueError(f"row_width_mismatch: expected {len(bare_fields)} fields, got {len(cells)}")
+            bare_vals: dict[str, Any] = {}
+            for j, f in enumerate(bare_fields):
+                cell = cells[j]
+                # Only a complete attachment marker (bare "^" or "^{...}" ending in "}")
+                # is forbidden; a "^{"-prefixed cell without a closing "}" is a literal
+                # row scalar, not an attachment.
+                if cell == "^" or (len(cell) >= 3 and cell[0] == "^" and cell[1] == "{" and cell[-1] == "}"):
+                    raise ValueError("invalid_group_header: grouped records must not carry attachments")
+                pv = parse_scalar(cell, tabular_context=True)
+                if pv is MISSING:
+                    continue
+                bare_vals[f] = pv
+            nm: dict[str, Any] = {}
+            for e in entries:
+                if e.name == group_col:
+                    nm[e.name] = group_val
+                elif e.is_const:
+                    nm[e.name] = const_vals[e.name]
+                else:
+                    if e.name in bare_vals:
+                        nm[e.name] = bare_vals[e.name]
+            if key_name not in nm:
+                raise ValueError(f'invalid_group_header: record missing key column "{key_name}"')
+            ks = format_scalar(nm[key_name])
+            if ks in seen_keys:
+                raise ValueError(f"duplicate_key: {ks}")
+            seen_keys.add(ks)
+            records.append(nm)
+            i += 1
+        total += gcount
+
+    if count >= 0 and total != count:
+        raise ValueError(f"count_mismatch: declared {count}, got {total}")
+    return records, i - header_line
+
+
+def _tabular_fields(arr: list) -> list[str] | None:
+    if not arr:
+        return None
+    field_order: list[str] = []
+    seen: set[str] = set()
+    for item in arr:
+        if not isinstance(item, dict):
+            return None
+        for k in item:
+            if k not in seen:
+                field_order.append(k)
+                seen.add(k)
+    return field_order if field_order else None
+
+
+def encode_generic_grouped(data: Any, key_field: str, group_field: str) -> str:
+    """Encode an array of uniform records as a value-grouped keyed set (SPEC 7.4.8):
+    opt-in, never the canonical default. key_field is the unique identity column
+    (emitted @-marked); group_field is the low-cardinality column the records are
+    clustered by. Other constant columns are factored (SPEC 7.4.7). It raises when the
+    array is not a keyed set the grammar can represent: a missing key/group field, a
+    non-unique key, key == group, or any record needing an attachment (nested value),
+    which grouped rows do not carry in this version.
+
+    The wire output is byte-identical to the Go reference EncodeGenericGrouped."""
+    if not isinstance(data, list):
+        raise ValueError("value-grouping requires a JSON array")
+    arr = data
+    if len(arr) == 0:
+        raise ValueError("value-grouping requires a non-empty array")
+    if key_field == group_field:
+        raise ValueError("value-grouping: key field and group field must differ")
+    for item in arr:
+        if not isinstance(item, dict):
+            raise ValueError("value-grouping requires an array of objects")
+    fields = _tabular_fields(arr)
+    if fields is None:
+        raise ValueError("value-grouping requires an array of objects with fields")
+    if key_field not in fields:
+        raise ValueError(f'value-grouping: key field "{key_field}" not present in the records')
+    if group_field not in fields:
+        raise ValueError(f'value-grouping: group field "{group_field}" not present in the records')
+
+    key_seen: set[str] = set()
+    for item in arr:
+        for f in fields:
+            if f not in item:
+                continue
+            val = item[f]
+            if isinstance(val, (dict, list)):
+                raise ValueError(f'value-grouping does not support nested values in this version: field "{f}"')
+        if key_field not in item or item[key_field] is None:
+            raise ValueError(f'value-grouping: key field "{key_field}" missing in a record')
+        ks = format_scalar(item[key_field])
+        if ks in key_seen:
+            raise ValueError(f'value-grouping: key field "{key_field}" is not unique ({ks})')
+        key_seen.add(ks)
+
+    # Constant columns (excluding key and group), factored per SPEC 7.4.7.
+    const_val: dict[str, str] = {}
+    if len(arr) >= 2:
+        for f in fields:
+            if f == key_field or f == group_field:
+                continue
+            first = ""
+            first_set = False
+            isc = True
+            for item in arr:
+                if f not in item:
+                    isc = False
+                    break
+                cv = format_const_value(item[f])
+                if not first_set:
+                    first = cv
+                    first_set = True
+                elif cv != first:
+                    isc = False
+                    break
+            if isc:
+                const_val[f] = first
+
+    header_fields: list[str] = []
+    for f in fields:
+        if f == key_field:
+            header_fields.append("@" + format_key(f))
+        elif f == group_field:
+            header_fields.append(format_key(f))
+        else:
+            if f in const_val:
+                header_fields.append(format_key(f) + "=" + const_val[f])
+            else:
+                header_fields.append(format_key(f))
+
+    bare_fields: list[str] = []
+    for f in fields:
+        if f == group_field:
+            continue
+        if f in const_val:
+            continue
+        bare_fields.append(f)
+
+    group_order: list[str] = []
+    group_members: dict[str, list[Any]] = {}
+    group_val_raw: dict[str, Any] = {}
+    for item in arr:
+        gv = item.get(group_field)
+        gk = format_scalar(gv)
+        if gk not in group_members:
+            group_order.append(gk)
+            group_members[gk] = []
+            group_val_raw[gk] = gv
+        group_members[gk].append(item)
+
+    out: list[str] = ["GCF profile=generic"]
+    out.append(f"## [{len(arr)}]{{{','.join(header_fields)}}} group={format_key(group_field)}")
+    for gk in group_order:
+        members = group_members[gk]
+        gv_str = format_scalar(group_val_raw[gk])
+        out.append(f"{format_key(group_field)}={gv_str} [{len(members)}]")
+        for item in members:
+            cells: list[str] = []
+            for f in bare_fields:
+                if f not in item:
+                    cells.append("~")
+                elif item[f] is None:
+                    cells.append("-")
+                else:
+                    cells.append(format_scalar(item[f], "|"))
+            out.append("|".join(cells))
+    return "\n".join(out) + "\n"

gcf/decode_generic.py

@@ -6,6 +6,11 @@ from typing import Any
 
 from .decode import decode
 from .keyed_map import keyed_rows_to_map
+from .constant_grouping import (
+    decode_constant_array,
+    decode_grouped_array,
+    parse_field_entries,
+)
 from .scalar import (
     parse_scalar, parse_quoted_string, split_respecting_quotes, split_field_decl,
     is_bare_key, MISSING, ATTACHMENT,
@@ -297,7 +302,36 @@ def _parse_array_from_header(
         brace_end = _find_closing_brace(after)
         if brace_end < 0:
             raise ValueError("invalid field declaration")
-        fields = split_field_decl(after[:brace_end + 1])
+        decl_str = after[:brace_end + 1]
+        group_clause = after[brace_end + 1:].strip()
+
+        # Value-grouping (SPEC 7.4.8): non-keyed tabular array with a group= clause.
+        if not keyed and group_clause.startswith("group="):
+            entries = parse_field_entries(decl_str)
+            return decode_grouped_array(lines, header_line, depth, entries, group_clause, count)
+        if group_clause:
+            raise ValueError(f"malformed_header_field: unexpected content after field declaration: {group_clause}")
+
+        # Constant-column factoring (SPEC 7.4.7): a non-keyed tabular array whose field
+        # declaration carries name=value entries (or a stray @, which is valid only with
+        # a group= clause). The common case (no "=" or "@") takes the plain path.
+        if not keyed and ("=" in decl_str or "@" in decl_str):
+            entries = parse_field_entries(decl_str)
+            has_const = False
+            for e in entries:
+                if e.is_key:
+                    raise ValueError(
+                        f"invalid field name: @{e.name} (an @ key column is valid only in a grouped section)"
+                    )
+                if e.is_const:
+                    has_const = True
+            if has_const:
+                return decode_constant_array(
+                    lines, header_line, depth, entries, count, _parse_tabular_body
+                )
+            # No constants after all (e.g. a quoted name containing "="): plain path.
+
+        fields = split_field_decl(decl_str)
         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)}")

gcf/generic.py

@@ -7,6 +7,7 @@ from typing import Any
 
 from .scalar import format_scalar, format_key
 from .keyed_map import keyed_map_eligible
+from .constant_grouping import format_const_value
 
 
 @dataclass
@@ -71,7 +72,7 @@ def _encode_root_array(arr: list, out: list[str], opts: GenericOptions) -> None:
         return
     fields = _tabular_fields(arr)
     if fields is not None:
-        _encode_tabular("## ", arr, fields, out, 0, opts)
+        _encode_tabular("## ", arr, fields, out, 0, opts, factor_const=True)
         return
     _encode_expanded("## ", arr, out, 0, opts)
 
@@ -87,7 +88,7 @@ def _encode_named_array(name: str, arr: list, out: list[str], depth: int, opts:
         return
     fields = _tabular_fields(arr)
     if fields is not None:
-        _encode_tabular(f"{prefix}## {name} ", arr, fields, out, depth, opts)
+        _encode_tabular(f"{prefix}## {name} ", arr, fields, out, depth, opts, factor_const=True)
         return
     _encode_expanded(f"{prefix}## {name} ", arr, out, depth, opts)
 
@@ -330,7 +331,7 @@ def _encode_keyed_map_with_prefix(
 
 def _encode_tabular(
     header_prefix: str, arr: list[dict], fields: list[str], out: list[str], depth: int,
-    opts: GenericOptions, keyed: bool = False
+    opts: GenericOptions, keyed: bool = False, factor_const: bool = False
 ) -> None:
     prefix = _indent(depth)
 
@@ -376,7 +377,48 @@ def _encode_tabular(
         if sas is not None:
             shared_arr_schemas[f] = sas
 
-    header_fields = ",".join(col["header"] for col in columns)
+    # Constant-column factoring (SPEC 7.4.7): a plain scalar column identical across
+    # every record is declared once in the header as name=value and omitted from the
+    # rows. Mandatory canonical for top-level tabular arrays, gated off for keyed maps
+    # and the nested-attachment path (factor_const). At least one per-record column
+    # remains.
+    const_col = [False] * len(columns)
+    const_header_val = [""] * len(columns)
+    if factor_const and not keyed and len(arr) >= 2:
+        for j, col in enumerate(columns):
+            if col["type"] != "original":
+                continue  # only plain scalar columns qualify, never flattened/attachment
+            first = ""
+            first_set = False
+            is_const = True
+            for item in arr:
+                f = col["field"]
+                if f not in item:
+                    is_const = False
+                    break
+                v = item[f]
+                if isinstance(v, (dict, list)):
+                    is_const = False
+                    break
+                cv = format_const_value(v)
+                if not first_set:
+                    first = cv
+                    first_set = True
+                elif cv != first:
+                    is_const = False
+                    break
+            if is_const:
+                const_col[j] = True
+                const_header_val[j] = first
+        # At least one per-record column MUST remain. If every column is constant
+        # (an array of identical objects), leave the last union field unfactored.
+        if not any(not c for c in const_col):
+            const_col[len(columns) - 1] = False
+
+    header_fields = ",".join(
+        (col["header"] + "=" + const_header_val[i]) if const_col[i] else col["header"]
+        for i, col in enumerate(columns)
+    )
     br = ":]" if keyed else "]"
     out.append(f"{header_prefix}[{len(arr)}{br}{{{header_fields}}}")
 
@@ -437,7 +479,9 @@ def _encode_tabular(
             row_has_attachment = True
             attachments.append((f, item[f], False, None))
 
-        row = "|".join(cells)
+        # Omit constant columns from the per-row cells (SPEC 7.4.7.3).
+        row_cells = [cells[j] for j in range(len(cells)) if not const_col[j]]
+        row = "|".join(row_cells)
         if row_has_attachment:
             out.append(f"{prefix}@{i} {row}")
         else:

{gcf_python-2.7.1.dist-info → gcf_python-2.8.0.dist-info}/METADATA

@@ -1,17 +1,18 @@
 Metadata-Version: 2.5
 Name: gcf-python
-Version: 2.7.1
+Version: 2.8.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://gcformat.com/
 Project-URL: Specification, https://github.com/blackwell-systems/gcf
 Author: Blackwell Systems
-License: MIT
+License: Apache-2.0
 License-File: LICENSE
+License-File: NOTICE
 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: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
@@ -29,7 +30,7 @@ Description-Content-Type: text/markdown
   <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>
+  <a href="https://github.com/blackwell-systems/gcf-python/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-333?style=for-the-badge" alt="License"></a>
 </p>
 
 <p align="center">
@@ -322,7 +323,7 @@ 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.5.3 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 281 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. Current versions: Go v1.7.1, TypeScript v2.6.1, Python v2.7.0, Rust v3.0.1, Swift v2.7.1, Kotlin v2.6.1, .NET v0.2.1. Cross-language conformance verified across all seven SDKs.
+**Specification:** [SPEC v3.5.3 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 281 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. Current versions: Go v1.7.1, TypeScript v2.6.1, Python v2.7.1, Rust v3.0.1, Swift v2.7.1, Kotlin v2.6.1, .NET v0.2.1. Cross-language conformance verified across all seven SDKs.
 
 ## Adopted by
 

{gcf_python-2.7.1.dist-info → gcf_python-2.8.0.dist-info}/RECORD

@@ -1,13 +1,14 @@
-gcf/__init__.py,sha256=uRYqyGTFSlmnfoj0hh79AZ_KhxiCgZgJt_v-okiK4_k,2616
+gcf/__init__.py,sha256=0ulf234ior-OkGp4Yu_fqEKoXGENK1hk0yUov9rIuX0,2700
 gcf/__main__.py,sha256=EpvBz1yc8H0D5OJ1zy2tYke-kRzvudKa4DEbfeW14ao,71
 gcf/cli.py,sha256=UEe1CAZn-rKGNIo_ap8-oez3ucl6DSRbsdv6RDnzygY,5256
+gcf/constant_grouping.py,sha256=OMdPF4aC1g2_mb16sbWPUhc4w9GHCqi6Y-EOYGdxfqo,21009
 gcf/constants.py,sha256=cmZ8YJSOB0im_eyfN8v4UvrLpBC6Fuf4cfcKZGbutxY,638
 gcf/decode.py,sha256=TP58_7UBhfeI0o9zpNgtQvAnLQGhNt0RaUjku7Ke75A,7162
-gcf/decode_generic.py,sha256=X59J2tV_ybZdWupVIVRtfLiqdxko2wfIn78Kkm5lNls,31170
+gcf/decode_generic.py,sha256=iJlgPnq2L1M7PwxLQ8H0kBrtNiU31XItKDrrSV3Bazo,32762
 gcf/delta.py,sha256=oviQ9WsDRYXPXE8bw6SFutmzMRIvu-U_Zzw-39Nd5Ic,8053
 gcf/encode.py,sha256=OYGDyF3oP2I8Y2PrPL_5yDVURqB0mghtqlOGyDEd-Fs,4081
 gcf/fastmcp.py,sha256=cwIX77DhA96rMrelQcrlAlFXGQ4FDNModa4rSGlGN7I,5139
-gcf/generic.py,sha256=1c53utF2GcD8lS_wks2opQw08hMz4KGL-7C8g7JB5bA,21577
+gcf/generic.py,sha256=V0Rl7vrZ64Zx3ryosg6a2mwgiT1EGIaAikV4Og3jZ50,23597
 gcf/generic_delta.py,sha256=5KSUT_QUeH7OILLWfu9JveaXRSrqRIi3c6E8WjlgC4Q,18785
 gcf/keyed_map.py,sha256=qCwhehXB1FQ2iYCPhcvXOqGwrVqdXhGYZGxv56CSUgc,3644
 gcf/packroot.py,sha256=0rZY7TEVcLzA8XhoIOc6_g9lbRCn-MUr54YTRVhzsO4,2019
@@ -16,8 +17,9 @@ 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.7.1.dist-info/METADATA,sha256=FYQP8X41OUkaB4Bwyvl0rvUCmlMsdTfINUDiRqQMcLM,17107
-gcf_python-2.7.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-gcf_python-2.7.1.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
-gcf_python-2.7.1.dist-info/licenses/LICENSE,sha256=2Fit9wnaIe--RMSAgyQqxC5hfZTyZqn4fIdBtp9qPDw,1072
-gcf_python-2.7.1.dist-info/RECORD,,
+gcf_python-2.8.0.dist-info/METADATA,sha256=qugUJ_7q1XfsZnBtqBjvLlLHL2GCm9lOawNX5odLVrY,17154
+gcf_python-2.8.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+gcf_python-2.8.0.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
+gcf_python-2.8.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+gcf_python-2.8.0.dist-info/licenses/NOTICE,sha256=bIpAq8Yk3ThWC8AWHpS39kZPJ52bSrT_G0h9_yaGuR0,183
+gcf_python-2.8.0.dist-info/RECORD,,

{gcf_python-2.7.1.dist-info → gcf_python-2.8.0.dist-info}/WHEEL

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

gcf_python-2.8.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

gcf_python-2.8.0.dist-info/licenses/NOTICE

@@ -0,0 +1,4 @@
+gcf-python
+Copyright 2026 Dayna Blackwell / Blackwell Systems
+
+This product includes software developed by Dayna Blackwell / Blackwell Systems (https://github.com/blackwell-systems).

gcf_python-2.7.1.dist-info/licenses/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Dayna Blackwell
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.