"OK" doesn't mean it opened — chasing a PDF that never appeared

Last time, the foundation of trust. Today, the shop floor — and another chapter in this series' running theme of things that only look like they worked.

The PDF that wouldn't open

STIL.HUB has a feature I call Browse: walk the Mac's folders from your iPhone and open a file on the Mac's side. Tap a filename in your hand, and it opens on the Mac's screen.

Testing on real hardware, a PDF wouldn't open. However many times I tapped, the Mac's screen stayed still. But the companion's log recorded, every single time:

"Executing open request → ok"

Ok. And yet, not open. The log and the screen were flatly contradicting each other.

What "ok" really meant

The first suspect was my own ok. Looking closer, something ugly turned up. The file-opening code asked the OS "please open this" — and logged ok without ever looking at the outcome of the request. A messenger who never checks for a reply, reporting only "I said it." The ok had never meant "it opened." It only meant "I asked."

So where were the requests disappearing to?

A fourteen-day nap

Digging into the Mac turned up the culprit. The standard app responsible for opening PDFs had been running for fourteen days straight, frozen in a state where it couldn't respond. Its window list held nothing but wreckage — four collapsed windows, 39 pixels tall. The OS was accepting my "please open this," handing it to this napping app, and there the requests vanished into the dark.

Restart the app, and the PDF opened as if nothing had ever been wrong. A nap fourteen days long — that was the immediate culprit.

But the lesson belonged to the "ok"

The culprit was found. What needed fixing, though, wasn't the Mac restart — naps will happen again. What I could fix was my side: the anatomy of that ok.

I switched the file-opening code to the form of the API that returns a result. Opened means opened; failed comes back as failed, with a reason. And instead of letting that failure sink into a log on the Mac, the app now carries it all the way to the iPhone's screen. The person who tapped is looking at the device in their hand; news that doesn't arrive there might as well not exist.

Silent success verifies nothing

The sharpest regret: when I first built this feature, I had recorded it as "verified that files open." What that verification had actually watched was an unconditional ok. In other words, it had verified nothing. A thing that looks like it worked and a thing that is proven to have worked are different things.

Back in the receipt season I wrote about turning every real-device bug into a test. Today's lesson sits one step before that one. When an API offers you a version that returns the result, take it. Every time. Don't build a messenger that never checks for a reply into your machinery. "Ok" is not proof that it opened.

Next time

Next: the time I tried to ask the OS for something and ended up changing the asking itself — how triggering the Mac's dictation from my hand failed, and how it led to "speak on the iPhone, type on the Mac."

STIL.HUB is out on the App Store.