Merge campaign rule overrides

A GM changes what the HERO template states, per campaign, and the change
reaches costing, display and combat with no edit anywhere else.

Six planned tasks plus a fix wave for the final whole-branch review, which
found seven paths where a rule was accepted and then silently did nothing --
the exact defect the feature exists to eliminate. Notably: the design's stated
premise that TemplateData is reached through ONE provider method was false
(there are four, and the loader preferred an unpatched one), a forced
defense/target/range lost to a second value-guard, and a forced uses_end=False
could never take effect. All now wired or refused at set() time with a reason.

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

Author: pdbethke

kirby_cost/campaign/__init__.py

@@ -0,0 +1,5 @@
+"""A campaign's own rules: what this GM changed about the HERO template."""
+from kirby_cost.campaign.active import use_campaign_rules
+from kirby_cost.campaign.rules import CampaignRules, OVERRIDABLE_FIELDS
+
+__all__ = ["CampaignRules", "OVERRIDABLE_FIELDS", "use_campaign_rules"]

kirby_cost/campaign/active.py

@@ -0,0 +1,36 @@
+"""Scoping the active campaign.
+
+The engine is global by design -- `set_active_hero` is a process-wide
+singleton and loading a character mutates it -- so a campaign slot matches the
+surrounding shape. What the bare setter does not give you is restoration, and
+without it a caller that sets rules and forgets leaks them into everything
+that follows in the process.
+
+CONCURRENCY: process-global, exactly as `active_hero` already is. That is a
+pre-existing property of this engine, not one this feature introduces, and it
+is not solved here. Anyone serving two campaigns from one process needs to
+read this note first.
+"""
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Optional
+
+from kirby_cost.core.context import EngineContext
+
+
+@contextmanager
+def use_campaign_rules(rules: Optional["CampaignRules"]):
+    """Run a block with *rules* active, restoring the previous value after.
+
+    Named `use_` rather than plainly `campaign_rules` because the latter
+    collides with `EngineContext.campaign_rules()`, the GETTER -- and a module
+    that needs both (tests/test_campaign_active.py does) ends up importing two
+    different things under one name.
+    """
+    previous = EngineContext.campaign_rules()
+    EngineContext.set_campaign_rules(rules)
+    try:
+        yield rules
+    finally:
+        EngineContext.set_campaign_rules(previous)

kirby_cost/campaign/rules.py

