Aetheria/docs/stats-and-power-target.md

# Stats and Power Target

Date: 2026-09-17

Status: target, design rulings only. No substrate map or cut map yet. This
document owns the ends; a cut map will own the means. Where it lands in the
order relative to `docs/headless-playground-cut.md` (lifecycle, fire control)
is not decided.

## Why

Two current mechanisms need a better shape:

- **Power.** Every draw succeeds and overdraw becomes reactor heat, so players
  cannot prioritize energy use. There is already a hidden priority: behavior
  execution order decides who drains capacitors first.
- **Stats.** `PerformanceStat` is authored catalog data that also stores runtime
  modifier state per entity. Every read recomputes every factor. `StatModifier`
  snapshots its value once and matches targets by exact type name.

## Power (operator direction, 2026-09-17)

- **Priority tiers.** Critical is fed first; each following tier divides what is
  left, so low-priority subsystems starve first. Reactor throttling is a player
  choice.
- **All draw is continuous.** Instant-activation items get an input-only
  capacitor that the bus charges and an activation spends. Operator's words:
  "convert instant activation items into having a sort of input-only capacitor
  that needs to be charged, that way all power draw is continuous". A partial
  grant fills the buffer slower; no item receives a fraction of a shot.
- **Continuous consumers brown out** through a power supply curve on their
  performance stats. An exponent is enough. Operator's words: "I really want
  performance stats on those continuous consumers to have a power supply curve.
  Just an exponent is plenty, but we don't wanna pay that cost for every stat
  evaluation."

## Stats: one stat authority (operator direction, 2026-09-17)

- **A stat declares only the terms it uses.** Operator: "PerformanceStat would
  hold only the modifiers it uses." It also unifies with `StatModifier` "for a
  single stat authority".
- **A term is a source plus an application.**
  - Item-local sources: heat, durability, quality of a named design role, power
    supply, consumable progress.
  - External sources: another item's resolved stat, attached by a modifier.
- **Applications (ruled: "Scale and constant only" for modifiers).** Declared
  terms apply inside the stat's min/max interpolation as exponents. Modifier
  terms apply only as scale or constant after it. An effect on a condition,
  such as cooling, is expressed by changing that condition.
- **One resolver per entity owns every stat value.** It recomputes a stat only
  when one of its terms' sources changes, and behaviors read resolved values.
- **Validation on assignment is the guard.** A stat that decides a power
  request may not depend on power supply, directly or through a modifier chain,
  and no stat may depend on itself. The check runs at catalog load and Studio
  save against what is possible, and when a term attaches at equip time against
  what is on the ship. It fails loudly and names the items and the stat.

## Quality can change: item upgrades (operator direction, 2026-09-17)

- **Quality is not immutable.** Operator: "don't say never on quality, that'd be
  a footgun when we inevitably add the ability to upgrade items at special
  stations".
- **Upgrades target a design role.** Example: improving a laser's range by
  upgrading its focusing array. The affordance exists today: `Lot.Roles` holds
  per-role quality, `Lot.QualityForRole` reads it, and a stat names its role.
  The catalog authors no roles yet.
- **Authoring roles is required, not optional (operator, 2026-09-17).** Until
  designs carry roles, every item is one-dimensional. Operator's words:
  "authoring roles for the catalog is what creates generative depth in the item
  selection for the game, until then every item is literally one-dimensional,
  it's not optional."
  - Agents generate the role data, and the operator reviews it.
  - The data is written through the catalog's own types (AetherDb or a scratch
    console over `Aetheria.Shared`), never through hand-copied schemas.
  - Validation refuses a stat term that names a role its design lacks.
- **Upgrade stations are exploration content.** Finding the station, and perhaps
  a small quest to unlock it, is something to discover in each boss-gated region
  of Terminus.
- **Consequence for provenance.** Lots are immutable, and units of one lot are
  identical (`docs/item-provenance-target.md`, F4). An upgrade therefore produces a
  new lot whose provenance names the original lot, the station and the inputs,
  and the upgraded item points at it. The resolver treats a change of lot as a
  change to that item's quality terms.

## Negentropy items (operator direction, 2026-09-18)

Adrasteian **negent** gear cools below ambient. Untended it is an infinite-DPS exploit:
heat is what limits sustained fire, so a free heat sink removes the limit.

- **It runs on a consumable, and that is the balance.** Operator: "I like the consumable
  option... That would make it expensive to run". The charge is a lot like any other, with a
  maker, a process and a price (`docs/item-provenance-target.md`), so a damage ceiling
  becomes a supply line, priced by the economy rather than by a cap.
- **Embrittlement needs no new mechanic.** Operator: "embrittlement isn't a joke, either,
  running gear that cold already causes rapid wear". `Entity.cs:1386` already derives `Wear`
  from distance off `OptimalTemperature` (`ItemData.cs:409`) and from `deltaTemp`, so negent
  wears gear twice: off-optimum, and by the speed of the swing. Weapons already spend that
  wear as durability damage (`Behaviors.cs:77`, `InstantWeapon.cs:192`,
  `ConstantWeapon.cs:135`). Do not author a negent-specific wear rule.
- **Cooling is a change to a condition, not an effect on a stat.** It lowers temperature and
  every stat that names heat responds on its own, the pilot included. That is the rule this
  document already states for conditions; negent is its sharpest case, not an exception.
- **The pilot stays exposed.** Dying hot is the default failure and the cultural nightmare;
  negent moves a ship toward the other end, where hypothermia is waiting. The safe band
  narrows from both sides and the thing saving the ship is what kills the crew.

- **A weapon is the sharpest case.** An Adrasteian gun whose ammunition is the
  ship's thermal load inverts the whole heat loop: `docs/negent-weapons-concept.md`.