Transit data changes are small edits with a long tail. A changed stop identifier can affect the catalog, bus geometry, the planner image, route tiles, and the map fallback. The safe workflow is staged: inspect the authority, validate the edit, rebuild its consumers, then publish only after the generated outputs agree.

What is authoritative

The curated catalog under packages/transit/data owns the route and stop relationships used by the build. GPS observations are evidence for drift and intelligence. They do not silently rewrite the catalog. Bus road geometry is generated from ordered stops; the map can mark a missing geometry as an approximate ordered-stop fallback.

Before editing, identify the smallest source of truth:

  • route identity, direction, and ordered stops: route catalog and related transit data;
  • road-following bus geometry: generated bus GeoJSON;
  • jeepney geometry: curated bundle inputs and reviewed inference output;
  • places: the OSM-derived places input and its generated bundle;
  • live behavior: collector observations and derived tables, not static bundle files.

The update sequence

  1. Make the smallest source edit and record the route or stop IDs it affects.
  2. Run pnpm --filter @aidrecabrera/transit validate-data.
  3. Rebuild the affected bundle with the matching script: build:bus-bundle, build:jeep-bundle, or build:places-bundle.
  4. Rebuild the planner image when route topology, stops, or geometry changed: pnpm --filter @aidrecabrera/transit build:planner-image.
  5. Rebuild and validate bus route tiles when canonical bus geometry changed: pnpm --filter @aidrecabrera/transit build:bus-route-tiles -- --min-zoom <min> --max-zoom <max> followed by pnpm --filter @aidrecabrera/transit validate:bus-route-tiles.
  6. Run the focused tests, typecheck, and the web build before publishing.

The order matters. A green data validator proves that the source bundle satisfies its schema. It does not prove that the planner image or tile release was regenerated from that bundle.

Drift review

The collector drift report requires an observations file. For example:

text
1pnpm --filter @aidrecabrera/collector drift:report -- --input /path/to/observations.csv

The report compares observed trips with the canonical bus geometry. It can use raw GPS points or an optional Valhalla match, and it reports routes with no observations separately. A route with no observations is not evidence of drift. A route below the report's review threshold is a reason to inspect the overlay, not an automatic catalog edit.

Do and do not

Do change the catalog first, regenerate its consumers, and inspect a map when geometry changes.

Do not edit generated bundles by hand. Do not treat a successful drift report as permission to replace the canonical line without review. Do not publish a new planner image while leaving the route tiles on the previous geometry version.

If a build fails after a valid source edit, keep the source edit isolated and fix the build input or command. A generated file that happens to compile is not a substitute for a reproducible build.