# Staten Island Railway

`sir.json` retains the existing source-located, curved MTA GTFS alignment and 21 current stations. Its original schedule validity expired on October 31, 2026. v.12 reuses its geographic coordinates; its legacy median running times do not establish current schedules or train movement.

`sir-timetable.json` extracts current SIR routes, parent and directional child stops, trips, headsigns, stop times, service calendars and date exceptions from the official [regular subway GTFS](https://rrgtfsfeeds.s3.amazonaws.com/gtfs_subway.zip) and [supplemented GTFS](https://rrgtfsfeeds.s3.amazonaws.com/gtfs_supplemented.zip). Both are linked by the [MTA developer page](https://www.mta.info/developers). The November 3, 2026 extraction is valid November 1, 2026 through May 15, 2027 and records version `20261028-fall-2026-pick-with-long-term-supplements`. The supplement covers most, not all, changes for seven days after retrieval; runtime matching expires it after seven days and can use the valid regular schedule with explicit scheduled labels.

Regenerate the timetable and its provenance with plain Node 24:

```powershell
node tools/host-affinity.mjs --exclude 10,11 -- node pipeline/prepare-sir-timetable.mjs
node tools/host-affinity.mjs --exclude 10,11 -- node tools/sync-viewer-data.mjs --lock
node tools/host-affinity.mjs --exclude 10,11 -- node tools/sync-viewer-data.mjs --check
```

The provenance records source archive URLs, SHA-256 hashes, retrieval timestamps, feed validity, output checksum and geometry verification. Each compatible shape is checked against the retained alignment. Rebuilding the geographic alignment is a separate operation: `python pipeline/prepare-sir.py /path/to/gtfs_subway.zip` requires `pyproj` and uses EPSG:6539 US survey feet converted to metres, minus `[292600,50500]`.

The shared browser feed source reads `/api/sir-feed` approximately every 30 seconds. Its server relay obtains the [official SIR GTFS-Realtime endpoint](https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-si), validates the bounded protobuf and returns unchanged bytes with a 25-second shared cache. Alerts use the separate `/api/sir-alerts` relay and [official subway alert endpoint](https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/camsys%2Fsubway-alerts). HTTP errors, invalid protobuf and unavailable alerts retain an explicit unavailable state.

The v.12 cards, station arrivals, train renderer and explicit follow share one normalized `RailwaySnapshot`. Trip identity retains service date, trip ID and supplied start time. Raw `SI`/`SS` route codes stay intact; an SIR mapping requires a unique active static trip and compatible ordered child-stop calls. Directional child stops map through their actual GTFS parent station. They do not imply passenger-facing track numbers.

The three November 3 verification samples contained station progress and predictions without geographic vehicle coordinates. Positions therefore use a fresh reported station anchor, a defensible station segment, or an explicitly estimated point supported by a previous-departure/next-arrival bracket and departure evidence. An insufficient segment never becomes a fictitious moving train. Unknown assignment, stale or future movement timestamps, expired schedules and ambiguous paths disable follow. No synthetic dwell or median segment duration creates v.12 movement.

Movement holds after 90 seconds without advancing evidence; publication/prediction age over 120 seconds removes active countdowns and pauses follow. After five minutes without usable movement, only last-known context remains. New headers alone do not renew unchanged predictions. Skipped calls, no live data, explicit cancellations and feed outages remain distinct. Terminal boarding uses departure predictions. Scheduled fallback is labeled Scheduled; zero never proves arrival.

`tools/verify-railway-feeds.mjs` records three public source observations 31 seconds apart in the ignored `reports/release-v12/feed-verification.json`. The captured binary `packages/data/test/fixtures/sir-20261103.pb` is verification-only and is outside production caches. The five-car map model represents a train class; its physical location, terrain-following elevation and individual appearance are illustrative rather than measured.

MTA data use follows the [MTA data terms](https://www.mta.info/developers/terms-and-conditions). The UI uses its own illustration without importing licensed MTA map artwork or logos. The [MTA-linked NYCT extensions](https://raw.githubusercontent.com/OneBusAway/onebusaway-gtfs-realtime-api/master/src/main/proto/com/google/transit/realtime/gtfs-realtime-NYCT.proto), [legacy NYCT reference](https://new.mta.info/document/134521), and [GTFS reference](https://gtfs.org/documentation/realtime/reference/) document the source contracts. Current samples test populated fields; they do not promise that every optional field will be available.
