Delta and Ownership Model

ChunkDelta is Chunkis' in-memory and persisted chunk payload. It can carry block changes, block entities, entity payloads, chunk metadata, source format version, dirty state, and an ownership claim.

The important rule: an attached delta is not automatically authoritative. A newly loaded or newly generated chunk can have a delta object without giving Chunkis permission to override vanilla persistence.

Three distinct predicates

Predicate	Meaning	Used for
hasChunkisOwnedState	The delta has an ownership claim.	dirty mirroring and Chunkis save authority
hasReplayPayload	Blocks, block entities, or entities must be replayed.	restore work
hasRestorableChunkisState	Replay payload exists or metadata contains a persistence anchor.	whether a load result is meaningful

A persistence anchor is persisted base-chunk NBT or a full block baseline flag. It lets Chunkis reconstruct a chunk even when the payload itself is sparse.

Why the distinction exists

Sparse changes alone are not enough to reconstruct terrain safely. A delta that says “place this block entity” but has no base chunk and no full snapshot would overwrite an unknown terrain baseline on reload. DeltaPersistenceGuard rejects that shape before it reaches durable storage.

For v11 data, a block payload with source version 11 or newer is treated as an authoritative snapshot baseline: omitted positions mean air. This is safe because v11 changed the block payload from a relative patch into an authoritative compact snapshot.

Runtime tracking

GlobalChunkTracker uses DimensionChunkKey to separate identical chunk coordinates in different dimensions. It stores dirty owned deltas and maintains a bounded unload cache.

When a candidate replacement arrives, the tracker keeps the existing delta when it is authoritative and the replacement is weaker. This prevents clean cache state or a placeholder from displacing the stronger live snapshot.

Save decision and vanilla suppression

Save ownership is decided above the lower vanilla storage hooks. PendingVanillaSaveDecision carries a per-thread (ChunkPos, delta, reason) snapshot so the lower hook can consume exactly the decision that belongs to that save.

The consequence is intentional:

• Chunkis-owned state may suppress the corresponding vanilla write.
• Unowned state does not get suppressed merely because a ChunkDelta object exists.
• A rejected sparse/no-base delta is logged with coordinates, dimension, caller, payload shape, source version, and metadata keys.

Developer rule

When adding a new payload field, decide all four things explicitly: does it establish ownership, does it need replay, does it provide a persistence anchor, and can it be restored without a vanilla base? Do not let an incidental field answer those questions by accident.