gate-external-routing-server-side

Wraps external routing APIs behind an OSRM-shaped server-side port for advisory travel estimates.

Updated Jul 9, 2026
One-click install
npx skills add https://github.com/shuddl/shuddl-os --skill gate-external-routing-server-side-shuddl
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: gate-external-routing-server-side
Source: https://github.com/shuddl/shuddl-os/tree/main/.claude/skills/gate-external-routing-server-side
Command: npx skills add https://github.com/shuddl/shuddl-os --skill gate-external-routing-server-side-shuddl

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? It prevents external travel-time, ETA, and route-optimization APIs (Mapbox Matrix/Directions/Optimization/Isochrone, OSRM, Valhalla) from leaking into ledger gates, sold transit windows, pricing, or the offline driver path, where nondeterministic vendor estimates would corrupt deterministic freight truth. ## Core Features & Use Cases - OSRM-shaped port with three adapters: a deterministic haversine fallback (offline/test/driver path), a Mapbox Matrix adapter (server-side, coordinates-only), and a self-hosted OSRM/Valhalla adapter that is drop-in interchangeable. - Advisory-only feasibility checks: the isAppointmentReachable helper returns a soft feasibility flag for appointment planning, never a gate decision, and returns UNKNOWN instead of fabricating a block when a lane is unresolvable. - Vendor-lock and ToS guardrails: coordinates-only requests keep party names inside the tenant, Mapbox isochrones are kept off the MapLibre renderer, and optimization output stays a human-approved suggestion. - Use Case: When a dispatcher asks whether a truck can reach a dock before its appointment window, call the Matrix port server-side, render the result as an advisory flag on the board, and keep the committed window from the config-driven transit matrix. ## Quick Start Ask the agent to check whether an in-progress leg can reach a given dock before its appointment window using the travel-matrix port, keeping the result advisory only.

Frequently Asked Questions about gate-external-routing-server-side

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check appointment feasibility with a travel-time API?▼

Call the TravelMatrix port's table method with the in-progress origin and dock coordinates, then compare the returned seconds against the SLA window via isAppointmentReachable. The result is an advisory flag rendered on the board, never a hard capacity gate.

Mapbox vs self-hosted OSRM or Valhalla for routing estimates?▼

Mapbox Matrix works for server-side minutes-only estimates but its display ToS forbids rendering its geometry on non-Mapbox maps. Self-hosted OSRM or Valhalla is drop-in through the same OSRM-shaped interface and is required for isochrones drawn on the MapLibre map.

Can a routing API estimate be used as the quoted transit window?▼

No. The sold transit window comes from the deterministic config-driven transit matrix resolver, which returns UNKNOWN rather than guessing. A live vendor ETA drifts and would make the committed number non-deterministic and non-reproducible.

Can the driver app call a routing API for live ETAs?▼

No. The driver path must complete the full stop cycle in airplane mode, so it uses the deterministic haversine adapter or cached values. Live driving-traffic enrichment is a server-side, online-only feature for the dispatch board.

What happens when a routing API call fails or returns null?▼

The call site degrades to the deterministic adapter on upstream errors, and null lane durations are treated as UNKNOWN rather than fabricated. Feasibility defaults to not blocking, since the hard guarantee is the D1 slot occupancy index, not the estimate.