Cut 6: wire StatSource.PowerSupply and refuse a power request that reads it

docs/stats-and-power-cut.md Cut 6, purely additive per its own map: the enum member, the
resolver's generation-cache and the bus's PowerSupply write already existed (Cuts 2/3/5)
as an identity everywhere. This lands the two things Cut 6 actually adds.

The curve: EquippedItem.PowerSupplyFactor now returns pow(PowerSupply, exponent) instead
of the Cut-3 identity stub, so a stat that declares a PowerSupply term degrades as this
tick's grant falls and reads unchanged at full supply (pow(1, n) == 1 regardless of n).
PowerBus.AllocateTiers now invalidates StatSource.PowerSupply once per draw per tick -- the
missing half of the wiring named in the cut map -- so the resolver actually recomputes when
the grant moves, using the same per-source generation scheme Heat/Durability already use
(unconditional, at most once per tick, never touching a stat that did not declare the
source).

The request-independence rule: a stat that decides a power request may not depend on power
supply, directly or through a modifier chain. Direct dependency is checked statically
(StatValidation.ValidateNoPowerSupplyOnRequest, ItemData.cs) against a fixed registry of
(BehaviorData type, field) pairs -- the one PerformanceStat each IPowerConsumer's own
PowerRequest evaluates as its request, a compile-time fact rather than something authored
per instance -- and runs at catalog load (AetheriaStores.Open), at Upsert, and again at
equip (EquippedItem's constructor) as defense against the two named bypasses that write a
catalog document without going through Upsert. The modifier-chain half is dynamic
(StatModifier.ValidateNoPowerSupplyChain): a modifier's own magnitude stat is walked
through the same magnitude->target edges ValidateNoCycle already builds for the self-cycle
check, and refused at Initialize (equip time) if it is power-tainted and targets a known
request stat, naming both items.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-09-19 03:47:07 +02:00
commit 1c1249e700
5 changed files with 166 additions and 15 deletions

View file

@ -754,6 +754,70 @@ public static class StatValidation
throw new InvalidOperationException($"{ownerName}: {ex.Message}");
}
}
// Cut 6 (docs/stats-and-power-cut.md): "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." IPowerConsumer.PowerRequest(dt)
// never hands the bus a number it invented on the spot -- each implementation evaluates exactly one fixed
// PerformanceStat field on its own BehaviorData (Thruster reads EnergyUsage, EnergyDraw reads EnergyDraw, and
// so on). That field is a compile-time fact about the C# type, not something authored per catalog instance,
// so it is named here once -- the same (type, field) address ResolveStatField already uses for
// StatReference -- rather than adding a second reflection idiom or a per-instance flag. Naming it here (not a
// new interface member on IPowerConsumer) means the check needs no Behavior instance, no EquippedItem and no
// Entity: it can run over the catalog's own Data objects, at load and at Upsert, before anything is ever
// equipped.
public static readonly (Type Type, string Field)[] PowerRequestFields =
{
(typeof(EnergyDrawData), nameof(EnergyDrawData.EnergyDraw)),
(typeof(ThrusterData), nameof(ThrusterData.EnergyUsage)),
(typeof(ConstantWeaponData), nameof(WeaponData.Energy)),
(typeof(InstantWeaponData), nameof(WeaponData.Energy)),
(typeof(SensorData), nameof(SensorData.PingEnergy)),
(typeof(ShieldData), nameof(ShieldData.Capacity)),
(typeof(RadiatorData), nameof(RadiatorData.EnergyUsage)),
(typeof(AetherDriveData), nameof(AetherDriveData.EnergyDraw)),
};
// The direct half of the rule: a request stat's own declared Terms must not name PowerSupply. Runs wherever
// ValidateHeatResponse/ValidateStatModifiers run (AetheriaStores.Open, CultRecordRefs.Upsert) plus once more
// at equip (EquippedItem's constructor, Entity.cs) as defense against the two named bypasses that write a
// catalog document without going through Upsert (CultCache Studio's generic editor, AetherDb's dangling-ref
// apply -- see the comment above ValidateHeatResponse). The modifier-chain half of the rule is dynamic and
// lives in StatModifier.Initialize (StatModifier.cs), because a modifier's target only resolves against a
// concrete entity's actual equipment.
public static void ValidateNoPowerSupplyOnRequest(string ownerName, IEnumerable<BehaviorData> behaviors)
{
foreach (var behavior in behaviors)
foreach (var (type, field) in PowerRequestFields)
{
if (!type.IsInstanceOfType(behavior)) continue;
if (!(type.GetField(field)?.GetValue(behavior) is PerformanceStat stat)) continue;
foreach (var term in stat.Terms)
if (term.Source == StatSource.PowerSupply)
throw new InvalidOperationException(
$"{ownerName}: {behavior.GetType().Name}.{field} is a power request -- its own Terms may not " +
"declare a PowerSupply term, or the request would depend on how much power it receives to " +
"decide how much power it asks for");
}
}
// Whether `stat` is the request stat of some IPowerConsumer behaviour on `data` -- used by StatModifier's
// equip-time chain check to tell "an ordinary modifier target" from "a modifier target that would corrupt a
// power request." Returns the owning behaviour's type name for the error message.
public static bool TryGetPowerRequestBehaviorName(EquippableItemData data, PerformanceStat stat, out string behaviorName)
{
foreach (var behavior in data.Behaviors)
foreach (var (type, field) in PowerRequestFields)
{
if (!type.IsInstanceOfType(behavior)) continue;
if (ReferenceEquals(type.GetField(field)?.GetValue(behavior), stat))
{
behaviorName = type.Name;
return true;
}
}
behaviorName = null;
return false;
}
}
[CultDocument("aetheria.personalityattribute", "1"), Inspectable, MessagePackObject, JsonObject(MemberSerialization.OptIn)]