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 rolls the archetype back to the last checkpoint (ResourceOptions.CheckpointIntervalMs, 30 s by default): every entity that the checkpoint captured survives with its checkpoint values, and every entity born since it is absent (rule CM-07). Population and values are as of the same instant — a coherent point in time, not a mixture.

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 CommitDiscipline.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 is delivered for an entity that already existed at the last checkpoint: recovery applies these records through RecoveryApplier.ApplySlotToExisting. (Until #569 landed it did not — the payloads were aggregated correctly and then dropped, so such an entity really recovered at checkpoint granularity while paying the full WAL cost. Any doc still saying that is stale.)

⚠️ It is not delivered for an entity SPAWNED inside the window and never written afterwards. A spawn does not set the cluster dirty bit the fence emits from (that bitmap tracks write mutations for change-filtered dispatch), so the fence never carries its values and it recovers with defaults. One subsequent write to it closes the gap. This is D5's documented non-guarantee and it applies to this setting too, not only to Checkpoint — use CommitDiscipline.Commit for a spawn that must be durable immediately (rule CM-06).

Remarks

This is a knob on the durability axis (see CommitDiscipline 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, the Destroy and SetEnabledBits lifecycle records, and CommitDiscipline.Commit writes are likewise untouched.

The one lifecycle record it does affect (rule CM-07). A Checkpoint archetype with no Versioned slot emits NO Spawn record for a spawn made under a non-Commit discipline, so an entity born since the last checkpoint is ABSENT after a crash rather than present-with-default-values. That is what "checkpoint-durable" means, and emitting the record while suppressing the values that fill it delivered something strictly worse. Destroy is never suppressed: the asymmetry is deliberate and load-bearing, because it makes the replay window able only to remove entities, never to create one.

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