feat: model specialization combat effects

docs/architecture.md

@@ -290,6 +290,62 @@ previews all four states, preventing duplicated tier data from diverging.
 Skill Chip mutations, owned relationships, and safe icon metadata are captured
 in the `game_data` audit stream.
 
+# Specialization combat effects and loadout state
+
+`specialization_combat_effects` stores reusable effect identity and description
+within one Specialization. A node rank attaches that identity through
+`specialization_tree_rank_combat_effects` and supplies the trigger count,
+trigger window, duration, stack limit, and stack gain. The first supported
+lifecycle uses an enemy-hit counter that resets after a proc. Each stack gain
+refreshes one shared duration, and expiry clears all stacks.
+
+`specialization_tree_rank_combat_modifiers` maps each attachment to one or more
+Attributes with a value per stack. This split lets ranks share effect language
+while changing their trigger and values. Specialization mutations capture the
+attachment and modifier sets in the `game_data` audit event. Contributors can
+submit effect definitions and node attachments through the existing
+Specialization proposal workflow.
+
+Loadout schema version 2 stores one focus, the selected rank for each tree node,
+nine Skill Chips, conditional-effect modes, and encounter assumptions. Each of
+the three focus abilities owns three chip positions. Version 1 migration keeps
+the three old chips in `specialization.unassignedChips`; the builder requires
+the user to place them under compatible abilities before it reports a complete
+calculation.
+
+# Versioned combat calculations
+
+`calculation_revisions` supplies one active rule set. Draft revisions can
+change, while active and retired revisions stay immutable.
+`calculation_stages` stores the ordered typed pipeline. The base-damage stage
+holds the first position, and the firing-cycle stage holds the last.
+`attribute_calculation_profiles` maps an Attribute to a stage with its weight,
+optional caps, curve, and weapon-category scope.
+
+The shared combat engine consumes weapon facts, accumulated Attributes,
+calculation profiles, and conditional effects. It produces four hit values,
+burst DPS, reload-aware sustained DPS, encounter DPS, and stack telemetry.
+Encounter mode walks the expected shot timeline from RPM, magazine size,
+reload time, hit rate, firing activity, and encounter duration. Peak mode
+applies maximum stacks, and Off mode excludes the effect.
+
+The engine returns `INSUFFICIENT_DATA` with missing requirement keys when a
+calculation lacks required inputs or an Attribute binding. Callers must render
+that state instead of a partial result. Saved and shared builds load the current
+active revision for each request.
+
+`calculation_calibration_cases` stores a versioned loadout snapshot, observed
+hit values, timing values, optional encounter DPS, and the model prediction.
+Ready cases require the four hit values plus magazine and reload times. The
+assisted suggestion action compares ready observations with their predictions
+and creates a draft revision for an operator to review.
+
+Rule activation requires `calculation.publish` and an explicit confirmation.
+ISAC records draft creation, draft edits, publication, calibration changes, and
+assisted suggestions under the `calculation_configuration` audit category.
+ISAC data export and environment synchronization include calculation rules,
+calibration cases, and Specialization combat-effect tables in dependency order.
+
 # Game-data icon storage
 
 Talents, brand sets, OS Protocols, and Skill Chips reference uploaded artwork