ReferenceDraft
System invariants
Normative boundaries that protect transit identity, artifact integrity, telemetry evidence, and assistant behavior.
These rules describe behavior that other parts of the system may rely on. The rationale belongs in the linked feature pages. If a source and this page disagree, current source and tests require investigation before either is treated as correct.
Transit and planning
| Rule | Source and test |
|---|
| A service is directed. The compiler does not invent a jeepney reverse service by reversing geometry. | planner compiler, planner compiler tests |
| Proximity alone does not establish a transfer. A bus-to-jeepney edge needs an official bus stop and a jeepney node within the current 400-metre bound. | edge compiler, conservative connectivity ADR |
| Origin and destination access are each capped at 1,500 metres. Combined endpoint access is capped at 2,000 metres. | planner contract, selector tests |
| A selected itinerary has at most two ride groups and cannot board the same service again. | selector, selector tests |
| Search candidates and rider-facing selection are separate stages. A graph-valid candidate can still be filtered for access, transfer, ride-sequence, or duplication rules. | trip planner engine |
| A missing fare or live arrival does not make a connected graph edge invalid. The product reports unavailable enrichment separately. | multimodal planner specification |
Planner image and offline path
| Rule | Source and test |
|---|
The planner image begins with WAYPLAN plus a null byte and uses format version 1. | image writer, image tests |
The build publishes a content-addressed .wayplan file and a manifest containing its digest and byte length. | planner image build |
| The page checks the manifest length and SHA-256 before transferring the image. The worker verifies it again before mounting. | image transport, trip worker |
Workbox precaches matching .wayplan assets. The current planner path does not use a planner-specific IndexedDB record. | Vite PWA configuration, offline lifecycle |
| Mounting decodes strings and allocates runtime arrays. Transferable message delivery is not zero-copy planning. | planner mount |
Telemetry and road intelligence
| Rule | Source and test |
|---|
| Raw vehicle observations are inserted before derived processing is attempted. | collector, telemetry pipeline |
| A duplicate raw packet is identified by vehicle and reported time. | collector migration 0001_vehicle_observations.sql |
| A stop candidate uses the current 75-metre radius, speed at or below 5 kph, and at least two samples. | intelligence, intelligence tests |
| Transit dwell is excluded from road-intelligence samples. | road intelligence, road tests |
| Valhalla matching is optional. A matcher failure must not prevent raw observation persistence or the basic transit path. | road matcher, telemetry ADR |
Assistant and security
| Rule | Source and test |
|---|
| The assistant model extracts intent. Deterministic code owns route, stop, fare, transfer, live-data, and service-area facts. | AI intent engine |
| The current assistant schema has eight intent kinds and rejects unknown fields. | shared schema |
| Known action shortcuts use no model call. A normal message path uses one extraction call, then validates and dispatches the result. | orchestrator |
| Invalid model output fails closed as an unknown or unavailable result. | assistant route, assistant tests |
| Dashboard Access JWT validation and HMAC share tokens are separate credentials and checks. | security and authentication, dashboard source |
Maps and static data
| Rule | Source and test |
|---|
| Bus direction and stop order are preserved through catalog, geometry, bundle, tile, and fallback paths. | bus data lifecycle ADR |
| Ordered-stop fallback preserves route topology but is not equivalent to road-following geometry. | static bundles, catalog and map |
| Routing-service output for jeepney inference is candidate evidence. It cannot by itself establish a service direction or transfer. | jeepney inference |