Enum ClusterDurability

Namespace

Typhon.Schema.Definition

Assembly

Typhon.Schema.Definition.dll

Declares how a cluster-eligible archetype's SingleVersion component values reach disk, and therefore how much of them a crash may lose. Set per archetype via [Archetype(ClusterDurability = ...)]; the default is FenceWal, which preserves the pre-existing behaviour.

public enum ClusterDurability : byte

Fields

Checkpoint = 1

No fence WAL records. SingleVersion values reach disk through the checkpoint — the same path cluster STRUCTURE (slot claim, occupancy, entity keys, growth) has always used. A crash loses up to one checkpoint interval of value updates (ResourceOptions.CheckpointIntervalMs, 30 s by default): the entities survive, their values are as of the last checkpoint.

Choose this for high-frequency simulation state that is regenerated by the simulation itself — position, velocity, AI scratch — where thirty seconds of staleness after a crash is cheaper than writing every tick. Do not choose it for state a player would notice losing; use DurabilityDiscipline.Commit or Versioned for that, both of which keep working normally alongside this setting.

Name the window, not the speed: read this as "thirty seconds", not as "fast". The performance gain is a consequence of the weaker guarantee, not the guarantee itself.

FenceWal = 0

Default, and the pre-#568 behaviour. Dirty SingleVersion values are written to the WAL at every tick fence.

⚠️ The ≤1-tick loss window this is meant to provide is nominal, not currently delivered: crash recovery has no ApplySlotToExisting, so it discards these records for any entity that already existed at the last checkpoint — which in a steady-state simulation is effectively all of them. In practice such entities recover at checkpoint granularity, exactly like Checkpoint, while still paying the full WAL cost. Tracked by #569; until it is fixed, the only difference this setting makes for a pre-existing entity is the write amplification.

Remarks

This is a knob on the durability axis (see DurabilityDiscipline and ADR-005), not the storage axis: it changes *when* values become durable, never the cluster layout. It is deliberately per-ARCHETYPE and not per-component, because a cluster page interleaves every component of the archetype — page-granular durability cannot express a per-component policy.

It applies only to SingleVersion values in the cluster. Versioned components are unaffected in every setting: their revision chain is WAL-logged at commit and is authoritative, and the cluster HEAD is a cache rebuilt from it on reopen. Transaction atomicity, lifecycle records (Spawn / Destroy / SetEnabledBits) and DurabilityDiscipline.Commit writes are likewise untouched.

Design: claude/design/Durability/cluster-page-durability.md. Issue #568.