VonixGuardian — Rollback, Restore & Undo

Candidate Line: 3.0.0-m1 Rollback EngineCurrent Dev/Test

Rollbacks in VonixGuardian are transactional, auditable, and reversible. Every operation is recorded in dedicated audit tables, enabling safe undos without data loss.

1. Rollback Execution Pipeline

When an operator issues /vg rollback <filters>, the engine executes the following discrete pipeline:

[Filter Query] ──> [Compute Inverses] ──> [Reverse Chrono Replay] ──> [Batch Audit Record]
      │                     │                       │                         │
      ▼                     ▼                       ▼                         ▼
Match audit rows     block_break -> place     Apply latest edits first   Insert into vg_rollback_batches
from vg_actions      container_in -> out      to prevent entity/physics  and link affected action IDs

1. Query Matching Rows: The filter parser resolves criteria (u:, t:, r:, a:, i:, e:, w:) and reads matching actions from vg_actions.
2. Compute Inverses: Each logged action is paired with its mathematical inverse:
   • block_break -> block_place restoring the exact original BlockState and BlockEntity NBT.
   • block_place -> block_break removing the placed block and resetting tile data.
   • container_in -> container_out removing deposited items.
   • container_out -> container_in replenishing stolen items.
3. Reverse Chronological Replay: Inverses are executed in strict reverse chronological order (newest to oldest). This guarantees that sequential block changes (e.g., placing stone, then carving it into stairs, then breaking it) are restored with physical consistency.
4. Batch Auditing: A new entry is written to vg_rollback_batches storing the operator UUID, start timestamp, filter JSON, and affected count. Every restored row is stamped into vg_rollback_batch_actions.

---

2. Safe Rollback Walkthrough

Step 1: Inspect the Damage

Stand at the scene of the incident and inspect modified blocks:

/vg inspect
# Left click destroyed block to view player name and timestamp

Step 2: Test with a Preview

Always execute a preview first. The #preview flag renders the proposed rollback using temporary client-side glass blocks without mutating server world state:

/vg rollback u:Griefer t:12h r:50 #preview

Step 3: Execute the Rollback

If the preview looks accurate, run the command without #preview:

/vg rollback u:Griefer t:12h r:50

Step 4: Revert if Necessary (/vg undo)

If you miscalculated the radius or targeted the wrong player, instantly revert the operation:

/vg undo

/vg undo inspects your last recorded batch ID from vg_rollback_batches and applies the inverse plan directly to the world.

---

3. Forward Restore (/vg restore)

/vg restore applies changes forward. It is primarily used to:

• Re-apply edits that were rolled back during an over-broad rollback operation.
• Reconstruct structures where actions were previously cleared.

# Re-apply changes previously undone
/vg restore u:Builder t:4h r:30

---

4. Pair-Atomic Inventory Replacement (Schema v8)

In modern modded environments, item transfers often occur as paired swaps (e.g., swapping armor, replacing a tool in a slot, or shifting items between custom container inventories).

VonixGuardian 3.0.0-m1 implements pair-atomic state tracking:

• Swaps persist two linked rows in vg_actions sharing a unique pair_id and the exact inventory_slot.
• During a rollback, the engine attempts to reverse both halves of the pair atomically.
• Durable Repair State (vg_repair_required): If a rollback compensates one half but fails on the second (for example, if a target container was destroyed or an inventory slot was locked by another mod), the engine persists the uncompensated state into vg_repair_required.
• Operators can query this table directly to ensure no phantom item duplications or deletions occurred:

  SELECT action_id, pair_id, reason, ts FROM vg_repair_required;

---

5. Scope & Limitations

Feature	Support State	Operator Guidance
Ender Chest Transactions	❌ Not Supported	Ender-chest transaction replay remains an open gap with CoreProtect v24. Do not rely on /vg rollback for ender chests.
Separate Item/Entity Controls	❌ Not Supported	Both items and entities are processed within action filters; independent item vs entity toggles do not exist in config.
WorldEdit Bounding Boxes	🟡 Partial	r:#worldedit falls back to global radius; use explicit coordinate bounding or manual radius (r:50).
Oversized NBT Handling	✅ Bounded	Oversized tile entity NBT payloads (e.g., complex modded machinery) are safely truncated or stored in blobs without freezing the game thread.