feat(fix): repeating-group support in the message framework (closes #423)

[TexasCoding]

Summary

Repeating-group support for the typed FIX message framework — the prerequisite for the order-entry, market-data, and settlement message phases. Builds on the merged foundation (#422).

What's included

• FixGroupMeta + groupfield() — declare a repeating group as
  Annotated[list[Entry], FixGroupMeta(NumInGroupTag, Entry)] = groupfield(). The entry-model class rides on Annotated metadata (it isn't JSON-serializable, so it can't live on json_schema_extra like scalar metadata does).
• Shared _FixFieldModel base (now under FixMessage and a new FixGroup):
  • to_body_fields() is layout-driven — scalars and groups are emitted in declaration order; a group emits NumInGroup then each entry's fields; empty groups are omitted; nesting works.
  • from_raw() parses scalars by tag and groups positionally — each entry is delimited by the entry model's first-field tag and bounded by the entry's member-tag set, which naturally captures (and recurses into) nested groups.
• messages/components.py — shared entry models reused by later phases: Party (NoPartyIDs), MiscFee (NoMiscFees), CollateralAmountChange (NoCollateralAmountChanges), MultivariateSelectedLeg (NoMultivariateSelectedLegs), and the nested MarketSettlementParty (NoMarketSettlementPartyIDs → NoCollateralAmountChanges + NoMiscFees). Amounts use DollarDecimal, quantities FixedPointCount.

Design note

Positional group decoding assumes group-member tags are distinct from top-level scalar tags — true for the Kalshi FIX dictionary v1.03 — so a scalar is found by first occurrence without colliding with a same-tagged field inside a group.

Tests (tests/fix/test_groups.py, 7 new)

Flat group round-trip (multiple entries) with a trailing scalar after the group (boundary correctness); on-wire layout (count → delimiter → trailing scalar order); empty-group omission; single-entry group; DollarDecimal coercion from a string (no float drift); nested-group round-trip (incl. a party with an empty nested misc-fees group); and a nested-group on-wire structure assertion.

Verification

• uv run ruff check . — clean
• uv run mypy kalshi/ (strict) — clean (149 files)
• uv run pytest tests/fix/ — 104 passed

Closes #423. Part of #402.

🤖 Generated with Claude Code

[claude]

Code Review: feat(fix): repeating-group support

Overview

Solid implementation of FIX repeating-group support. The architecture is clean: extracting shared encode/decode machinery into _FixFieldModel, riding group metadata on Annotated rather than json_schema_extra (smart given JSON-serialization constraints), and positional decoding bounded by a member-tag set. The documented assumption (group tags are distinct from top-level tags) is realistic for the Kalshi FIX dictionary.

---

Issues

Medium: Public API exposes a private type

@dataclass(frozen=True)
class FixGroupMeta:
    num_in_group_tag: int
    entry_model: type[_FixFieldModel]   # _FixFieldModel is private

FixGroupMeta is exported from __init__.py, but entry_model is annotated with the private _FixFieldModel. Users writing strict-typed code will touch an implementation detail they should not see. The intended constraint is type[FixGroup] — consider reordering so FixGroup is defined before FixGroupMeta and using that, or use type[BaseModel] as a looser bound.

Minor: Count/entry mismatch silently tolerated

entries, _ = _parse_group(pairs, idx + 1, count, spec.entry_model)
kwargs[spec.name] = entries   # no assertion that len(entries) == count

If NumInGroup says 3 but the wire only delivers 2 complete entries (malformed FIX), the model is silently built with 2 entries. A warnings.warn or custom FixDecodeWarning when len(entries) != count would surface this during debugging.

Minor: ValueError on bad count is swallowed silently

try:
    count = int(pairs[idx][1])
except ValueError:
    continue   # entire group silently dropped

When NumInGroup is not a valid integer the whole group is dropped without any signal. A debug-level log or re-raise as FixDecodeError would make protocol bugs visible.

Minor: _first_tag() undocumented edge case

_first_tag() returns spec.count_tag when the first layout entry is a _GroupSpec. That is technically valid (count tag becomes the delimiter), but no FIX standard puts a nested group as the first field of a group entry. The docstring says "the first declared field's tag" without covering this case — a one-line note avoids future confusion.

---

Suggestions

Tag-uniqueness assumption — a cheap runtime guard:

# assert no overlap between top-level scalar tags and group member tags
# under __debug__ (fires once per class; free in production with -O)

This converts a silent wrong-parse into an early, obvious error if a future dictionary revision violates the assumption.

_parse_group dual-termination deserves a note in the docstring:

The loop terminates on both the count guard and tag-not-in-member-set. The count upper bound guards against pathological data, but the boundary logic would work for valid FIX without it. A one-liner prevents the next reader from wondering why both conditions exist.

---

Test Coverage

7 tests cover the happy paths well. Gaps worth a follow-up issue:

• Malformed NumInGroup value (e.g., "abc") — confirm silent-skip is intentional.
• NumInGroup says 3 but only 2 entries on the wire — what does the caller receive?
• Empty entry model hitting _first_tag() — confirms the ValueError fires correctly.

---

Nits

• components.py: MiscFee.misc_fee_curr and misc_fee_type are required with no default. Per FIX spec 137/138/139 are all required on the wire, so this is correct — a brief comment would help since misc_fee_basis (891) being optional could confuse a future editor.
• The # type: ignore[arg-type] in test_decimal_group_field_coerces_without_float_drift is expected and fine; Pydantic's str -> DollarDecimal coercion is invisible to mypy.

---

Summary

Approve with minor follow-ups. The encoding/decoding logic is correct, the caching strategy is sound, and the positional-decoding algorithm handles nesting cleanly. The private-type leak in FixGroupMeta.entry_model is the one thing worth addressing before merge; the rest can live as issues.