@@ -0,0 +1,189 @@
+"""A campaign's rule overrides, as a diff over the template.
+
+kirby-cost is the only thing in the platform that reads a `.hdt`, which makes
+it the only place a house rule can enter the model. This holds what a campaign
+changed -- four values wide for a campaign that changes four rules -- so that
+"what does this campaign change?" stays a question something can answer. A
+copy of Main6E cannot answer it.
+"""
+from __future__ import annotations
+
+import dataclasses
+import difflib
+from typing import Any, Iterable, Optional
+
+from kirby_cost.template.dataclasses import TemplateData
+
+#: Bookkeeping the provider writes, never a rule a GM sets. Excluded so it
+#: cannot be set as an override and then silently clobbered.
+_NOT_OVERRIDABLE = frozenset({"campaign_forced"})
+
+#: Fields a campaign may NOT set, and why. Derivation stays the rule so a new
+#: template fact is overridable automatically; this names the exceptions.
+#:
+#: Accepting a field nothing reads would mean a GM writes a rule, gets no
+#: error, and the rule silently does nothing -- the exact defect this feature
+#: exists to remove.
+#:
+#: HOW THIS SET WAS ESTABLISHED, field by field, so a later reader knows what
+#: is measurement and what is inference. Every `TemplateData` field except
+#: `campaign_forced` was accounted for. Each entry listed below was measured
+#: INERT -- forced, and the loaded object did not change. Of the rest:
+#:
+#:   * killing, does_body, does_damage, does_knockback, defense, target,
+#:     range, uses_end: wired by `apply_template` and each one locked by a
+#:     test in tests/test_campaign_beats_hdc.py that asserts the forced value
+#:     reaches the object and outranks a document-stated one.
+#:   * level_cost: measured end to end (tests/test_campaign_cost_fields.py:
+#:     Ravel's RKA moves 45 -> 30). display, level_value, level_power,
+#:     level_multiplier, min_set, max_set: read directly by `apply_template`
+#:     (base.py:398, :487-:509, :545, :551) and by `Adder.apply_template`.
+#:   * The nine below were the ones the first pass never probed. Each was
+#:     then forced through `CampaignRules` and observed changing a loaded
+#:     object, on 2026-08-25 (six via real character loads; three via
+#:     constructed objects, noted below):
+#:   * types      -> forcing ("PROBE",) on RKA gave Ravel's RKA `_types
+#:                   == ["PROBE"]` (base.py, the `tmpl.types` loop).
+#:   * attributes -> forcing SHOWOPTIONONLY="Yes" on PENETRATING flipped
+#:                   that modifier's `show_option_only` to True (base.py:291).
+#:   * adders     -> forcing {} emptied `_template_adder_order` on RKA.
+#:   * options    -> forcing LARGE's level_cost=77/level_multiplier=9 moved
+#:                   Bokor's GROWTH to exactly those (base.py:428).
+#:   * option_aliases -> with LARGE removed from `options`, forcing
+#:                   {"LARGE": "HUGE"} resolved GROWTH's option to HUGE.
+#:   * base_value -> forcing 42.0 on STR moved Ravel's STR `base_level`
+#:                   from 10.0 to 42.0 (hdc_loader.py:655).
+#:   * all_cost / group_cost / sense_cost -> forcing 55.0 on a sense-rate
+#:                   xmlid put 55.0 on all three of a constructed SenseAdder
+#:                   (base.py, the sense-rate loop; hdc_loader.py:1615).
+#:                   (These three were probed via apply_template on a built
+#:                   object, not a real character load, because none of the
+#:                   authored characters carries a SenseAdder.)
+#:
+#: The one field that is neither wired nor listed as a rule is `class_name`,
+#: below: it has ZERO reads off a `TemplateData` anywhere in `kirby_cost/`.
+_UNSUPPORTED_FIELDS = {
+    # apply_template never assigns tmpl.base_cost to a non-maneuver object
+    # (its only base_cost write is from an OPTION, base.py:440), and never
+    # reads _base_cost_from_xml. Making the template's price authoritative for
+    # every object changes how the engine costs everything and needs its own
+    # oracle-gated change. Use level_cost to re-price a power.
+    "base_cost": "not applied by apply_template; use level_cost to re-price",
+    # apply_template DOES assign these (base.py:546, :552) -- but gated on
+    # tmpl.min_set / tmpl.max_set, which are false for a typical power. And
+    # forcing min_set/max_set on would surface the TEMPLATE's own
+    # minimum_cost/max_cost, never a campaign-forced one, because this field
+    # is itself blocked. So the value a GM sets here can never reach an
+    # object by either route.
+    "minimum_cost": "gated on min_set, and forcing min_set surfaces the template's value, not this one",
+    "max_cost": "gated on max_set, and forcing max_set surfaces the template's value, not this one",
+    # Gated on the object not already having a duration, which it does by the
+    # time a campaign could matter.
+    "duration": "the object already holds a duration when the template applies",
+    # Not rules. Identity and a derived predicate.
+    "xmlid": "identity, not a rule",
+    "is_power": "derived from the object, not settable",
+    # Parsed by hdt_provider (:323) and dataclasses (:196) and then read by
+    # NOTHING: `grep -rn class_name kirby_cost/` finds only unrelated local
+    # variables in modifier.py and behaviors/registry.py, never a read off a
+    # TemplateData. Forcing it can therefore not change any loaded object.
+    "class_name": "carried by TemplateData but read by nothing, so forcing it cannot change a loaded object",
+}
+
+#: Every field of TemplateData, DERIVED rather than listed. Adding a template
+#: fact makes it overridable automatically. A hand-maintained list here would
+#: rebuild the exact trap this work came from -- a fact parsed into one
+#: structure and dropped because a second structure had no field for it.
+OVERRIDABLE_FIELDS = frozenset(
+    f.name for f in dataclasses.fields(TemplateData)
+) - _NOT_OVERRIDABLE - frozenset(_UNSUPPORTED_FIELDS)
+
+
+class CampaignRules:
+    """What one campaign changes about the template.
+
+    Validates at `set()` time against a real template, so a typo raises at the
+    line that wrote it rather than silently matching nothing all session.
+    """
+
+    def __init__(self, provider: Optional[Any] = None) -> None:
+        if provider is None:
+            from kirby_cost.template.hdt_provider import HDTTemplateProvider
+            # Raises FileNotFoundError with the provider's own message when no
+            # template is configured -- authoring rules that cannot be checked
+            # is the failure this class exists to prevent.
+            provider = HDTTemplateProvider()
+        self._provider = provider
+        self._overrides: dict[tuple[str, str], Any] = {}
+
+    def set(self, xmlid: str, field: str, value: Any) -> None:
+        # Checked before the OVERRIDABLE_FIELDS membership test below, and
+        # given its own message: an unsupported field IS a template field
+        # (it's a name a GM typed correctly), so the near-miss/typo message
+        # for an unknown field would be actively misleading here.
+        if field in _UNSUPPORTED_FIELDS:
+            raise ValueError(
+                f"{field!r} is a template field, but apply_template does not "
+                f"wire it into a loaded object, so a campaign rule on it "
+                f"would never take effect: {_UNSUPPORTED_FIELDS[field]}."
+            )
+        if field not in OVERRIDABLE_FIELDS:
+            near = difflib.get_close_matches(field, sorted(OVERRIDABLE_FIELDS), n=3)
+            hint = f" Did you mean: {', '.join(near)}?" if near else ""
+            raise ValueError(
+                f"{field!r} is not a template field, so nothing would ever "
+                f"read it.{hint}"
+            )
+        # A rule that sets None cannot do anything. `apply_template` skips a
+        # tri-state field whose template value is None (`if stated_value is
+        # None ... continue`), which is how "the template says nothing" is
+        # spelled -- so None means ABSENCE, not "revert to the class
+        # default". That second meaning is not a capability this engine has,
+        # and accepting None would only add another accepted-and-inert path.
+        if value is None:
+            raise ValueError(
+                f"a campaign rule cannot set {field!r} to None: None means "
+                f"'the template says nothing', so the rule would be skipped "
+                f"and do nothing. Set the value you want instead. (Reverting "
+                f"a field to its class default is not a capability that "
+                f"exists today.)"
+            )
+        # Template maneuvers carry no XMLID — DISPLAY is their sole identity.
+        # So `hdc_loader` routes them to `get_maneuver` (keyed by display), not
+        # to `get_template_data`. If allowed here, this rule would find nothing
+        # on the template side and do nothing. Moreover, patching here by xmlid
+        # would rewrite all 53 maneuvers at once (they all parse with the same
+        # XMLID="MANEUVER" in HDC). Refused here instead, before the check.
+        if xmlid.upper() == "MANEUVER":
+            raise ValueError(
+                "'MANEUVER' cannot be the subject of a campaign rule: template "
+                "maneuvers carry no XMLID (DISPLAY is their identity), so this "
+                "rule would find nothing on the template side. Moreover, all 53 "
+                "HDC maneuvers are written XMLID=\"MANEUVER\", so patching by "
+                "xmlid would rewrite all 53 at once. Overriding one maneuver "
+                "needs a rule keyed by display, which does not exist yet."
+            )
+        if self._provider.get_template_data(xmlid) is None:
+            raise ValueError(
+                f"{xmlid!r} is not in the loaded template, so this rule would "
+                f"never match anything. (An xmlid that EXISTS but that no "
+                f"character owns is fine -- this is about a name the template "
+                f"has never heard of.)"
+            )
+        self._overrides[(xmlid, field)] = value
+
+    def get(self, xmlid: str, field: str, default: Any = None) -> Any:
+        return self._overrides.get((xmlid, field), default)
+
+    def items(self) -> Iterable[tuple[str, str, Any]]:
+        return [(x, f, v) for (x, f), v in self._overrides.items()]
+
+    def fields_for(self, xmlid: str) -> frozenset:
+        """Field names this campaign forces for *xmlid*."""
+        return frozenset(f for (x, f) in self._overrides if x == xmlid)
+
+    def __bool__(self) -> bool:
+        return bool(self._overrides)
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"CampaignRules({len(self._overrides)} overrides)"

