The alert is only a hint

The first version of this feature cheated, and it cost me a clean afternoon to learn how. A desktop agent on a customer's own machine was meant to notice bank statements as they landed in an account folder, read them locally, and send up only the results. Instead the data got loaded by hand, once, straight past the agent. It looked fine on the screen. It was not fine. Every suggestion the system then made was built on numbers no agent had ever read off a real statement. The rule that came out of that afternoon is the spine of everything below: a notification that a file arrived is a hint, not a fact, and you design the whole thing so that being wrong about the hint is survivable.

The job sounds small. A customer adds an account in the cockpit, the agent creates a folder for it on the disk, and the customer drops statements into that folder - PDFs, CSVs, spreadsheets. Something has to notice. The obvious something is a timer: wake every few minutes, walk the folders, see what is new. That works, and it is also slow and a little wasteful. It is minutes late on average, and it burns a wake-and-walk even on the overwhelming number of passes where nothing changed at all.

So the better instinct is to let the machine tell you. Every desktop operating system can do this: it will notify a program the moment a file lands in a folder it is watching. On Windows a single call can watch an entire folder tree at once. That is the fast path, and it is the one I want as the primary signal. But a fast path you trust blindly is a trap, and the rest of this piece is about why - and about the humble backstops that turn a clever notification into a system you can actually rely on.