feat: model specialization combat effects

docs/DESIGN_SYSTEM.md

@@ -196,8 +196,10 @@ The canonical tokens live in `src/app.css` under `:root`.
 | Page background | `--shd-bg` | `#0a0c0d` |
 | Base surface | `--shd-surface` | `#111415` |
 | Raised surface | `--shd-surface-raised` | `#141718` |
+| Modeled-data surface | `--shd-model-surface` | `#0d1213` |
 | Subordinate border | `--shd-border-soft` | `#272c2d` |
 | Primary border | `--shd-border` | `#303536` |
+| Modeled-data border | `--shd-model-border` | `#3b4648` |
 | Interactive boundary | `--shd-border-strong` | `#424849` |
 | Main text | `--shd-text` | `#ecebe5` |
 | Muted text | `--shd-text-muted` | `#858b8d` |
@@ -206,6 +208,7 @@ The canonical tokens live in `src/app.css` under `:root`.
 | Supporting copy floor | `--shd-type-supporting` | `14px` |
 | Ordinary body floor | `--shd-type-body` | `16px` |
 | Adaptive display scale | `--shd-display-scale` | `1` by default; stepped on high-resolution desktops |
+| Monospaced data | `--shd-font-mono` | Cascadia Mono with system monospace fallbacks |
 
 ### High-resolution display scaling
 
@@ -1605,7 +1608,9 @@ Pair the short state label with a complete consequence sentence. Contributors
 must not have to infer this behavior from their role name, data-mode color, or a
 success message shown after saving. Read-only operators do not see a mutation
 statement because their mutation controls are absent. At narrow widths the
-  message becomes its own compact row above the module toolbar.
+message becomes its own compact row above the module toolbar. A toolbar with
+multiple actions must reserve the complete action group width in the inline
+desktop strip so the consequence sentence never runs beneath a button.
 
 ### Public database index
 
@@ -1692,3 +1697,71 @@ components use the shared blue quality treatment and may be combined in any
 positive whole-number quantities for Rank 2. Rank 3 uses the yellow High-end
 Omega treatment and exactly one component. Color is supporting hierarchy;
 quality names and quantities always remain visible.
+
+### Conditional combat modeling
+
+ISAC authors define a combat effect once per Specialization and attach it to
+one or more tree-node ranks. Each rank attachment owns its hit trigger, stack
+duration, stack limit, and Attribute modifiers. Keep the lifecycle rules in a
+compact fact rail: trigger counters reset after a proc, each stack gain refreshes
+the timer, and expiry clears the complete stack. The shared definition provides
+one effect name and description to every attached rank.
+
+Use `--shd-model-surface` and `--shd-model-border` for conditional mechanics,
+calculation revisions, and field calibration. The blue information rail marks
+modeled behavior. Orange remains reserved for selection and activation. Every
+effect card names its trigger, duration, maximum stacks, and value per stack in
+text so the mechanic remains clear without color.
+
+The loadout builder gives each unlocked conditional effect three calculation
+modes:
+
+- `OFF` excludes the effect.
+- `PEAK` applies its configured maximum stacks.
+- `ENCOUNTER` models stack buildup and expiry from weapon RPM, magazine size,
+  reload time, hit rate, firing activity, and encounter duration.
+
+Users may override encounter assumptions on one effect without changing the
+global combat profile. The effect card shows the applied stack state beside the
+mode. On mobile, assumption fields and effect controls stack into full-width
+44-pixel targets.
+
+Combat result panels show normal, critical, headshot, and critical-headshot
+values with burst, sustained, and encounter DPS. Conditional stack telemetry
+lists the mode, average and peak stacks, ending stacks, buildup time, and
+maintained state that produced the result. A result with missing equipment,
+Attribute bindings, rules, or assumptions displays `INSUFFICIENT DATA` and a
+concrete remediation list. The interface withholds combat numbers until it has
+the required inputs.
+
+### Specialization loadout composer
+
+The builder places Specialization focus selection after equipment
+configuration. The focus identity combines Specialization artwork and the
+primary Attribute mark, followed by three ability panels. Each ability panel
+contains three fixed Skill Chip positions. A chip picker shows definitions
+assigned to that ability and excludes definitions assigned elsewhere.
+
+The focus tree groups nodes by row and uses segmented rank controls. Disabled
+ranks remain visible with their lock state. The builder permits a row after the
+user buys every available Rank 1 and Rank 2 in preceding rows and enforces the
+49-point limit. Cost telemetry lists Credits and components beside each rank.
+
+Saved loadouts store focus, node ranks, nine Skill Chips, effect modes, and
+combat assumptions. Version 1 loadouts keep their three legacy chips in an
+unassigned recovery list until the user places them under compatible abilities.
+
+### Calculation revision controls
+
+Combat rules use immutable active and retired revisions. ISAC editors may
+change draft revisions, ordered stages, and Attribute profiles. Activation
+requires `calculation.publish`, an explicit review state, and a confirmation
+that saved builds will recalculate. Successful activation closes the
+confirmation surface and records the revision in the audit history.
+
+Calibration cases pair a loadout snapshot with measured hit and timing values.
+Ready cases require the four hit values, magazine time, and reload time.
+Assisted suggestions create a draft revision for review and leave activation
+to an authorized operator. Use monospaced text for raw loadout and prediction
+snapshots; labels, findings, and errors stay in the standard operational
+typeface.

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