kirby_cost/core/context.py

@@ -11,6 +11,7 @@
     from kirby_cost.model.hero import Hero
     from kirby_cost.core.preferences import Preferences
     from kirby_cost.core.template import Template
+    from kirby_cost.campaign.rules import CampaignRules
 
 
 class EngineContext:
@@ -24,6 +25,7 @@ class EngineContext:
     _active_hero: Optional['Hero'] = None
     _active_template: Optional['Template'] = None
     _preferences: Optional['Preferences'] = None
+    _campaign_rules: Optional['CampaignRules'] = None
 
     def __init__(self):
         """Initialize EngineContext instance."""
@@ -60,7 +62,28 @@ def set_active_template(cls, template: Optional['Template']) -> None:
         """Set the currently active template."""
         instance = cls.get_instance()
         instance._active_template = template
-    
+
+    @classmethod
+    def campaign_rules(cls) -> Optional['CampaignRules']:
+        """The active campaign's rule overrides, or None.
+
+        DELIBERATELY separate from `active_template`. That slot has EIGHT
+        readers whose branches were never finished -- they only ever ran their
+        None side -- so populating it would switch eight stubs on at once
+        (counted 2026-08-25: continuous, nonpersistent, norangemodifier,
+        persistent, disadvantage, combat_sense, simulate_death,
+        universal_translator; base.py:1814 mentions the slot in prose and does
+        not read it). See the campaign-rule-overrides spec, section 7.
+        """
+        return cls.get_instance()._campaign_rules
+
+    @classmethod
+    def set_campaign_rules(cls, rules: Optional['CampaignRules']) -> None:
+        """Set the active campaign's rule overrides. Prefer the
+        `kirby_cost.campaign.use_campaign_rules` context manager, which restores
+        the previous value."""
+        cls.get_instance()._campaign_rules = rules
+
     @classmethod
     def prefs(cls) -> 'Preferences':
         """Get preferences."""

