merge: the vocabulary guard, and a build doc that keeps what it is given

`test_vocabulary.py` pins that a library does not name its consumers'
internals -- the guard that keeps a leaf package a leaf.

The build-doc fixes are the larger half. The canonical document was lossy
in three places -- NATIVE_TONGUE, the whole EQUIPMENT section, and
Resistant Protection's PD/ED split -- and every one of them round-tripped
to the same TOTAL, so cost parity never caught them and never could. One
of the three did move a total (Bokor, 276 -> 279) and that is how the
other two were found.

Suite 1811, 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

tests/test_vocabulary.py

@@ -0,0 +1,121 @@
+"""A library does not name its consumers' internals.
+
+kirby-combat, kirby-cost, kirby-dice and kirby-terrain are standalone
+packages. A comment here that names a module in a consuming application --
+or worse, cites line numbers inside it -- is a leaky abstraction and a
+guaranteed source of rot: those offsets were pinned against a file in
+another repository that no CI here can check, and they were wrong within
+weeks. Describe the ROLE ("the consumer's driver", "the chooser") and the
+comment stays true for as long as the role does.
+
+The same rule covers vendor and product names. This package models
+CHOOSING -- a `chooser`, an `option`, a `situation`, a `decide()` -- and
+that vocabulary is deliberately neutral about what implements the choice.
+The neutrality is the better design as well as the tidier one: a scripted
+chooser and any other kind are then indistinguishable to the engine, which
+is exactly what lets a fight run with no dependencies at all.
+
+A comment convention does not survive contact with a year of commits. This
+does, because it fails the build. It follows the same shape as
+kirby-terrain's leaf test: assert the property, then assert the assertion
+could actually fail.
+
+To permit a genuine exception, add it to ALLOW with a reason. Deliberate
+and reviewable beats a silently widened pattern.
+"""
+import pathlib
+import re
+import subprocess
+
+#: Unambiguous vendor, product and technique names. Deliberately NOT "ai":
+#: `ai = AttackInput(...)` is an ordinary local in several tests, so banning
+#: it would train everyone to ignore this test -- the failure mode that ends
+#: with the guard deleted.
+TERMS = [
+    "llm", "ollama", "anthropic", "openai", "gpt", "chatgpt", "claude",
+    "gemini", "mistral", "llama", "huggingface", "copilot", "bedrock",
+    "medialib", "prompt",
+]
+
+#: Underscore is a word character, so `\bllm\b` does NOT match `llm_driver` --
+#: the exact string this test exists to catch. These lookarounds treat any
+#: non-alphanumeric as a boundary, so `llm_driver`, `LLM-driver` and `(llm)`
+#: all match.
+PATTERN = re.compile(
+    "|".join(rf"(?<![a-z0-9]){t}(?![a-z0-9])" for t in TERMS), re.IGNORECASE
+)
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+
+#: (path, matched term) -> why it is allowed to stay.
+ALLOW: dict[tuple[str, str], str] = {
+    (".gitignore", "claude"): "editor tooling directory, not a project reference",
+}
+
+
+def _tracked_files() -> list[str]:
+    """Every file git tracks -- source, README, pyproject, CI workflows.
+
+    Uses git rather than rglob so the scan covers exactly what is published
+    and nothing that is not: no .venv, no build artefacts, no local scratch.
+    """
+    out = subprocess.run(
+        ["git", "-C", str(ROOT), "ls-files"],
+        capture_output=True, text=True, check=True,
+    )
+    return out.stdout.split()
+
+
+def _offenders() -> list[str]:
+    found: list[str] = []
+    here = pathlib.Path(__file__).name
+    for rel in _tracked_files():
+        # This file necessarily contains every banned term.
+        if pathlib.Path(rel).name == here:
+            continue
+        path = ROOT / rel
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue  # binary or unreadable; nothing to read anyway
+        for lineno, line in enumerate(text.splitlines(), 1):
+            for match in PATTERN.finditer(line):
+                term = match.group(0).lower()
+                if (rel, term) in ALLOW:
+                    continue
+                found.append(f"{rel}:{lineno}: {term!r} in {line.strip()[:80]!r}")
+    return found
+
+
+def test_the_published_source_names_no_inference_vocabulary() -> None:
+    offenders = _offenders()
+    assert offenders == [], (
+        "A library must not name its consumers' internals. These "
+        "references do:\n  "
+        + "\n  ".join(offenders)
+        + "\n\nRephrase to describe the ROLE ('the consumer's driver', 'the "
+          "chooser') rather than the implementation. If a reference is "
+          "genuinely necessary, add it to ALLOW with a reason."
+    )
+
+
+def test_the_guard_would_notice_a_leak() -> None:
+    """Guards the guard.
+
+    A word-boundary bug would make the test above pass on every input while
+    appearing to work -- so assert against the specific string that motivated
+    it, underscore and all.
+    """
+    assert PATTERN.search("see llm_driver.py for details")
+    assert PATTERN.search("calls the Anthropic API")
+    assert PATTERN.search("OLLAMA_BASE_URL")
+    # ...and does not fire on ordinary prose or an `ai` local.
+    assert not PATTERN.search("ai = AttackInput(attacker=a, target=b)")
+    assert not PATTERN.search("the domain contains available terrain")
+
+
+def test_the_scan_actually_reads_files() -> None:
+    """A `git ls-files` that returned nothing would make the guard vacuous."""
+    tracked = _tracked_files()
+    assert len(tracked) > 5, tracked
+    assert any(f.endswith(".py") for f in tracked)