gcf-python 2.2.2__py3-none-any.whl → 2.5.0__py3-none-any.whl

gcf/__init__.py

@@ -36,9 +36,27 @@ Specification: https://github.com/blackwell-systems/gcf
 
 from .constants import KIND_ABBREV, KIND_EXPAND
 from .decode import DecodeError, decode
-from .delta import encode_delta
+from .delta import decode_delta, encode_delta, verify_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 .packroot import pack_root
 from .session import Session, encode_with_session
 from .decode_generic import decode_generic
 from .stream import StreamEncoder
@@ -58,12 +76,30 @@ __all__ = [
     "StreamEncoder",
     "Symbol",
     "decode",
+    "decode_delta",
     "decode_generic",
     "encode",
     "encode_delta",
+    "verify_delta",
     "encode_generic",
     "GenericOptions",
     "encode_with_session",
+    "GenericSet",
+    "GenericDeltaPayload",
+    "generic_pack_root",
+    "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__ = "2.2.2"
+__version__ = "2.3.0"

gcf/decode_generic.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import Any
 
 from .decode import decode
+from .keyed_map import keyed_rows_to_map
 from .scalar import (
     parse_scalar, parse_quoted_string, split_respecting_quotes, split_field_decl,
     is_bare_key, MISSING, ATTACHMENT,
@@ -72,7 +73,7 @@ def decode_generic(input_text: str) -> Any:
         if trimmed.startswith("##! "):
             summary_line = trimmed
             continue
-        if trimmed.startswith("## ") and "[?]" in trimmed:
+        if trimmed.startswith("## ") and ("[?]" in trimmed or "[?:]" in trimmed):
             deferred_count += 1
         content_lines.append(line)
 
@@ -134,7 +135,7 @@ def _parse_object_body(
 
         if content.startswith("## "):
             hdr = content[3:]
-            bi = hdr.find(" [")
+            bi = _find_bracket_start(hdr)
             if bi >= 0:
                 name = _parse_key_from_header(hdr[:bi])
                 _check_dup(out, name)
@@ -177,7 +178,14 @@ def _parse_object_body(
                         i += 1
                         continue
 
-        i += 1
+        # An object-body line that is not a `## ` section, a `key=value` field, or
+        # an inline array is not valid content and MUST NOT be silently skipped
+        # (that dropped data, a lossless round-trip hole). A pipe-delimited line is
+        # a stray positional inline body with no eligible `^` cell (SPEC 16.5,
+        # orphan_inline_attachment); any other unrecognized line is likewise rejected.
+        if "|" in content:
+            raise ValueError(f"orphan_inline_attachment: {content}")
+        raise ValueError(f"invalid_line: unexpected content in object body: {content!r}")
     return i - start
 
 
@@ -226,10 +234,24 @@ def _parse_array_from_header(
         raise ValueError("invalid_count")
     count_str = bp[1:close]
     after = bp[close + 1:]
+
+    # A keyed map is marked by `:` after the count inside the bracket (`[N:]`).
+    # The decoder reconstructs a JSON object, not an array (SPEC 7.2a.2).
+    keyed = count_str.endswith(":")
+    if keyed:
+        count_str = count_str[:-1]
+        if not after.startswith("{"):
+            raise ValueError("keyed_map: missing field declaration")
+
     count = -1
     if count_str != "?":
         count = _parse_count(count_str)
 
+    # A keyed map has at least one member; an empty object is encoded per
+    # Section 7.7, never as [0:] (SPEC 7.2a.4).
+    if keyed and count == 0:
+        raise ValueError("keyed_map: zero count [0:] is invalid (an empty object uses Section 7.7)")
+
     if count == 0 and not after.startswith("{") and not after.startswith(":"):
         return [], 1
 
@@ -252,6 +274,8 @@ def _parse_array_from_header(
         rows, consumed = _parse_tabular_body(lines, header_line + 1, depth, fields, count)
         if count >= 0 and len(rows) != count:
             raise ValueError(f"count_mismatch: declared {count}, got {len(rows)}")
+        if keyed:
+            return keyed_rows_to_map(rows, fields), consumed + 1
         return rows, consumed + 1
 
     items, consumed = _parse_expanded_body(lines, header_line + 1, depth)
@@ -260,6 +284,27 @@ def _parse_array_from_header(
     return items, consumed + 1
 
 
+def _find_bracket_start(s: str) -> int:
+    # Find " [" (the named-array count bracket) that is OUTSIDE any quoted name,
+    # so a quoted section/key name containing " [" (e.g. `## "a [1] b"`) is not
+    # misread as a named-array header. Mirrors _find_closing_brace's quote tracking.
+    in_quote = False
+    escaped = False
+    for i, c in enumerate(s):
+        if escaped:
+            escaped = False
+            continue
+        if c == "\\" and in_quote:
+            escaped = True
+            continue
+        if c == '"':
+            in_quote = not in_quote
+            continue
+        if not in_quote and c == " " and i + 1 < len(s) and s[i + 1] == "[":
+            return i
+    return -1
+
+
 def _find_closing_brace(s: str) -> int:
     in_quote = False
     escaped = False
@@ -521,6 +566,11 @@ def _parse_tabular_body(
         if row_has_id:
             inline_idx = 0
 
+            # Columns that carry a `^` marker cell in this row legitimately expect
+            # a `.field` body. Any other `.field` is an orphan (Section 16.5) unless
+            # its name contains `>` (the flatten-fallback attachment, Section 7.4.6.1.4).
+            expected_att = set(traditional_att_fields) | set(inline_att_fields)
+
             while i < len(lines):
                 a_line = lines[i]
                 a_content: str | None = None
@@ -541,6 +591,14 @@ def _parse_tabular_body(
                     att_name, after_name = _parse_attachment_name(rest)
                     after_name_stripped = after_name.lstrip()
 
+                    # Orphan attachment: a `.field` with no matching `^` cell in this
+                    # row is only legitimate for a `>`-named field (Section 7.4.6.1.4).
+                    # Any other unmatched attachment is rejected rather than silently
+                    # injected as an undeclared extra field, which would decode to a
+                    # record no encoder produces (Section 16.5, lossless round-trip).
+                    if att_name not in expected_att and ">" not in att_name:
+                        raise ValueError(f"orphan_attachment: {att_name}")
+
                     # Prefixed inline data.
                     ifs = inline_schemas.get(att_name)
                     if ifs and not after_name_stripped.startswith("{}") and not after_name_stripped.startswith("["):
@@ -613,8 +671,22 @@ def _parse_tabular_body(
                     if extra_name in attachment_values:
                         raise ValueError(f"duplicate_attachment: {extra_name}")
 
+        # Reconstruct the row in declared field-union order. A flattened group is
+        # emitted at the position of its first path column, so the nested object
+        # reappears where the original field was, not appended at the end (SPEC
+        # 7.4.6.1 step 7 and the key-order preservation requirement, SPEC 52, 931).
+        nested = _unflatten_paths(path_column_map, flat_values, flat_absent) if path_column_map else {}
+        emitted_groups: set[str] = set()
         row: dict[str, Any] = {}
         for f in fields:
+            if f in path_column_map:
+                top = path_column_map[f][0]
+                if top in emitted_groups:
+                    continue
+                emitted_groups.add(top)
+                if top in nested:  # omitted when the whole group is absent
+                    row[top] = nested[top]
+                continue
             if f in missing_fields:
                 continue
             if f in cell_values:
@@ -625,10 +697,6 @@ def _parse_tabular_body(
         for k, v in attachment_values.items():
             if k not in row:
                 row[k] = v
-        # Unflatten path columns into nested objects.
-        if path_column_map:
-            nested = _unflatten_paths(path_column_map, flat_values, flat_absent)
-            row.update(nested)
 
         rows.append(row)
 
@@ -725,7 +793,7 @@ def _validate_summary_counts(
     current_count = 0
     for line in content_lines:
         trimmed = line.lstrip()
-        if trimmed.startswith("## ") and "[?]" in trimmed:
+        if trimmed.startswith("## ") and ("[?]" in trimmed or "[?:]" in trimmed):
             if in_deferred:
                 actual_counts.append(current_count)
             in_deferred = True

gcf/delta.py

@@ -1,7 +1,8 @@
 """GCF delta encoding: only added/removed symbols for incremental delivery."""
 
-from .constants import KIND_ABBREV
-from .types import DeltaPayload
+from .constants import KIND_ABBREV, KIND_EXPAND
+from .packroot import pack_root
+from .types import DeltaPayload, Edge, Symbol
 
 
 def encode_delta(d: DeltaPayload) -> str:
@@ -37,7 +38,9 @@ def encode_delta(d: DeltaPayload) -> str:
         parts.append("## added")
         for i, s in enumerate(d.added):
             kind = KIND_ABBREV.get(s.kind, s.kind)
-            parts.append(f"@{i} {kind} {s.qualified_name} {s.score:.2f} {s.provenance}")
+            parts.append(
+                f"@{i} {kind} {s.qualified_name} {s.score:.2f} {s.provenance} {s.distance}"
+            )
 
     # Removed edges.
     if d.removed_edges:
@@ -52,3 +55,183 @@ def encode_delta(d: DeltaPayload) -> str:
             parts.append(f"{e.source} -> {e.target} {e.edge_type}")
 
     return "\n".join(parts) + "\n"
+
+
+def _expand_kind(k: str) -> str:
+    """Reverse a kind abbreviation to its full form (identity if unknown)."""
+    return KIND_EXPAND.get(k, k)
+
+
+def _parse_delta_edge(line: str) -> Edge:
+    """Parse a `source -> target type` delta edge line."""
+    idx = line.find(" -> ")
+    if idx < 0:
+        raise ValueError(f"malformed_delta: edge line missing ' -> ': {line!r}")
+    source = line[:idx]
+    rest = line[idx + 4 :].split()
+    if len(rest) != 2:
+        raise ValueError(
+            f"malformed_delta: edge line {line!r} must be 'source -> target type'"
+        )
+    return Edge(source=source, target=rest[0], edge_type=rest[1])
+
+
+def decode_delta(wire: str) -> DeltaPayload:
+    """Parse a GCF graph delta wire payload back into a DeltaPayload.
+
+    Kind abbreviations on removed/added lines are expanded to their full form so the
+    result matches a base snapshot's symbol identities. Raises ValueError containing
+    ``malformed_delta`` on bad lines or unknown sections.
+    """
+    lines = wire.rstrip("\n").split("\n")
+    if not lines or lines[0] == "":
+        raise ValueError("missing_header: empty delta payload")
+    header = lines[0].rstrip("\r")
+    if not header.startswith("GCF profile=graph"):
+        raise ValueError(
+            "missing_profile: delta header must begin with 'GCF profile=graph'"
+        )
+
+    d = DeltaPayload()
+    for field in header.split():
+        kv = field.split("=", 1)
+        if len(kv) != 2:
+            continue
+        key, value = kv
+        if key == "tool":
+            d.tool = value
+        elif key == "base_root":
+            d.base_root = value
+        elif key == "new_root":
+            d.new_root = value
+
+    section = ""
+    for raw in lines[1:]:
+        line = raw.rstrip("\r")
+        if line == "":
+            continue
+        if line.startswith("## "):
+            section = line[3:].strip()
+            if section not in ("removed", "added", "edges_removed", "edges_added"):
+                raise ValueError(f"malformed_delta: unknown section {section!r}")
+            continue
+        if section == "removed":
+            parts = line.split()
+            if len(parts) != 2:
+                raise ValueError(
+                    f"malformed_delta: removed line {line!r} must be 'kind qname'"
+                )
+            d.removed.append(
+                Symbol(kind=_expand_kind(parts[0]), qualified_name=parts[1])
+            )
+        elif section == "added":
+            parts = line.split()
+            if len(parts) != 6:
+                raise ValueError(
+                    f"malformed_delta: added line {line!r} must be "
+                    "'@id kind qname score provenance distance'"
+                )
+            try:
+                score = float(parts[3])
+            except ValueError:
+                raise ValueError(f"malformed_delta: invalid added score {parts[3]!r}")
+            try:
+                dist = int(parts[5])
+            except ValueError:
+                raise ValueError(
+                    f"malformed_delta: invalid added distance {parts[5]!r}"
+                )
+            d.added.append(
+                Symbol(
+                    kind=_expand_kind(parts[1]),
+                    qualified_name=parts[2],
+                    score=score,
+                    provenance=parts[4],
+                    distance=dist,
+                )
+            )
+        elif section in ("edges_removed", "edges_added"):
+            e = _parse_delta_edge(line)
+            if section == "edges_removed":
+                d.removed_edges.append(e)
+            else:
+                d.added_edges.append(e)
+        else:
+            raise ValueError(
+                f"malformed_delta: data line {line!r} before any section header"
+            )
+    return d
+
+
+def verify_delta(
+    base_symbols: list[Symbol],
+    base_edges: list[Edge],
+    removed: list[Symbol],
+    added: list[Symbol],
+    removed_edges: list[Edge],
+    added_edges: list[Edge],
+    expected_new_root: str,
+) -> tuple[list[Symbol], list[Edge]]:
+    """Apply a delta to a base snapshot and verify the resulting pack root.
+
+    Symbols are matched by identity ``(kind, qualified_name)``; edges by
+    ``(source, target, edge_type)``. Raises ValueError containing ``delta_invalid``
+    when removing a symbol/edge that does not exist or adding one that already exists,
+    and ``root_mismatch`` when the recomputed pack root differs from
+    ``expected_new_root``. On success returns the applied ``(symbols, edges)``.
+    """
+    sym_map: dict[tuple[str, str], Symbol] = {}
+    for s in base_symbols:
+        sym_map[(s.kind, s.qualified_name)] = s
+
+    for s in removed:
+        key = (s.kind, s.qualified_name)
+        if key not in sym_map:
+            raise ValueError(
+                f"delta_invalid: removing symbol {s.kind} {s.qualified_name} "
+                "that does not exist in base"
+            )
+        del sym_map[key]
+
+    for s in added:
+        key = (s.kind, s.qualified_name)
+        if key in sym_map:
+            raise ValueError(
+                f"delta_invalid: adding symbol {s.kind} {s.qualified_name} "
+                "that already exists"
+            )
+        sym_map[key] = s
+
+    result_symbols = list(sym_map.values())
+
+    edge_map: dict[tuple[str, str, str], Edge] = {}
+    for e in base_edges:
+        edge_map[(e.source, e.target, e.edge_type)] = e
+
+    for e in removed_edges:
+        key = (e.source, e.target, e.edge_type)
+        if key not in edge_map:
+            raise ValueError(
+                f"delta_invalid: removing edge {e.source} -> {e.target} "
+                f"{e.edge_type} that does not exist"
+            )
+        del edge_map[key]
+
+    for e in added_edges:
+        key = (e.source, e.target, e.edge_type)
+        if key in edge_map:
+            raise ValueError(
+                f"delta_invalid: adding edge {e.source} -> {e.target} "
+                f"{e.edge_type} that already exists"
+            )
+        edge_map[key] = e
+
+    result_edges = list(edge_map.values())
+
+    computed_root = pack_root(result_symbols, result_edges)
+    if computed_root != expected_new_root:
+        raise ValueError(
+            f"root_mismatch: computed {computed_root}, expected {expected_new_root}"
+        )
+
+    return result_symbols, result_edges

gcf/encode.py

@@ -17,10 +17,16 @@ def encode(p: Payload) -> str:
     """
     parts: list[str] = []
 
-    # Build symbol index for edge references.
+    # Group symbols by distance (sorted by score descending within each group),
+    # then assign local IDs in output order so they are sequential in the wire
+    # (SPEC 16.1).
+    groups = _group_by_distance(p.symbols)
     sym_index: dict[str, int] = {}
-    for i, s in enumerate(p.symbols):
-        sym_index[s.qualified_name] = i
+    next_id = 0
+    for _distance, g_symbols in groups:
+        for s in g_symbols:
+            sym_index[s.qualified_name] = next_id
+            next_id += 1
 
     # Count valid edges (both endpoints in symbol index).
     valid_edges = sum(
@@ -28,14 +34,20 @@ def encode(p: Payload) -> str:
         if e.source in sym_index and e.target in sym_index
     )
 
-    # Header line.
-    header = f"GCF profile=graph tool={p.tool} budget={p.token_budget} tokens={p.tokens_used} symbols={len(p.symbols)} edges={valid_edges}"
+    # Header line (SPEC 16.1): omit budget/tokens/edges when zero, matching the
+    # reference encoder.
+    header = f"GCF profile=graph tool={p.tool}"
+    if p.token_budget > 0:
+        header += f" budget={p.token_budget}"
+    if p.tokens_used > 0:
+        header += f" tokens={p.tokens_used}"
+    header += f" symbols={len(p.symbols)}"
+    if valid_edges > 0:
+        header += f" edges={valid_edges}"
     if p.pack_root:
         header += f" pack_root={p.pack_root}"
     parts.append(header)
 
-    # Group symbols by distance.
-    groups = _group_by_distance(p.symbols)
     group_names = ["targets", "related", "extended"]
 
     for g_distance, g_symbols in groups:
@@ -52,17 +64,25 @@ def encode(p: Payload) -> str:
             kind = KIND_ABBREV.get(s.kind, s.kind)
             parts.append(f"@{idx} {kind} {s.qualified_name} {s.score:.2f} {s.provenance}")
 
-    # Edges section.
+    # Edges section. Order edges by source ID then target ID (then edge type
+    # for parallel edges) so the wire is canonical regardless of the order
+    # edges were provided (SPEC 16.1). Edge reordering is decode-invariant
+    # (edges are a set) and does not affect pack_root, which sorts edge records
+    # independently.
     if p.edges:
-        edge_lines: list[str] = []
+        resolved: list[tuple[int, int, str, str]] = []
         for e in p.edges:
             src_idx = sym_index.get(e.source)
             tgt_idx = sym_index.get(e.target)
             if src_idx is None or tgt_idx is None:
                 continue
-            line = f"@{tgt_idx}<@{src_idx} {e.edge_type}"
-            if e.status and e.status != "unchanged":
-                line += f" {e.status}"
+            resolved.append((src_idx, tgt_idx, e.edge_type, e.status))
+        resolved.sort(key=lambda r: (r[0], r[1], r[2]))
+        edge_lines: list[str] = []
+        for src_idx, tgt_idx, edge_type, status in resolved:
+            line = f"@{tgt_idx}<@{src_idx} {edge_type}"
+            if status and status != "unchanged":
+                line += f" {status}"
             edge_lines.append(line)
         parts.append(f"## edges [{len(edge_lines)}]")
         parts.extend(edge_lines)
@@ -71,15 +91,17 @@ def encode(p: Payload) -> str:
 
 
 def _group_by_distance(symbols: list[Symbol]) -> list[tuple[int, list[Symbol]]]:
-    """Group symbols by distance, preserving order."""
+    """Group symbols by distance ascending, sorted by score descending within each
+    group (stable), matching the reference encoder so IDs are assigned canonically."""
     if not symbols:
         return []
 
+    ordered = sorted(symbols, key=lambda s: (s.distance, -s.score))
     groups: list[tuple[int, list[Symbol]]] = []
     current_distance: int | None = None
     current_symbols: list[Symbol] = []
 
-    for s in symbols:
+    for s in ordered:
         if current_distance is None or current_distance != s.distance:
             if current_symbols:
                 groups.append((current_distance, current_symbols))  # type: ignore[arg-type]

gcf/generic.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass
 from typing import Any
 
 from .scalar import format_scalar, format_key
+from .keyed_map import keyed_map_eligible
 
 
 @dataclass
@@ -30,6 +31,11 @@ def _encode_root_value(v: Any, out: list[str], opts: GenericOptions) -> None:
     if v is None:
         out.append("=-")
     elif isinstance(v, dict):
+        km = keyed_map_eligible(v)
+        if km is not None:
+            keys, values, value_fields, key_label = km
+            _encode_keyed_map("", False, keys, values, value_fields, key_label, out, 0, opts)
+            return
         _encode_object(v, out, 0, opts)
     elif isinstance(v, list):
         _encode_root_array(v, out, opts)
@@ -42,6 +48,11 @@ def _encode_object(d: dict, out: list[str], depth: int, opts: GenericOptions) ->
     for key, value in d.items():
         fk = format_key(key)
         if isinstance(value, dict):
+            km = keyed_map_eligible(value)
+            if km is not None:
+                keys, values, value_fields, key_label = km
+                _encode_keyed_map(key, True, keys, values, value_fields, key_label, out, depth, opts)
+                continue
             out.append(f"{prefix}## {fk}")
             _encode_object(value, out, depth + 1, opts)
         elif isinstance(value, list):
@@ -165,8 +176,9 @@ def _analyze_flattenable(
     arr: list[dict], field_name: str, parent_path: str
 ) -> list[dict] | None:
     """Analyze whether a field can be flattened. Returns list of leaf descriptors or None."""
-    # Field names containing ">" cannot be flattened (would create ambiguous paths).
-    if ">" in field_name:
+    # A field name that is empty or contains ">" cannot be flattened: it would create an
+    # ambiguous path column the decoder treats as literal (SPEC 7.4.6.1.3).
+    if field_name == "" or ">" in field_name:
         return None
     canonical_shape: dict[str, str] | None = None  # key -> "scalar" | "nested"
 
@@ -192,7 +204,7 @@ def _analyze_flattenable(
         if canonical_shape is None:
             canonical_shape = {}
             for k in keys:
-                if ">" in k:
+                if k == "" or ">" in k:  # empty/">" -> ambiguous path (SPEC 7.4.6.1.3)
                     return None
                 val = v[k]
                 if isinstance(val, list):
@@ -272,8 +284,53 @@ def _resolve_key_chain(item: Any, keys: list[str]) -> tuple[Any, bool]:
     return current, True
 
 
+# ── Keyed map encoding (SPEC 7.2a) ───────────────────────────────────────
+
+
+def _keyed_header_prefix(name: str, named: bool, depth: int) -> str:
+    """Build the keyed-table header prefix up to the count bracket. named
+    distinguishes an anonymous root keyed map (`## `) from a named member whose
+    name may itself be the empty string (`## ""`), which format_key quotes so it
+    round-trips as a distinct level rather than collapsing into the anonymous
+    root form (SPEC 7.2a.1)."""
+    prefix = _indent(depth)
+    if not named:
+        return f"{prefix}## "
+    return f"{prefix}## {format_key(name)} "
+
+
+def _encode_keyed_map(
+    name: str, named: bool, keys: list[str], values: list[Any],
+    value_fields: list[str], key_label: str, out: list[str], depth: int, opts: GenericOptions
+) -> None:
+    """Emit a keyed table for a map of objects. Routes through _encode_tabular
+    with the keyed bracket so nested-value handling (flatten/inline/attachment/
+    null/absent) is inherited unchanged. name is empty for a root/anonymous map."""
+    _encode_keyed_map_with_prefix(
+        _keyed_header_prefix(name, named, depth), keys, values,
+        value_fields, key_label, out, depth, opts,
+    )
+
+
+def _encode_keyed_map_with_prefix(
+    header_prefix: str, keys: list[str], values: list[Any],
+    value_fields: list[str], key_label: str, out: list[str], depth: int, opts: GenericOptions
+) -> None:
+    """Emit `<header_prefix>[N:]{...}` and the keyed rows, reusing _encode_tabular.
+    Each value object is augmented with the key column and encoded as a tabular
+    row; the key column is declared first."""
+    fields = [key_label] + value_fields
+    arr: list[dict] = []
+    for k, v in zip(keys, values):
+        aug = dict(v)
+        aug[key_label] = k
+        arr.append(aug)
+    _encode_tabular(header_prefix, arr, fields, out, depth, opts, keyed=True)
+
+
 def _encode_tabular(
-    header_prefix: str, arr: list[dict], fields: list[str], out: list[str], depth: int, opts: GenericOptions
+    header_prefix: str, arr: list[dict], fields: list[str], out: list[str], depth: int,
+    opts: GenericOptions, keyed: bool = False
 ) -> None:
     prefix = _indent(depth)
 
@@ -320,7 +377,8 @@ def _encode_tabular(
             shared_arr_schemas[f] = sas
 
     header_fields = ",".join(col["header"] for col in columns)
-    out.append(f"{header_prefix}[{len(arr)}]{{{header_fields}}}")
+    br = ":]" if keyed else "]"
+    out.append(f"{header_prefix}[{len(arr)}{br}{{{header_fields}}}")
 
     for i, item in enumerate(arr):
         cells: list[str] = []
@@ -401,8 +459,15 @@ def _encode_tabular(
                 else:
                     _encode_attachment_array(prefix, fk, att_val, out, depth + 2, opts)
             elif isinstance(att_val, dict):
-                out.append(f"{prefix}.{fk} {{}}")
-                _encode_object(att_val, out, depth + 2, opts)
+                km = keyed_map_eligible(att_val)
+                if km is not None:
+                    keys, values, value_fields, key_label = km
+                    _encode_keyed_map_with_prefix(
+                        f"{prefix}.{fk} ", keys, values, value_fields, key_label, out, depth + 2, opts,
+                    )
+                else:
+                    out.append(f"{prefix}.{fk} {{}}")
+                    _encode_object(att_val, out, depth + 2, opts)
             else:
                 # Scalar attachment (e.g. field names containing ">").
                 if att_val is None:
@@ -467,6 +532,13 @@ def _encode_expanded(header_prefix: str, arr: list, out: list[str], depth: int,
     out.append(f"{header_prefix}[{len(arr)}]")
     for i, item in enumerate(arr):
         if isinstance(item, dict):
+            km = keyed_map_eligible(item)
+            if km is not None:
+                keys, values, value_fields, key_label = km
+                _encode_keyed_map_with_prefix(
+                    f"{prefix}@{i} ", keys, values, value_fields, key_label, out, depth + 1, opts,
+                )
+                continue
             out.append(f"{prefix}@{i} {{}}")
             _encode_object(item, out, depth + 1, opts)
         elif isinstance(item, list):