Safety & Transactions API

The Safety and Transactions API handles disk-level line patching, verified byte backups, fail-closed rollbacks, and reversible quarantine.


1. FilePatchEngine

The FilePatchEngine generates and applies surgical line patches to serialized YAML assets without re-serializing whole files.

using ProjectDoctor.Core.Repair;
using ProjectDoctor.Core.Recovery;
using ProjectDoctor.Core.Diff;

// Construct repair pairs (BreakRecord + chosen FixCandidate)
var pairs = new List<(BreakRecord breakRec, FixCandidate candidate)>
{
    (brokenReference, chosenCandidate)
};

// Generate a PatchPlan (calculates exact byte offsets and diffs)
PatchPlan plan = FilePatchEngine.CreatePlan(projectRoot, pairs);

foreach (FilePatch patch in plan.FilePatches)
{
    Console.WriteLine($"Patch for {patch.RelativePath}: {patch.LineReplacements.Count} lines modified.");
}

// Apply the plan within a fail-closed transaction
bool success = FilePatchEngine.ApplyPlan(projectRoot, plan);
if (!success)
{
    Console.WriteLine("Patch failed verification and was automatically rolled back!");
}

2. TransactionEngine

The TransactionEngine manages the creation, journaling, verification, and rollback of atomic operations.

using ProjectDoctor.Core.Safety;

var transactionEngine = new TransactionEngine(projectRoot);

// Begin transaction
TransactionContext context = transactionEngine.BeginTransaction("RepairWeaponReferences");

try
{
    // 1. Stage backup files
    context.BackupFiles(new[] { "Assets/Scenes/Arena.unity", "Assets/Prefabs/Sword.prefab" });

    // 2. Perform file writes
    // ...

    // 3. Verify post-conditions
    bool verified = context.VerifyTargetReferences();
    if (!verified)
    {
        throw new InvalidOperationException("Post-write verification failed.");
    }

    // 4. Commit transaction
    context.Commit();
}
catch (Exception ex)
{
    Console.WriteLine($"Rolling back due to error: {ex.Message}");
    context.Rollback();
}

Rollback via Transaction ID

You can roll back any previously committed transaction from code:

bool rolledBack = transactionEngine.RollbackTransaction("20261025_143022_a1b2c3d4");

3. QuarantineManager

The QuarantineManager provides reversible file isolation outside Assets/.

using ProjectDoctor.Core.Safety;

var quarantine = new QuarantineManager(projectRoot);

// Quarantine unreferenced files
var filesToQuarantine = new[] { "Assets/LegacyProps/Chair.prefab" };
string batchId = quarantine.QuarantineFiles(filesToQuarantine, "CleanupUnreferencedProps");

Console.WriteLine($"Quarantined to batch: {batchId}");

// Restore batch later
bool restored = quarantine.RestoreBatch(batchId);
Console.WriteLine($"Batch restoration status: {restored}");

“No tool can truthfully guarantee ‘zero risk’ or ‘zero data loss’; ImportShield fails closed and tells you the truth instead of pretending otherwise.”


Copyright © 2026 DecNet Games. All rights reserved. ImportShield is a commercial Unity tool.

This site uses Just the Docs, a documentation theme for Jekyll.