I flipped one byte in my own backup

August 9, 2026 · Foldic development notes

This started with a question that kept me up at night. A user's Mac backs up to a Synology over SMB, and the network drops sometimes. While teaching Foldic to survive that gracefully, I asked myself: when a scan decides a photo is already backed up, what does it actually compare? The answer: file names. Only file names.

Names only, on purpose

Foldic's scan computes the file names every photo in an album should have, and compares them against what is in the folder. The names carry each photo's identity, so renames and naming-scheme changes are recognised — but size is never checked, content is never checked, dates are never checked. That is a deliberate trade: checking content means reading the entire drive on every scan, and a photo whose original lives only in iCloud would have to be downloaded before there is anything to compare. Scans would go from seconds to hours.

Foldic's own end is covered. Every file is written into a staging folder first and moved to its real name only when complete — and on a local file system like APFS that move is atomic: the file either appears whole or does not exist at all, with no state in between. So a cancel, a crash, a yanked cable never leaves half a photo pretending to be a whole one.

The trouble is the end we do not control. The guarantee has a premise: the file system does what it says. A NAS can tell you "written" and then lose data that never durably landed when the connection drops — on a network drive, even "the move is atomic" does not fully hold (see the appendix). A drive unplugged without ejecting can keep a file whose name is right and whose tail is zeros. And in every scan after that, those files count as backed up.

The failure that looks like success

The worst failure for a backup tool is not an error message. Errors you can see; errors you deal with. The worst failure looks like success: a green check, "12,430 photos backed up" — and on the day you actually need to restore, one of them opens as half a photo and a grey rectangle.

That day might be years away. Whether the source still exists by then, nobody can promise.

This is what I was afraid of. We believe the sync finished; what we actually have is broken files.

Originals never change, so the expensive step happens once

To prove a backup is good, sooner or later you have to read the bytes and compare them. How expensive that is depends on what you compare them against.

Here we have one built-in advantage: originals in the Photos library are immutable. You can edit, crop, filter — the original stays the file your camera made. So once a file's bytes on disk have been checked against the bytes the library serves, and the hash written down, every later verification only needs to read the disk side. The expensive comparison happens once per file, ever.

The whole feature is designed around that one fact.

Three lines of defense

Record at write time. From the next version on, whenever a sync writes a file, Foldic computes its SHA-256 and size and records them in an index at the root of the backup drive. The index travels with the drive — plug it into another Mac and the evidence comes along. New files are born fully accounted for; you do nothing.

Read it back. A new setting, on by default: after each sync, every file just written is read back from the backup disk and compared against what was sent. This is the check aimed squarely at "the NAS said it was written, and it was not" — it catches the mistake at the only moment it is still free to fix, instead of years later. A mismatched file goes to the Trash and the next scan rewrites it.

Deep Compare. Right-click an album, or run it for all albums from Settings. Files with a recorded hash are verified by reading the disk alone — the library is never touched. Files without one (backups that predate this version) are checked against the bytes the library serves, and the result is recorded — so the expensive pass happens once per file, ever. A photo whose original lives only in iCloud while downloads are off is honestly marked unverifiable. A backup tool has no business being optimistic on your behalf.

Damaged files are named right on the album's row, next to a button: re-back up the damaged files. The bad copy goes to the Trash, a fresh export replaces it, the evidence is renewed. Because the source is immutable, the repair is always lossless.

The afternoon I broke my own backup

With the feature built, I ran an experiment.

I let Foldic sync 331 files to a test drive and ran the first Deep Compare. Those 331 files were "old backups" — no records in the index — so all of them were verified against the library: 331 passed, and the index was written.

Then I picked one 3.3 MB photo and flipped its 1,000,000th byte. The file size did not change by a single byte. The date did not change. The name did not change. To the old Foldic, this photo would have counted as backed up forever.

I ran Deep Compare again. This time the index held 331 records, so the whole pass read only the disk and finished in six seconds — and it named the file:

DAMAGED 15846A2E-…jpg: recorded 3315306B 06723ae2…, disk has 3315306B c87e7a45…

The recorded hash and the on-disk hash matched exactly what I computed in a terminal, out of band. One click on repair, the photo was re-exported, and a third pass reported: 396 files, all verified, zero damaged.

(The experiment also caught one of my own bugs along the way — the index could fail to save under a sandbox path. That is what tests like this are for: they verify the feature, and they verify the person who wrote it.)

A backup's worth is decided on the day you restore

"Sync complete" is a promise. This feature is the audit — and the audit's rules are: verify new files on the spot, re-verify old files on a schedule you choose, and say unverifiable out loud when that is the truth.

A backup's worth was never decided on the day it was written. It is decided on the day you restore. We want every photo you open that day to be whole.

Appendix: where "atomic" ends

To be precise about the boundary. On local file systems (APFS, HFS+), rename is an atomic system call — that is the basis for "never half a photo". SMB has atomic-rename semantics at the protocol level too, but that describes the server's file system. On the actual write path there are write-back caches on both the client and the server: when your Mac hears "written", the data may still be in memory on either end. If the connection dies in that window, the protocol promises nothing about what is on the disk. That is why "read it back" runs at the end of a sync instead of trusting anyone's acknowledgement — the bytes read back are the only evidence that no cache and no protocol vouched for.

(Strictly, even a read-back can be served from the client's cache. Which is why Deep Compare is the final line: it can run at any time, after a reboot, even from a different Mac.)

Foldic is $29.99 once, for Mac and iPhone together.