Expose per-feed static GTFS hashes before the multi-feed fingerprint replaces staticGtfsHash #1907

Problem

#1846 added staticGtfsHash to /api/v2/metadata.json so Watchdog can tell whether it is validating realtime data against the same static bundle Maglev serves. Watchdog downloads the same feed, takes the SHA-256 of the zip bytes, and compares it with staticGtfsHash. If they differ, it re-downloads. If they still differ after that, it reports that either its feed URL is wrong or the backend is running on outdated data.

The multi-feed spec in #1811 changes what that value means. staticGtfsHash reads import_metadata.file_hash. Under section 6 ("Import pipeline"), step 3, that column becomes a dataset fingerprint: a SHA-256 over the ordered import_feeds rows plus the hash of the stop consolidation file. Section 4.3 also notes that single-feed deployments get a new ETag on upgrade.

Once that lands, Watchdog can no longer use staticGtfsHash:

• Even with one feed, the value won't equal the SHA-256 of the zip, so every Maglev server would look out of sync.
• Watchdog can't compute the fingerprint itself. It doesn't have the feed ids, the source URL or path Maglev used, each feed's default agency, the stop consolidation file, or the exact format the rows are combined in before hashing.
• In a multi-agency region, one combined hash can't tell Watchdog which feed is out of date.

The spec doesn't mention staticGtfsHash, so nothing currently stops its meaning from changing under the same field name.

Proposed solution

Phase C step 3 already plans to list the feeds in /metadata and the health endpoint. Each entry in that list should include the SHA-256 of that feed's zip, so clients can compare per feed:

{
  "staticGtfsFeeds": [
    { "id": "kcm", "source": "https://example.com/kcm.zip", "sha256": "aac8f1d4..." },
    { "id": "st", "source": "https://example.com/st.zip", "sha256": "5b21e09c..." }
  ]
}

The field names are only an example. What matters is that sha256 is the hash of the zip bytes as downloaded, before gtfstidy or any other processing, which is the same value the import already computes for each feed. Watchdog then compares the set of hashes it downloaded with the set Maglev lists, for one feed or many, and can say which feed is out of date.

For staticGtfsHash itself, either:

• keep it as the raw zip SHA-256 when there is exactly one feed, or
• move the fingerprint to a separate field (e.g. staticGtfsFingerprint) and document that it isn't a file hash.

Acceptance criteria

• /api/v2/metadata.json lists every loaded static feed with its id, source, and the SHA-256 of its zip as downloaded.
• With one feed, that feed's sha256 equals sha256sum of the zip at its URL.
• The meaning of staticGtfsHash after multi-feed import is documented in the spec and on the wiki (Document staticGtfsHash and metadata.json on the wiki #1859).
• The spec (Rewrite the multi-feed static GTFS spec #1811) mentions the per-feed hashes in Phase C step 3.

References

• Rewrite the multi-feed static GTFS spec #1811: multi-feed static GTFS spec (docs/multi-agency-static-feeds-spec.md)
• Expose the static GTFS hash in metadata #1846, Expose the static GTFS hash for Watchdog sync #1845: staticGtfsHash in /api/v2/metadata.json
• Document staticGtfsHash and metadata.json on the wiki #1859: wiki docs for staticGtfsHash
• Feat/refresh static on agency mismatch watchdog#193: Watchdog's current agency-based check, which the hash check is meant to extend