❤️ Health System — System Guarantees Matrix

This document defines the explicit behavioural guarantees of the RevFramework Health System.

It mirrors the structure used in other systems (e.g., Currency) and is intentionally strict.

If something is not listed here, it is not guaranteed.

---

1️⃣ Core Health

Aspect	Guarantee
State ownership	Per-GameObject Current and Max values owned by the health host
Units	External HP state is integer-based
Internal math	Internal rule math may use floats before final rounding
Threading	Main-thread usage
Mutation surface	Public APIs only
HP bounds	Always clamped [0..Max]
Death handling	Idempotent
Cross-component atomicity	❌ Not guaranteed

---

2️⃣ Damage Pipeline

Aspect	Guarantee
Guard order	Authority → State Guards (Dead → Invincible → DamageLock)
PRE rule order	Ascending Priority
Rule bypass	Specific rule families may be skipped via RuleBypass
DamageAttempted	Fires once per evaluated attempt (applied or rejected)
Damage evaluation	(RawAmount * Multiplier) + FlatDelta
Shield position	After PRE rules, before HP mutation
Shield bypass	Respects BypassShields
POST observers	Run once for attempts that reach POST evaluation (implementation-dependent for early rejections)
Death trigger	Only after HP ≤ 0
Cross-attempt atomicity	❌ Not guaranteed

---

3️⃣ Heal Pipeline

Aspect	Guarantee
Guard order	Authority → Dead → Amount ≤ 0
PRE heal rules	Ascending Priority
Healing modifiers	Multiplicative (IHealingModifier)
Zero-apply heals	Treated as non-applied (no events guaranteed)
HP mutation	Clamped to Max
Overheal spill	Optional spill into OverhealShield when enabled
POST observers	Run once per successful heal
Lifecycle bypass	Revive / SetCurrent bypass the rule pipeline
Cross-op atomicity	❌ Not guaranteed

---

4️⃣ Shields

Aspect	Guarantee
Execution slot	After PRE damage rules
Mutation	Shields never mutate HP directly; they only modify incoming damage
Full absorb	HP unchanged
Partial absorb	Remainder applied to HP
Preview seam	Accurate preview requires IShieldPreview
Shield selection	Defined by ShieldChain when present; otherwise first enabled shield
ShieldPool absorption	❌ Not a shield

---

5️⃣ Rules

Aspect	Guarantee
PRE rules	May mutate context or cancel
POST rules	Observe finalized outcome
Rule ordering	Deterministic by Priority
Exception safety	Exceptions caught; pipeline continues
Direct HP mutation	❌ Not supported through rule contracts
Cross-rule atomicity	❌ Not guaranteed

---

6️⃣ Authority

Aspect	Guarantee
Opt-in gating	requireAuthority
Denied mutation	Deterministic block
Error surface	AuthorityDenied event + LastAuthorityError
Read-only access	Allowed
Replication	❌ Not provided
Ownership model	❌ Not defined

---

7️⃣ Lifecycle

Aspect	Guarantee
Death pipeline	IBeforeDeathHandler → IHealthDeathHandler → UnityEvents → C# event
Cancellation	Only via IBeforeDeathHandler
Revive	Clears dead state
Revive atomicity	✔ Single health mutation operation
Multi-handler atomicity	❌ Not guaranteed

---

8️⃣ Regeneration

Aspect	Guarantee
Delay after damage	✔
Smooth/tick modes	✔
Ceiling enforcement	✔ (when enabled)
Authority respect	✔
Frame-rate independence	✔ (accumulator-based)
Multi-source coordination	❌ Not guaranteed

---

9️⃣ Invincibility

Aspect	Guarantee
Damage block	✔ While active
Tick ownership	HealthSystem drives Tick
Disable edge	Disabling while active emits end event once
Scaled/unscaled	Supported
Retroactive block	❌ No

---

🔟 Persistence

Aspect	Guarantee
Snapshot type	Absolute state
Restore behaviour	Silent
Event emission	❌ None
Shield persistence	❌ Not automatic
Cross-owner atomicity	❌ Not guaranteed

---

11️⃣ Preview

Aspect	Guarantee
No mutation	✔
No events	✔
No death	✔
Invincibility considered	❌ Ignored
Authority checks	❌ Ignored
Damage lock considered	❌ Ignored
Shield accuracy	Only if IShieldPreview implemented
Deterministic ordering	✔ (structural ordering only)

---

12️⃣ Events

Aspect	Guarantee
Death event	Raised once per death
DamageAttempted	Fires per attempt
HealthChanged	After HP mutation
Event ordering	Deterministic within a single health mutation pipeline
Event emission	Occurs after evaluation; mutation-dependent events fire only on successful state changes
Listener isolation	Exceptions caught
Cross-system ordering	❌ Not guaranteed

---

13️⃣ Public API

Aspect	Guarantee
Stable contracts	✔ (DamageContext, HealContext, etc.)
Internal namespaces	❌ Not supported
Composition safety	✔
Subclass safety	❌ Not supported

---

🚨 Non-Guarantees

The Health system does not guarantee:

• ❌ Multi-operation atomicity across rules + shields + handlers
• ❌ Multiplayer replication
• ❌ Rollback determinism
• ❌ Cross-scene authority safety
• ❌ Cross-owner atomic mutation
• ❌ Network prediction
• ❌ Automatic shield/effect persistence
• ❌ Deterministic RNG unless explicitly seeded
• ❌ Shield stacking behaviour without ShieldChain

---

🎯 Summary

Health guarantees:

• Deterministic ordering
• Explicit extension seams
• Idempotent death handling
• Event isolation
• Clear responsibility boundaries

Health does not attempt to be:

• A netcode framework
• A transaction engine
• A persistence manager
• A prediction system
• A gameplay brain

If it’s not listed above, it is not guaranteed.