fix: the build doc was lossy in three places, and none of them cost a point

The canonical build doc is meant to be what a file corpus stores: the
rebuild document, no prose, round-trippable. Moving kirby-combat's suite
onto it found three things it silently forgot. Every one of them
round-tripped to the same TOTAL, which is why cost parity never caught
any of them and never could.

NATIVE_TONGUE. A native tongue is free, and the flag is the only thing
that says so -- the element still carries the option's base cost, so
Bokor's Creole is `OPTIONID="ACCENT" BASECOST="3.0"` with
`NATIVE_TONGUE="Yes"`. `Language._init` has always read it; nothing wrote
it back, so the reader rebuilt an ordinary three-point Language and Bokor
came back 279 points against the .hdc's 276. This one DID move a total,
and it is the reason the other two were looked for.

EQUIPMENT. `_SECTION_TAG` listed seven sections and equipment was not one
of them, so a character whose weapon is CARRIED round-tripped into being
unarmed. The loader has always read an <EQUIPMENT> section, with the same
`_load_powers_section` as powers -- 6E2 p.182: "Most equipment is built
with Powers" -- and kirby-combat has read `hero.equipment` for its
attacks since 2026-09-07. Only the document forgot. Verified on the HSEG
19th-century prefabs: 126 weapons in, 126 out.

THE PD/ED SPLIT. HD writes PDLEVELS/EDLEVELS/MDLEVELS/POWDLEVELS on a
Resistant Protection element and `ForceField.XML_ATTRS` has read them
since a re-export was caught losing the whole power. The doc never wrote
them, so Power Lad's 45 points rebuilt as 0/0 and the consumer was left
guessing which half was physical -- kirby-combat guessed half and half,
then capped the guess against natural PD, and he fought a gunfight at
rPD 2 instead of 25. Costing does not notice: HD prices the power by
LEVELS, so a doc without the split is worth exactly the same points and
looks correct. What it loses is the fight.

THE PATTERN IS THE FINDING. Three fields, three different places, and all
three invisible to a totals comparison. A document that is checked only
by its cost can drop anything the cost does not read -- which includes
most of what combat consumes. What this wants next is a round-trip test
that walks a real character field by field rather than comparing points.

Suite 1811 passed, oracle parity unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lvepxj9B2mDc4cRN3jaWwn

Author: pdbethke

kirby_cost/io/build_json.py

@@ -12,6 +12,13 @@ class BuildDocError(ValueError):
     "characteristics": "CHARACTERISTICS", "powers": "POWERS", "skills": "SKILLS",
     "perks": "PERKS", "talents": "TALENTS", "martial_arts": "MARTIALARTS",
     "disadvantages": "DISADVANTAGES",
+    # Carried gear. Shaped exactly like POWERS -- the loader builds it with
+    # the same `_load_powers_section` -- and 6E2 p.182 says why: "Most
+    # equipment is built with Powers". Missing here, a character whose
+    # weapon is carried rather than innate round-tripped UNARMED, silently,
+    # and kirby-combat has read `hero.equipment` for its attacks since
+    # 2026-09-07. Last of the seven sections to be written down.
+    "equipment": "EQUIPMENT",
 }
 # Cost-driving fields the loader's _init() reads off every element (power,
 # modifier, adder). Emitting the EFFECTIVE values back as their HDC attributes
@@ -55,14 +62,25 @@ class BuildDocError(ValueError):
     "body_levels": "BODYLEVELS", "width_levels": "WIDTHLEVELS",
     "cost_per_inch": "COSTPERINCH", "cost_per_body": "COSTPERBODY",
     "group": "GROUP",
+    # Resistant Protection's PD/ED/MD/POWD split. HD costs the power by
+    # LEVELS, so losing these did not move a single point and the round trip
+    # looked clean -- but the split is what COMBAT reads, and without it a
+    # consumer is left guessing which half of 45 is physical.
+    "pd_levels": "PDLEVELS", "ed_levels": "EDLEVELS",
+    "md_levels": "MDLEVELS", "powd_levels": "POWDLEVELS",
 }
 # Skill cost-mode flags the Skill loader reads in _init (skill.py:654-668). These
 # decide the base cost (familiarity=1 / proficiency=N / 3) and the adder-cost
 # discount path (AdderBasedSkill.total_cost). Without them a skill that defaulted
 # off in the HDC re-defaults ON (set_familiarity(True) at adder_based_skill.py:43),
 # dropping adder cost. Emit the EFFECTIVE flag (Yes/No) so the mode is preserved.
 _SKILL_FLAG = {"familiarity": "FAMILIARITY", "proficiency": "PROFICIENCY",
-               "levels_only": "LEVELSONLY", "everyman": "EVERYMAN"}
+               "levels_only": "LEVELSONLY", "everyman": "EVERYMAN",
+               # A native tongue is FREE, and the flag is the only thing that
+               # says so -- the element still carries the option's BASECOST.
+               # Missing here, Bokor's Creole rebuilt as an ordinary 3-point
+               # Language and he came back 279 points against the .hdc's 276.
+               "native_tongue": "NATIVE_TONGUE"}
 #: Input-only spellings of the same three flags. `Skill.to_build_dict` writes
 #: `familiarity`/`proficiency`/`everyman`, and so does this module's emitter --
 #: but the ORACLE's dump (hd6cli, the shape `tests/fixtures/authored/*.json`