kirby_cost/objects/base.py

@@ -32,6 +32,13 @@
     from kirby_cost.objects.modifier import Modifier
     from kirby_cost.objects.list import List as HeroList
 
+#: Fields whose XML attribute name is NOT the de-underscored upper-case form.
+#: `uses_end` is gated on "END", not "USESEND" -- derive it and a campaign's
+#: forced override silently misses the guard, leaving the document's own
+#: value to win with no error. Add to this map, don't trust the derivation,
+#: whenever a new field's XML name diverges from its Python name.
+_XML_NAME_OVERRIDES = {"uses_end": "END"}
+
 
 class GenericObject(CostMixin, ModifierMixin, XMLAttrsMixin,
                     DeserializationMixin, SerializationMixin, ABC):
@@ -573,6 +580,33 @@ def apply_template(self, tmpl: "TemplateData", option_id: str = None) -> None:
         # subclass reads, and suppressing the template for an attribute that
         # was never loaded would leave the field at its constructor default.
         stated = self._stated_and_declared()
+        # A campaign's rules outrank the document. Everything below is guarded
+        # on "the source did not state this", which is right for a template
+        # default and wrong for a house rule: a rule a character can be exempt
+        # from is not a rule, so an attribute the campaign forced is removed
+        # from the guard, per attribute -- forcing one does not free the
+        # others. This does NOT cover the cost fields (base_cost,
+        # minimum_cost, max_cost) even though the corpus states BASECOST 371
+        # times: they are not gated by `stated` at all -- they are set through
+        # min_set/max_set and _base_cost_from_xml. That was measured, and the
+        # decision was to REFUSE those fields at `CampaignRules.set()` time
+        # rather than build a second branch here; see `_UNSUPPORTED_FIELDS` in
+        # kirby_cost/campaign/rules.py, which names each one and why. A GM who
+        # wants to re-price a power uses level_cost, which IS wired.
+        #
+        # The XML name is usually the field name upper-cased with underscores
+        # removed -- HD's own convention, used verbatim by the *_increase
+        # family further down this method. It is NOT always that: `uses_end`
+        # is gated on "END", not the derived "USESEND", so deriving it here
+        # would subtract a name that was never in `stated` and the campaign's
+        # rule would silently lose. Irregular names go in the override map.
+        forced = getattr(tmpl, "campaign_forced", frozenset())
+        forced_xml = {
+            _XML_NAME_OVERRIDES.get(f, f.upper().replace("_", ""))
+            for f in forced
+        }
+        if forced_xml:
+            stated = stated - forced_xml
 
         # TYPES come from the TEMPLATE. An object's own element rarely states
         # them -- Main6E declares `<DETECT ...><TYPE>SPECIAL</TYPE>
