A Seek Is a State Machine, Not a Boolean

"Queueing a command is pending, not success; the engine-reported time decides applied, clamped, or failed."

The Seek That Refuses to Be True or False

Ask a naive player "did the seek work?" and it answers true — it sent the command, didn't it? But a real seek has more outcomes than a boolean can hold. It might land right where you asked. It might land at the end because you asked past the duration. It might never confirm because the file stalled. It might outright fail. Squeezing all of that into true/false is how a player ends up claiming success while sitting at the wrong second.

Ashen Reel models a seek as a small state machine: it starts pending, and the engine's reported position moves it to exactly one honest outcome.

applied — the observed position is within tolerance of the target. Real success.
clamped — the target was past the end, so it snapped to the duration. The UI shows both what you asked and what it did.
timeout — the engine never confirmed a position in time. The requested time is kept; the app does not claim an exact open.
failed — the seek errored. Visible, with the reason preserved.

Honest Exactness: One Frame or 80 Milliseconds

What counts as 'landed where you asked'? Not zero milliseconds — that's a fantasy the medium can't honor. Video is made of frames, and the smallest thing that exists on screen is one frame. So the tolerance is defined honestly as the larger of one decoded frame or 80 ms. 'Exact' means 'the correct frame,' not a sub-frame precision no format can represent. Defining success against the grain of the medium is what keeps the claim truthful.

Model outcomes as a named state, not a boolean. The instant a result has more than two meaningful endings, a bool forces you to lie about the ones that don't fit. An enum of honest outcomes lets the UI, the logs, and the tests all speak about the same reality.

The resolution logic is small, and every branch is a real thing that can happen:

Clamp is a success you must still show honestly. When you ask to jump past the end, snapping to the duration is the right behavior — but the UI shows both the requested time and the applied time, so the user understands why the picture isn't where they typed. A silent clamp would look like a bug; a labeled clamp looks like care.

Why the Machine Pays Off

Once seeks have named states, everything downstream gets honest for free. The overlay can say "seeking…" during pending and the real position after. Logs record clamped instead of a mysterious wrong number. Tests assert on applied versus timeout instead of guessing. And the Recall handoff — which lives or dies on landing at the right second — can finally tell the difference between "I'm at the moment you remembered" and "I tried and here's what actually happened."

Code

Seek outcomes as honest states, resolved against the medium·swift

enum SeekResult {
    case pending                       // sent, not yet confirmed
    case applied(observed: Double)     // landed within tolerance of target
    case clamped(to: Double)           // target was past the end -> snapped
    case timeout(target: Double)       // engine never confirmed in time
    case failed(reason: String)
}

/// Compare the engine's OBSERVED position to the target, honestly.
func resolveSeek(target: Double,
                 observed: Double,
                 duration: Double,
                 frameDuration: Double) -> SeekResult {
    let tolerance = max(frameDuration, 0.080)   // one frame OR 80 ms
    if target > duration { return .clamped(to: duration) }
    if abs(observed - target) <= tolerance { return .applied(observed: observed) }
    return .pending   // still off-target: keep observing, or time out elsewhere
}
// Nowhere does this return `true`. 'It worked' is one of five honest states.

Exercise

Find an operation in your code that returns a boolean 'did it work?' but actually has more than two outcomes — a payment (approved / declined / pending / needs-3DS), a save (saved / conflict / offline-queued), a fetch (ok / not-modified / rate-limited / failed). Redesign its return as an enum of named states. Then pick the tolerance question: for anything with a 'close enough' notion, what's the honest threshold, defined against the real grain of the domain?

Hint

Two tells you've outgrown a bool: (1) you find yourself returning true but logging a warning about which kind of true it was; (2) callers have to inspect a second field to know what really happened. Both mean the outcomes want names. And define 'success tolerance' against the medium's real resolution, not an idealized zero.

A Seek Is a State Machine, Not a Boolean

The Seek That Refuses to Be True or False

Honest Exactness: One Frame or 80 Milliseconds

Why the Machine Pays Off

Code

External links

Exercise

Progress

Comments 0