kirby_cost/objects/powers/force_field.py

@@ -31,6 +31,27 @@ class ForceField(Power, xmlid="FORCEFIELD"):
         XMLAttr("POWDLEVELS", "powd_levels", "int"),
     )
 
+    def to_build_dict(self) -> dict:
+        """The split, which the cost does not depend on and the FIGHT does.
+
+        `XML_ATTRS` has read PDLEVELS/EDLEVELS off the element since a
+        re-export was found dropping the whole power. Writing them back was
+        missed because nothing in the COST notices: HD prices Resistant
+        Protection by LEVELS, so a doc without the split round-trips to the
+        same points and looks correct. What it loses is which half is
+        physical -- and kirby-combat, handed 45 and no split, guessed half
+        and half.
+
+        Emitted whenever non-zero, matching ForceWall's exporter one file
+        over; a power with no split of its own says nothing rather than
+        writing four zeroes.
+        """
+        d = super().to_build_dict()
+        for field in ("pd_levels", "ed_levels", "md_levels", "powd_levels"):
+            if getattr(self, field, 0):
+                d[field] = getattr(self, field)
+        return d
+
     def __init__(self):
         """Initialize a Force Field power."""
         super().__init__()

kirby_cost/objects/skills/language.py

@@ -106,7 +106,26 @@ def __init__(self, xmlid: str = None):
         self._minimum_cost = 0.0
         self._minimum_level = 0
         self._alias = "Language"
-    
+
+    def to_build_dict(self) -> dict:
+        """Everything `Skill` exports, plus the one flag that sets the price.
+
+        A native tongue is free. The element still carries the option's
+        BASECOST -- Bokor's Creole is `OPTIONID="ACCENT" BASECOST="3.0"` --
+        so `NATIVE_TONGUE` is the ONLY thing distinguishing a free language
+        from a three-point one. `_init` has always read it; nothing wrote it
+        back, so the canonical build doc was lossy in a way that changed a
+        character's total: Bokor round-tripped 276 -> 279, and every one of
+        those points was his mother tongue.
+
+        Written unconditionally rather than only when true: a reader that
+        sees the key absent cannot tell "not native" from "written by an
+        older exporter", and this document is the corpus's shape.
+        """
+        d = super().to_build_dict()
+        d["native_tongue"] = bool(self.native_tongue)
+        return d
+
     def _init(self, element) -> None:
         """Initialize from XML element, including native tongue flag."""
         super()._init(element)

tests/test_build_json.py

@@ -141,3 +141,128 @@ def test_user_wording_and_notes_survive_the_build_doc():
     again = build_from_json(to_build_json(hero)).powers[0]
     assert again.text_output == power.text_output
     assert again.notes == power.notes