@@ -585,16 +619,33 @@ def apply_template(self, tmpl: "TemplateData", option_id: str = None) -> None:
             if declared and declared not in self._types:
                 self._types.append(declared)
 
-        if tmpl.uses_end and "END" not in stated:
+        # Each of these four carries a SECOND guard beyond `stated` -- on the
+        # object's CURRENT value ("only if it has no duration", "only if
+        # target is empty or N/A"), or, for uses_end, by only ever assigning
+        # True. Those guards stand in for the same precedence `stated` does,
+        # so removing a name from `stated` alone left the campaign losing
+        # anyway: measured, forced defense=NORMAL over a document that stated
+        # MENTAL came back MENTAL, forced target=SELFONLY over DCV came back
+        # DCV, forced range=LOS over "No" came back "No", and a forced
+        # uses_end=False could never be assigned at all. A forced field is
+        # therefore assigned UNCONDITIONALLY; the heuristic guards remain for
+        # the ordinary, uncampaigned path.
+        if "END" in forced_xml:
+            self.uses_end = tmpl.uses_end
+        elif tmpl.uses_end and "END" not in stated:
             self.uses_end = True
         if tmpl.duration and not self._duration and "DURATION" not in stated:
             self._duration = tmpl.duration
-        if tmpl.target and self.target in ("", "N/A") and "TARGET" not in stated:
+        if "TARGET" in forced_xml:
+            self.target = tmpl.target
+        elif tmpl.target and self.target in ("", "N/A") and "TARGET" not in stated:
             self.target = tmpl.target
         # DEFENSE, on the same terms as TARGET: the template states it, the
         # document rarely does, and the constructor's default is "NONE" --
         # which reads as an answer rather than as an absence.
-        if tmpl.defense and self.defense in ("", "NONE") and "DEFENSE" not in stated:
+        if "DEFENSE" in forced_xml:
+            self.defense = tmpl.defense
+        elif tmpl.defense and self.defense in ("", "NONE") and "DEFENSE" not in stated:
             self.defense = tmpl.defense
         # Combat facts stated by the template. These are what let a GM's house
         # rules reach the fight: kirby-cost reads the .hdt, so a campaign that
@@ -622,7 +673,9 @@ def apply_template(self, tmpl: "TemplateData", option_id: str = None) -> None:
         # RANGE is the word that decides whether a power reaches at all, and
         # only the template states it — an HDC file never does. Without it
         # every power read as un-ranged and range_value returned 0.
-        if getattr(tmpl, "range", "") and not (self.range or "").strip() \
+        if "RANGE" in forced_xml:
+            self.range = tmpl.range
+        elif getattr(tmpl, "range", "") and not (self.range or "").strip() \
                 and "RANGE" not in stated:
             self.range = tmpl.range