Route Guard

What this chapter covers

Route Guard is Korido's name for corridor monitoring: watching whether a truck on a mission is still on the road it committed to, and raising a deviation when it is not. This chapter describes the mission's frozen acceptance region, the deviation lifecycle with its hysteresis and eight close reasons, and the notifications a deviation raises. It builds on the roads and corridors of the previous two chapters, and it is an engine-side chapter, so its edge cases are load-bearing.

The picture

The two intermediate phases — Watching before a deviation opens, and the requirement of movement to confirm a return — are what keep a single noisy GPS point from ever creating or clearing an incident.

The acceptance region

Every mission has an acceptance region: the area within which the truck is considered on-corridor. It is the union of two things:

• the buffered polygons of the mission's roads — each road segment's centre line thickened by its width; and
• the mission's own waypoint geofences — each waypoint buffered by its operational radius.

Current behavior

The acceptance region is mission-specific and frozen. Later road curation helps future missions, while an active mission keeps the region its deviations were measured against unless the plan is deliberately reassembled.

Unioning the waypoint geofences into the region is what absorbs the ordinary city driving on arrival and departure. Our Douala tanker, inside the port geofence but a few hundred metres past where the buffered road ends, is still inside the region — so manoeuvring in a yard never reads as leaving the corridor.

Frozen at creation

The acceptance region is frozen when the mission is created. It is assembled once, from the roads the corridor resolved to plus the mission's waypoints, and stored as a single multi-polygon on the mission. From then on, an active mission's guard never shifts underneath it. This matters because an open deviation references the region it was measured against; if the region could change mid-flight, an in-progress incident would lose its meaning.

The region is re-assembled in exactly two controlled cases: when the mission's corridor is edited, and when an admin edits a road's geometry and that change is propagated to the in-flight missions using it. Both are deliberate acts on the plan.

A mission with no corridor has no acceptance region. Route Guard skips such a mission entirely rather than inventing a boundary — the fleet engine still tracks its stops and gaps, but no deviation is possible.

The deviation lifecycle

Route Guard is deliberately conservative. It moves through phases, and each phase exists to reject noise.

1. Inside the region. Nothing happens.
2. Outside while stationary. Nothing happens — a parked truck just off the line is not deviating anywhere.
3. Outside while moving. Route Guard starts watching.
4. Watching, back inside. The watch resets. A brief clip of a corner is not an incident.
5. Watching, still outside. Outside evidence accumulates fix by fix.
6. Watching, enough consecutive outside trusted fixes. A deviation opens.
7. Open, still outside. The deviation stays open.
8. Open, inside while moving. The truck has returned to the corridor.
9. Open, inside while stationary. The deviation stays open until movement confirms the return — a truck that drifts back into the region and parks has not demonstrably rejoined the route.

Degraded or jitter-flagged positions never open deviation state; only trusted fixes count. The watching phase itself has a time-to-live, so a stale watch that never resolves does not linger.

An open deviation records the excursion in full: where and how fast the truck left, how far it strayed at the furthest point, how long it lasted broken down into driving and stationary time, how many stops happened off-corridor, and which road segment it strayed from (resolved as the closest segment to the exit point). Every deviation is persisted — even the ones that never reach a person — because they are the raw material for corridor analytics.

The eight close reasons

A deviation closes as either returned or abandoned, and the close reason records why in human terms:

• Returned to corridor — the truck drove back onto the route. The ordinary, healthy ending.
• Mission arrived — the mission reached its destination while the deviation was still open.
• Mission terminated — the mission was completed or cancelled out from under the open deviation.
• Corridor replaced — the mission's corridor was changed, so the old excursion is measured against a region that no longer applies.
• Vehicle reassigned — the truck was moved to a different mission.
• Relocated during signal loss — the truck reappeared somewhere new after a gap in the signal, so route continuity can no longer be trusted and the old deviation cannot be honestly continued.
• False-start recovery — the mission was flagged as a false start and rolled back, taking its open deviation with it.
• Stale safety net — a background sweep closed a deviation that had been left open with no fresh evidence, so nothing lingers forever.

Only one deviation per truck can be open at a time. The close reason is always recorded; a deviation is never silently dropped.

Notifications

Persisting a deviation and notifying a person are two separate decisions. Every deviation row is written for analytics; only the owner-or-dispatcher alert is gated, and it is gated to fight fatigue:

• Historical replays never page. A deviation reconstructed from replayed history persists its row but never notifies a person — it already happened.
• A brief deviation cancels its own alert. A deviation that returns within 60 seconds suppresses its still-queued open-notification, so one noisy excursion never reaches the owner even though the row is kept.
• Per-stop off-corridor alerts are opt-in. A stop that happens while a truck is off-corridor always writes its fact, but the per-stop notification is off by default. In practice nearly every off-corridor stop is unauthorised, so alerting on each one by default would be pure noise; a tenant that wants that visibility turns it on.

Edge cases

• No corridor, no guard. A mission with no acceptance region is skipped by deviation detection; the engine falls back to treating a long ignition-off stop as pause evidence rather than a route judgement.
• A pause freezes an open deviation. When a mission pauses, an open deviation is preserved as-is rather than being closed as returned — a legitimately paused truck sitting off the line is not resolving the excursion, and forcing it closed would lose the story.
• A signal gap relocates the truck. If a gap ends with the truck somewhere it could not have driven continuously, the open deviation's continuity is closed with the "relocated during signal loss" reason, because the path between exit and reappearance is unknown.
• The engine's memory disagrees with the database. The persisted open deviation rows are authoritative. If the engine's in-memory view and the stored rows disagree, persistence self-heals toward what the database holds, so a restarted or re-ordered run never double-opens or loses an incident.
• A road edited mid-mission. Editing an admin-curated road re-unions the acceptance region of the active missions that use it, so a corridor correction reaches trucks already on the road without rebuilding their missions.

Known limitations

• Duration separates driving from stationary, not pause. An open deviation's elapsed time is decomposed into the driving portion and the stationary portion, measured against the truck's trips and stops across the excursion window. A distinct paused component is not broken out today — the driving and stationary figures carry the story, and any slice that belongs to neither sits in the unaccounted remainder rather than its own number.
• The guard reacts only to trusted fixes. Deviation state opens and clears on trusted positions alone; degraded and jitter-flagged fixes are ignored. During a stretch of heavily degraded signal the guard therefore holds its current verdict rather than reacting to noisy points — correct by design, but it means an excursion that begins and ends entirely within a degraded window can go unseen until clean fixes resume.

How it connects

• Waypoints and road geometry — the polygons that make up the acceptance region.
• Corridors — the resolved roads a mission's region is assembled from.
• The mission lifecycle — pause, arrival, false-start, and reassignment, which drive several close reasons.
• Progression and ETA — how a blocked road ahead, separate from a deviation, changes the arrival estimate.
• Part 3 (the fleet engine) for signal gaps and the trusted-position filter, and Part 6 (fleet intelligence) for how deviation alerts reach people.