# TransitGap input and export contract

TransitGap calculates the timetable margin for explicitly chosen interchanges under supplied inbound-delay scenarios. It returns a CSV, a JSON scenario table, a plain-text report and a reproducibility manifest. It does not estimate actual reliability, choose routes, certify a GTFS feed, find walking routes or promise a connection.

The input is a JSON object with `gtfs`, `service_date`, `connections` and `delays_seconds`. The optional `scope` must equal `scheduled_interchange_scenarios_v1`; when omitted, that scope is declared explicitly in every result and manifest. This preserves the parent-provided example contract.

`gtfs` maps exact filenames to decoded CSV strings. Required files: `stops.txt`, `routes.txt`, `trips.txt`, `stop_times.txt`. Supply `calendar.txt`, `calendar_dates.txt`, or both. These six filenames are the entire supported subset. The engine refuses additional files rather than silently ignore operational restrictions in frequencies, transfers, flexible-service or pathways data. A caller may explicitly prepare a reviewed extract; this is not a full-feed GTFS validator. Ordinary agency, shape and other extra files also require external extraction before use.

Required headers:

- stops: `stop_id,stop_name`
- routes: `route_id`
- trips: `route_id,service_id,trip_id`
- stop_times: `trip_id,arrival_time,departure_time,stop_id,stop_sequence`
- calendar: `service_id,monday,tuesday,wednesday,thursday,friday,saturday,sunday,start_date,end_date`
- calendar_dates: `service_id,date,exception_type`

Additional columns in those tables are metadata except the specifically checked stop hierarchy, boarding/alighting, continuous-stopping, timepoint and flexible-service fields. This limited checker does not validate all GTFS columns. IDs are exact, nonempty, trimmed strings of at most 128 characters, with no control characters. Quoted commas, quotes and newlines in descriptive CSV cells are supported. Duplicate headers, duplicate primary IDs, duplicate numeric stop sequences, invalid row widths and missing required cells are refused. UTF-8 BOM and CRLF are accepted. Each trip must reference an existing route/service and at least two timed stop records, with existing stops. CSV row order need not be sequence order: trips are ordered by numeric `stop_sequence` before checking chronology.

`service_date` is an ISO date (`YYYY-MM-DD`). Calendar table dates use `YYYYMMDD`. The weekday calendar applies within its inclusive date range; date exceptions add/remove service afterward. Conflicting duplicate service/date exceptions are rejected. A requested connection to an inactive trip is an error, never a zero-reliability observation. Other inactive trips may remain in the supplied extract and are counted separately.

A connection contains `from_trip`, `from_stop`, `to_trip`, `to_stop`, and nonnegative integer `walk_seconds`. Optional fields: unique `id`, integer `from_sequence` and `to_sequence`. When a trip visits the same stop repeatedly, specify the exact corresponding sequence. Self-connections and duplicate interchanges are refused. The inbound event must have an earlier stop and the outbound event must have a later stop. Boarding or alighting prohibited by `pickup_type=1` or `drop_off_type=1` is refused at the requested event. Conditional pickup/drop-off, approximate timepoints, station hierarchies and continuous/flexible stopping are outside scope.

Times may extend beyond 24:00, up to 71:59:59. They are seconds on the **same selected service day**. The engine never wraps an earlier outbound departure into the next day. It does not search the preceding/following calendar date or convert timetable seconds into timezone/DST-aware elapsed seconds. Explicit zero dwell is allowed. All arrivals precede/equal departures and each departure precedes/equal the next stop's arrival.

`delays_seconds` contains distinct nonnegative integer assumptions. Each is applied separately to the inbound arrival; the outbound departure remains scheduled. For each connection × delay:

```
ready_seconds = scheduled_inbound_arrival + assumed_inbound_delay + supplied_walk
slack_seconds = scheduled_outbound_departure - ready_seconds
scheduled_feasible = slack_seconds >= 0
```

A zero margin supplies no boarding buffer. Feasible-case counts summarize supplied scenarios, not likelihoods or observed outcomes. Add any desired buffer to the explicitly supplied walking allowance and label it externally.

Bounds: 2,000,000 total CSV characters; 20,000 total data rows; 80 columns/table; 4,096 characters/cell; 200 explicit connections; 100 distinct scenarios; 0–86,400 seconds each for walk and delay. Thus at most 20,000 case rows. The browser wrapper is responsible for its own JSON/ZIP upload and decompression limits before calling this in-memory engine. No filesystem, network, subprocess or third-party package is used by `run`.

`run(data)` returns `summary`, `files` and `warnings`; invalid or unsupported input raises `ValueError`. Files are strings keyed by `connections.csv`, `scenarios.json`, `report.txt`, `manifest.json`. CSV protects formula-looking user IDs with a leading apostrophe; JSON preserves exact IDs. Integer numeric columns are unchanged. No HTML is emitted. The manifest hashes canonical JSON input, exact supplied CSV text and the other three export files. It contains version, scope, assumptions and counted results. It is reproducibility metadata, not a digital signature or source attestation.

`products.transitgap.verify.verify(data, result)` validates the source and then independently reparses CSV, reselects calendars and reconstructs arithmetic. It checks JSON rows, CSV rows, summary, human report and provenance hashes. It does not call `run` or reuse its calculation objects. Input validation and declared constants are shared; this is a secondary calculation verifier, not a fully independent GTFS parser implementation. Invalid export/source raises `ValueError`; success returns its recomputed case count.

Primary specification consulted September 8, 2026: [GTFS Schedule reference](https://gtfs.org/documentation/schedule/reference/), particularly `stop_times.txt`, `calendar.txt`, `calendar_dates.txt` and the service-day definition. Service days can continue beyond midnight; calendar-date exceptions modify normal service selection. This product intentionally implements a narrower subset than that specification.