+
+
+# ── A native tongue is free, and the doc has to remember that ────────────────
+
+NATIVE = dict(MINIMAL, skills=[
+    # Bokor's Creole, as HERO Designer writes it: OPTIONID="ACCENT",
+    # BASECOST="3.0", NATIVE_TONGUE="Yes". The base cost on the element is
+    # the price of the option, and the flag is what makes it free.
+    {"id": "S1", "xmlid": "LANGUAGES", "option_id": "ACCENT",
+     "base_cost": 3.0, "alias": "Language", "input": "Creole",
+     "skill": True, "native_tongue": True},
+])
+
+
+def _creole(hero):
+    return [s for s in hero.skills if s.xmlid == "LANGUAGES"][0]
+
+
+def test_a_native_tongue_costs_nothing_through_the_build_doc():
+    """Found by moving kirby-combat's suite onto build docs (2026-09-08):
+    Bokor came back 279 points against the .hdc's 276, and the whole
+    difference was his Creole.
+
+    `Language` parses `NATIVE_TONGUE` and prices on it, but had no
+    `to_build_dict` of its own, so the flag never reached the document.
+    The reader then rebuilt an ordinary 3-point Language. The .hdc path
+    is the one validated against the Java oracle, and it says 0.
+    """
+    assert _creole(build_from_json(NATIVE)).real_cost == 0.0
+
+
+def test_a_language_that_is_not_native_still_costs():
+    """Guards the guard: the flag must not zero every Language."""
+    doc = dict(NATIVE, skills=[dict(NATIVE["skills"][0], native_tongue=False)])
+    assert _creole(build_from_json(doc)).real_cost == 3.0
+
+
+def test_the_flag_survives_a_round_trip_out_and_back():
+    """The writer's half. A doc that loses the flag reads as a legal
+    document and prices a character wrongly, which is the worst shape a
+    serializer can have."""
+    once = build_from_json(NATIVE)
+    doc = to_build_json(once)
+    assert doc["skills"][0].get("native_tongue") is True
+    assert _creole(build_from_json(doc)).real_cost == 0.0
+
+
+# ── A carried weapon is part of the build ────────────────────────────────────
+
+EQUIPPED = dict(MINIMAL, equipment=[
+    {"id": "E1", "xmlid": "RKA", "levels": 2, "base_cost": 0.0,
+     "level_cost": 15.0, "level_value": 1.0,
+     "alias": "Killing Attack - Ranged", "name": "Revolver"},
+])
+
+
+def test_equipment_survives_the_build_doc():
+    """Found converting kirby-combat off raw .hdc (2026-09-08): the doc had
+    no equipment section at all.
+
+    `_SECTION_TAG` listed characteristics, powers, skills, perks, talents,
+    martial arts and disadvantages -- so a character whose weapon is CARRIED
+    round-tripped without it, silently, and arrived unarmed. The loader has
+    always read one (`hero.equipment = _load_powers_section(root,
+    "EQUIPMENT")`), and kirby-combat has read `hero.equipment` for its
+    attacks since 2026-09-07; only the document forgot.
+    """
+    hero = build_from_json(EQUIPPED)
+    assert [e.name for e in hero.equipment] == ["Revolver"]
+
+
+def test_equipment_is_written_back_out():
+    doc = to_build_json(build_from_json(EQUIPPED))
+    assert [e["name"] for e in doc.get("equipment", [])] == ["Revolver"]
+
+
+def test_a_carried_weapon_keeps_its_cost_across_the_round_trip():
+    """The half that matters: equipment that survives by name but not by
+    cost is worse than equipment that vanishes, because it looks right."""
+    once = build_from_json(EQUIPPED)
+    twice = build_from_json(to_build_json(once))
+    costs = [e.real_cost for e in once.equipment]
+    assert costs, "nothing to compare — the weapon did not survive at all"
+    assert [e.real_cost for e in twice.equipment] == costs
+
+
+# ── Resistant Protection keeps its PD/ED split ───────────────────────────────
+
+PROTECTED = dict(MINIMAL, powers=[
+    # Power Lad's "Body Like Iron": LEVELS 45 split 25 PD / 20 ED. HD costs
+    # the power by the split, and combat READS the split -- 25 rPD is the
+    # difference between shrugging off a revolver and being killed by one.
+    {"id": "P1", "xmlid": "FORCEFIELD", "levels": 45, "base_cost": 0.0,
+     "level_cost": 3.0, "level_value": 2.0, "alias": "Resistant Protection",
+     "name": "Body Like Iron", "pd_levels": 25, "ed_levels": 20},
+])
+
+
+def _protection(hero):
+    return [p for p in hero.powers if p.xmlid == "FORCEFIELD"][0]
+
+
+def test_resistant_protection_keeps_its_split_through_the_build_doc():
+    """`ForceField.XML_ATTRS` has read PDLEVELS/EDLEVELS off the .hdc since
+    the day someone noticed a re-export losing the whole power. The build
+    doc never wrote them, so a character whose armor is Resistant
+    Protection rebuilt with the split at 0/0 and the consumer left to
+    guess -- kirby-combat guessed half and half, then capped the guess
+    against natural PD, and Power Lad fought at rPD 2 against 25.
+    """
+    p = _protection(build_from_json(PROTECTED))
+    assert (p.pd_levels, p.ed_levels) == (25, 20)
+
+
+def test_the_split_is_written_back_out():
+    doc = to_build_json(build_from_json(PROTECTED))
+    node = [n for n in doc["powers"] if n["xmlid"] == "FORCEFIELD"][0]
+    assert (node.get("pd_levels"), node.get("ed_levels")) == (25, 20)
+
+
+def test_the_split_survives_two_round_trips():
+    once = build_from_json(PROTECTED)
+    twice = build_from_json(to_build_json(once))
+    assert (twice.powers[0].pd_levels, twice.powers[0].ed_levels) == (25, 20)
+    assert twice.powers[0].real_cost == once.powers[0].real_cost