Never report success for work that did not happen.

The rule, and what it costs

Verification is easy to claim and easy to get subtly wrong. The cheap version hashes the source as it streams past and records that as the destination’s hash. It proves the read was correct. It says nothing at all about what the write did. PIGEON re-reads the bytes at the destination and hashes those, and verification is on by default in every profile that ships.

Four consequences follow, and each one is a place the cheap version quietly breaks:

• Every write and every close is checked. A close is where buffered data is finally handed to the filesystem, so a close is where a full disk surfaces.
• A file that fails verification is not checkpointed, so a resume re-copies it rather than skipping it as already done.
• The manifest is the delivery receipt, so a manifest that could not be written fails the run on its own. Files with no receipt are not a completed transfer.
• A later step succeeding is not proof an earlier one did. Archive extraction does not stop at the first failed member — it records the error and reads the next header — so “the next file’s progress callback fired” is not evidence the previous file landed intact. A destination filling up mid-entry produces exactly that sequence. Archive mode’s incremental checkpointing re-verifies size, and hash where the profile asks for it, against the source file before recording anything.

We know the difference because we got it wrong. Three failures in this product’s own history compiled, linked, passed review and were caught only by running the thing: a signing option that silently signed nothing and exited zero, because the guard the signing code sat behind was never true and unreachable code cannot report an error; a plain copy that reported success over a truncated file; and archive mode on Windows reporting completed having delivered zero files. Six more, in detail.

Every failure says what state your data is in

When a transfer fails at two in the morning, the question that matters is not what went wrong. It is whether the destination can be used, and whether re-running will help or waste an hour. PIGEON answers that explicitly rather than leaving it to be inferred: every failure carries a stable code, a category, what happened, what it means, what to do next, and one of six answers about the destination.

Untouched

Nothing was written. The destination is as it was.

Partially delivered, verified

What landed is hash-verified, and a checkpoint means re-running resumes rather than restarts.

Partially delivered, unverified

A partial result with no checkpoint and no per-file verification behind it. Treat as suspect.

Discarded

Archive mode is all or nothing. Nothing was delivered.

Delivered

Everything landed and verified; the failure is in a step after delivery. Re-running the transfer is not the fix and would re-copy the whole set for nothing.

Unknown

The engine genuinely cannot say — so it says that, rather than guessing.

There are seventy codes today, across five categories: input, environment, policy, data and defect. They are append-only — never renumbered, never reused. Inside an enclave where the tool cannot be updated, a code gets read down a phone and written on a form, so the words may change and the number must not. A test enforces uniqueness, the category ranges, and that the mapping from category to process exit code stays one-to-one.

What is actually built

The full surface, with the qualifications each part travels with, is on the product page. In outline:

Verified against things somebody else wrote

Every protocol is checked against an implementation from outside this project, in both directions where both exist: a real OpenSSH server; real independent TFTP client and server implementations; a real FTPS server with real TLS; and PIGEON’s own HTTPS client driven against PIGEON’s own embedded server rather than either side against a stand-in — a pairing that found two real bugs immediately, both of which look correct when either side is tested alone.

Where a platform feature is the thing under test, the platform is real. NTFS alternate data streams are checked on a real NTFS volume, because creating a file with a colon in its name on an ordinary Linux filesystem produces a file with a colon in its name and a test built on it would pass for entirely the wrong reason. Same-drive detection is checked between two filesystems that genuinely are different. The suite builds and runs on real Windows hardware, not in emulation.

Several Windows-only features carried an explicit “compiles, not proven” status in our own engineering log, in writing, for as long as that was true — and were marked proven only when a real Windows machine settled them. In one case the compatibility layer did not merely fail to prove a feature; it reported the opposite of the truth.

Some of it is what the tool will not do

Move mode and mirror-delete cannot be combined on one profile, and there is no override flag — run that combination twice and the second run deletes the only remaining copy of your data, deterministically, not as an edge case. Mirror-delete only ever removes a path this profile recorded delivering, so a file something else put at the destination is left alone with a notice. On the receive side of a one-way link, where nobody can be asked whether an unrecognised file was meant to go, it is moved into dated quarantine instead of removed. A local state file that will not parse fails closed, because the benign reading is always the one that reopens the hole the record was keeping shut.