Transaction Engine & Fail-Closed Safety
Modifying serialized Unity YAML files is an operation fraught with risk. A single misplaced colon, truncated byte, or invalid indentation can corrupt a 200MB scene file, rendering it unopenable by Unity.
The Transaction Engine guarantees that no repair, import rollback, or component stripping operation can ever leave your project in a corrupt state.
The Fail-Closed Model
Traditional file utilities operate on a fail-open model: they perform writes sequentially; if an error occurs midway through, whatever was already written remains on disk, leaving a partially corrupted project.
ImportShield operates strictly on a fail-closed model:
- No file is modified until byte backups of all targets are verified on disk.
- If any operation fails, times out, or triggers a verification discrepancy, the engine immediately and automatically rolls back all touched files to their verified originals.
- If an operation cannot be 100% verified, it is treated as a total failure.
Transaction Lifecycle State Machine
Every modification executed by ImportShield passes through a formal finite state machine recorded in <ProjectRoot>/ProjectDoctorData/Transactions/<id>/journal.json:
┌───────────────────────┐
│ Initiated │
└───────────┬───────────┘
│ 1. Create directory & copy byte originals
▼
┌───────────────────────┐
│ Prepared │
└───────────┬───────────┘
│ 2. Apply surgical line patches to disk
▼
┌───────────────────────┐
│ Written │
└───────────┬───────────┘
│ 3. Execute Semantic Verification
┌─────────────┴─────────────┐
(Pass) ▼ ▼ (Fail)
┌─────────────────────────┐ ┌─────────────────────────┐
│ Committed │ │ RolledBack │
└─────────────────────────┘ └─────────────────────────┘
1. Atomic Byte Backups
Prior to touching a single file on disk:
- ImportShield allocates a unique transaction ID (
yyyyMMdd_HHmmss_<guid>). - It creates an isolated directory:
<ProjectRoot>/ProjectDoctorData/Transactions/<id>/orig/ - Target assets and their associated
.metafiles are copied intoorig/. - The copied files are immediately read back and their SHA-256 hashes are verified against the active project files.
- Only when byte parity is confirmed does the journal transition to the
Preparedstate.
2. Line-Level YAML Patching (FilePatchEngine)
When applying repairs, ImportShield does not re-serialize the entire file through a generic YAML generator:
- It targets only the specific lines where broken GUIDs, fileIDs, or properties reside.
- It preserves original file line endings (CRLF on Windows, LF on Unix/macOS).
- It preserves all comments, custom formatting, and non-target lines exactly as they existed.
3. Post-Write Semantic Verification
Immediately after writing patches to disk, ImportShield runs a thorough verification pass:
- Target Reference Resolution: Parses the touched file using
YamlLineScannerto ensure the replaced GUID/fileID matches the intended candidate. - Untouched Line Invariance: Compares all unpatched lines against the original backup to ensure no unintended formatting or data shifts occurred.
- No Secondary Breakages: Confirms that the repair did not trigger new missing references elsewhere in the asset.
If any check fails:
- The engine halts execution immediately.
- The verified files in
orig/are copied back to the project root. - The journal status is recorded as
RolledBack. - A detailed error diagnostic is presented to the user.
4. 1-Click Manual Rollback
Every completed transaction remains preserved in your History tab. Even weeks later, you can select any transaction and click Rollback Transaction:
- Restores original files byte-for-byte.
- Automatically handles any manual edits made in the interim via the Conflicts Folder.
“No tool can truthfully guarantee ‘zero risk’ or ‘zero data loss’; ImportShield fails closed and tells you the truth instead of pretending otherwise.”