@motionstudies/data 0.1.0-alpha.11 → 0.1.0-alpha.13

package/README.md

@@ -25,6 +25,14 @@ Build release candidates with `npm run build:packages`. Distribution manifests a
 
 Source workspace manifests always stay private. `npm run check:release` builds public candidates, tests their packed consumer and records the tested tarball hashes; `npm run release:dry-run` inspects the publication without writing to npm. The manual main-branch `release.yml` workflow publishes those same tarballs with public access and provenance. See [release instructions](https://github.com/emmettl/motionstudies/blob/main/docs/RELEASING.md) for bootstrap-token and trusted-publisher setup. All four shared packages are MIT-licensed; each distribution includes `LICENSE`.
 
+## Timetable patterns, station calls and observation windows
+
+`@motionstudies/core/domain/network-patterns` provides a transport-neutral repeated-schedule codec. `@motionstudies/web/use-pattern-network-day` lazily decodes current/adjacent chunks after verifying byte length and SHA-256; it exposes retry and drops old-source state when the manifest URL changes. Supply stable options and a stable asset resolver. Format/category options support existing edition wire contracts.
+
+`@motionstudies/core/domain/station-calls` supplies station calls, independent source status, namespaced source combination and upcoming-call filtering. Source IDs, repeated visits and acquired windows survive combination. Consumers supply interchange IDs and passenger restrictions; matching display names do not collapse services.
+
+`@motionstudies/data/observation-windows` compiles bounded acquired records into hashed windows with explicit time semantics, conflict policy and acquisition-gap reporting. It preserves supplied record IDs, values and source references. It uses elapsed UTC seconds, including 23/25-hour study days, and performs no acquisition or inference. See [contracts, limits and parity evidence](../docs/ALLCHANGE-FOUNDATIONS.md).
+
 ## Now and browser location
 
 `useNowClock` from `@motionstudies/web/use-now-clock` follows the wall clock on each animation frame, so returning from a suspended tab catches up immediately. Call `start()` from a Now button, set the consumer's playback rate to 1, and render its `time` while `active`. With `NationalNetworkScene`, pass `isPlaying={false}` while this external clock owns time. Call `stop()` before pausing, seeking or changing speed, and retain the last clock time for ordinary playback. Clear moving vehicle selections on entry to keep the camera still; panning and zooming remain available.
@@ -164,6 +172,28 @@ Rail and other transport consumers can share the same time filtering through `mo
 
 `@motionstudies/data/air-endpoints` provides offline `enrichAirEndpoints` for existing air manifests, chunks and opening snapshots. Supply cached same-date global ADSB.lol heatmaps, an OurAirports CSV and the service date's local UTC offset. It associates only unambiguous low-altitude endpoints near a reference airport; cruise-only traces and uncertain routes stay unknown. Optional `AirEndpoint` origin/destination fields carry airport identity, observed boundary time and `observed-endpoint` evidence. `airportBoardMovements` maps full manifest entries to board rows without confusing playback chunk boundaries with flight endpoints. Input hashes and source/licence attribution are recorded in fixture metadata. These fields describe inferred observations, never flight schedules, gates or live status.
 
+## Vehicle hero cards
+
+`VehicleHeroCard` shows one vehicle's destination, next stop and remaining calling points. Import it from `@motionstudies/web/components/VehicleHeroCard` with `@motionstudies/web/vehicle-hero-card.css`. The **Vehicle heroes** lab compares `uk-bus` (amber onboard display), `uk-rail` (dark rail display), `yellow-bus` (yellow next-stop panel) and `sbb` (blue next-stop panel with a red service badge). These are presentation studies, not official operator components.
+
+```tsx
+<VehicleHeroCard
+  presentation="sbb"
+  vehicle={{ service: 'IC 1', operator: 'SBB CFF FFS', destination: 'Genève-Aéroport' }}
+  stops={[
+    { id: 'bern', name: 'Bern', time: '10:28', platform: '6' },
+    { id: 'fribourg', name: 'Fribourg/Freiburg', time: '10:56' },
+  ]}
+  note="Synthetic journey · Example calls and times."
+  onSelectStop={selectStation}
+  selectedStopId={selectedStationId}
+/>
+```
+
+Consumers supply remaining `stops` in journey order and update them with playback, seeking or observations; the card has no independent clock. The first supplied call is the next stop. Optional `time`, `platform` and `detail` are consumer-formatted; absent values stay absent. `vehicle.destination` is optional and shows an explicit unavailable label when missing. The final supplied stop is never inferred to be the destination: set `isDestination` only when confirmed, especially when data is progressively chunked. Empty calls mean no upcoming stops are available, without asserting that the vehicle has arrived.
+
+The required `note` explains provenance. Optional `status`, `statusTone`, `clockLabel`, localized `labels`, `loading`, `error` and `onRetry` follow the consumer's data; the component never manufactures an on-time status. Loading and errors hide the calling points. Stop selection is controlled through stable call IDs and does not alter playback or clear when a call leaves the list. All supplied calls are shown, with wrapping names and container-based compact layouts. The lab exercises advance/rewind, unknown destinations/times, localization, disruption, recovery and narrow widths. Edition adoption requires its own package upgrade and data adapter.
+
 ## Optional live airport feed
 
 `AirportBoard` from `@motionstudies/web/components/AirportBoard` adds Study/Now controls around an existing `AirportHeroCard` configuration. Pass `studyCard` with the usual card props and `live={{ baseUrl, edition, airport }}` for the shared service. Import `airport-hero-card.css`. `labels` localizes the wrapper's control and availability messages. The lower-level `useAirportFeed` hook and core `domain/live-airport` contract are also public exports.
@@ -193,3 +223,9 @@ The renderer now shares active GPU upload ranges, paused frame reuse, label and
 `useTransitionValue(target, { durationMs, easing, steps })` from `@motionstudies/web/use-transition-value` animates a numeric value, returning `value` and `transitioning`. It reverses from the current frame, cancels on teardown, and settles immediately when reduced motion becomes active. `smoothTransition` is the default easing; `cosineTransition` and stepped progress support existing edition rhythms. Keep custom easing functions stable. Camera actions and lazy layout loading stay in the edition.
 
 Edition chunk scripts can call `runNetworkChunkCli()` from `@motionstudies/data/network-chunk-cli`. It accepts the existing `--input`, `--manifest`, `--opening`, `--chunk-hours`, `--opening-start`, `--opening-end`, and `--focus` arguments. Source acquisition, provenance, output paths and command invocation remain edition-owned.
+
+For timetable-backed vehicle selections, `NetworkVehicleHeroCard` from `@motionstudies/web/components/NetworkVehicleHeroCard` accepts `snapshot`, `train`, playback `time`, a required source `note` and the vehicle card's presentation/state/label options. Import `vehicle-hero-card.css`. It resolves the selected train ID against the current snapshot, retaining destination identity but showing no stale calls when that ID is absent. Calls stay in journey order, use stable journey/call IDs and follow backward seeking. During dwell the heading becomes `atStopLabel` (default “At stop”) and the time is the departure; otherwise it is the upcoming arrival. Times are formatted with `formatServiceTime` by default, without normalizing after midnight or adding delay twice. Use `showTimes={false}` for frequency-modelled journeys, and explain the model in `note`. The core `vehicleCalls` helper is also exported from `@motionstudies/core/domain/vehicle-calls` for custom adapters. Selection callback IDs refer to calls, not station indexes.
+
+### Railway preparation
+
+`@motionstudies/data/rail-wtt`, `rail-journeys`, `rail-public-calls`, `rail-routing` and `rail-geometry` expose typed offline railway preparation. XLSX reading, dated source-column audits, UID/date joins, public-call anchors and connected OSM paths preserve source evidence. Editions supply regional identities, calendar exceptions and clipping policy. Node 24+ and `unzip` are required; no Python runtime is shipped. See `docs/SHARED-RAIL-READERS.md` in the source repository for calendar limits and parity evidence.

package/observation-windows.d.mts

@@ -0,0 +1,38 @@
+export interface ObservationRecord<T> {
+  readonly id: string
+  readonly timeUtc: string
+  readonly receivedAt?: string
+  readonly sourceRecordedAt?: string
+  readonly sourceRefs?: readonly string[]
+  readonly value: T
+}
+export interface ObservationWindowOptions {
+  readonly startUtc: string
+  readonly endUtc: string
+  readonly sourceId: string
+  readonly evidenceKind: string
+  readonly timeBasis: 'capture-schedule' | 'receipt' | 'measurement'
+  readonly windowSeconds?: number
+  readonly cadenceSeconds?: number
+  readonly minimumRecords?: number
+  readonly duplicatePolicy?: 'reject' | 'omit' | 'last'
+  readonly pathPrefix?: string
+  readonly maxRecords?: number
+  readonly maxBytes?: number
+}
+export interface ObservationCoverage {
+  inputCount: number; retainedRecords: number; duplicates: number; conflicts: number; outsideWindow: number;
+  occupiedSlots: number; expectedSlots: number; missingSlots: number[]; longestGapSeconds: number;
+  leadingGapSeconds: number; trailingGapSeconds: number;
+}
+export interface ObservationWindowDescriptor {
+  id: string; windowStart: number; windowEnd: number; path: string; frameCount: number; bytes: number; sha256: string;
+}
+export function jsonArtifact(value: unknown): { json: string; bytes: number; sha256: string }
+export function compileObservationWindows<T>(input: Iterable<ObservationRecord<T>>, options: ObservationWindowOptions): {
+  manifest: { schemaVersion: number; sourceId: string; evidenceKind: string; timeBasis: ObservationWindowOptions['timeBasis'];
+    startUtc: string; endUtc: string; durationSeconds: number; cadenceSeconds: number; duplicatePolicy: string;
+    coverage: ObservationCoverage; chunks: ObservationWindowDescriptor[] };
+  chunks: { descriptor: ObservationWindowDescriptor; artifact: { windowStart: number; windowEnd: number;
+    frames: (ObservationRecord<T> & { time: number })[] }; json: string }[];
+}

package/observation-windows.mjs

@@ -0,0 +1,76 @@
+import { createHash } from 'node:crypto'
+
+function instant(value) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/.test(value) || !Number.isFinite(Date.parse(value)) ||
+    new Date(`${value.slice(0, 10)}T00:00:00Z`).toISOString().slice(0, 10) !== value.slice(0, 10) || Number(value.slice(11, 13)) > 23) throw new Error('An explicit valid observation timestamp with timezone is required')
+  return Date.parse(value)
+}
+function positive(value, name) {
+  if (!Number.isSafeInteger(value) || value < 1) throw new Error(`Invalid ${name}`)
+}
+
+/** Hash the exact JSON bytes that are written and subsequently verified by consumers. */
+export function jsonArtifact(value) {
+  const json = `${JSON.stringify(value)}\n`
+  return { json, bytes: Buffer.byteLength(json), sha256: createHash('sha256').update(json).digest('hex') }
+}
+
+/** Bounded offline compilation. Clock semantics and evidence kind must be named by the caller. */
+export function compileObservationWindows(input, options) {
+  const { startUtc, endUtc, sourceId, evidenceKind, timeBasis, windowSeconds = 7200, cadenceSeconds = 60,
+    minimumRecords = 0, duplicatePolicy = 'reject', pathPrefix = 'observation-chunks',
+    maxRecords = 100000, maxBytes = 256 * 1024 * 1024 } = options
+  const start = instant(startUtc), end = instant(endUtc), durationSeconds = (end - start) / 1000
+  positive(windowSeconds, 'window duration'); positive(cadenceSeconds, 'cadence'); positive(maxRecords, 'record limit'); positive(maxBytes, 'byte limit')
+  if (typeof sourceId !== 'string' || !sourceId || typeof evidenceKind !== 'string' || !evidenceKind || !['capture-schedule', 'receipt', 'measurement'].includes(timeBasis) || end <= start ||
+    !Number.isSafeInteger(minimumRecords) || minimumRecords < 0 || !['reject', 'omit', 'last'].includes(duplicatePolicy) ||
+    typeof pathPrefix !== 'string' || !pathPrefix || pathPrefix.startsWith('/') || pathPrefix.split('/').some(part => part === '..' || !part)) throw new Error('Invalid observation archive options')
+  const records = new Map(), rejected = new Set()
+  let inputCount = 0, inputBytes = 0, duplicates = 0, conflicts = 0, outsideWindow = 0
+  for (const record of input) {
+    if (++inputCount > maxRecords) throw new Error('Observation record limit exceeded')
+    const serialized = JSON.stringify(record)
+    if (serialized === undefined || (inputBytes += Buffer.byteLength(serialized)) > maxBytes) throw new Error('Observation byte limit exceeded')
+    if (!record || typeof record.id !== 'string' || !record.id || record.value === undefined) throw new Error('Observation identity and value required')
+    const timestamp = instant(record.timeUtc)
+    if (record.receivedAt !== undefined) instant(record.receivedAt)
+    if (record.sourceRecordedAt !== undefined) instant(record.sourceRecordedAt)
+    if (timestamp < start || timestamp >= end) { outsideWindow++; continue }
+    if (rejected.has(record.id)) { conflicts++; continue }
+    const prior = records.get(record.id)
+    if (prior) {
+      if (prior.serialized === serialized) { duplicates++; continue }
+      conflicts++
+      if (duplicatePolicy === 'reject') throw new Error(`Conflicting observation identity: ${record.id}`)
+      if (duplicatePolicy === 'omit') { records.delete(record.id); rejected.add(record.id); continue }
+    }
+    records.set(record.id, { record, serialized, timestamp })
+  }
+  const ordered = [...records.values()].sort((a, b) => a.timestamp - b.timestamp || a.record.id.localeCompare(b.record.id))
+  if (ordered.length < minimumRecords) throw new Error(`Observation archive has ${ordered.length} records; ${minimumRecords} required`)
+  const slots = new Set(ordered.map(item => Math.floor((item.timestamp - start) / (cadenceSeconds * 1000))))
+  const expectedSlots = Math.ceil(durationSeconds / cadenceSeconds)
+  const missingSlots = []
+  // A caller-controlled duration/cadence must not allocate an unbounded coverage index.
+  if (expectedSlots > maxRecords) throw new Error('Observation coverage index limit exceeded')
+  for (let slot = 0; slot < expectedSlots; slot++) if (!slots.has(slot)) missingSlots.push(slot)
+  let longestGapSeconds = 0
+  for (let i = 1; i < ordered.length; i++) longestGapSeconds = Math.max(longestGapSeconds, (ordered[i].timestamp - ordered[i - 1].timestamp) / 1000)
+  const coverage = { inputCount, retainedRecords: ordered.length, duplicates, conflicts, outsideWindow,
+    occupiedSlots: slots.size, expectedSlots, missingSlots, longestGapSeconds,
+    leadingGapSeconds: ordered.length ? (ordered[0].timestamp - start) / 1000 : durationSeconds,
+    trailingGapSeconds: ordered.length ? (end - ordered.at(-1).timestamp) / 1000 : durationSeconds }
+  const groups = new Map()
+  for (const { record, timestamp } of ordered) {
+    const index = Math.floor((timestamp - start) / (windowSeconds * 1000))
+    if (!groups.has(index)) groups.set(index, [])
+    groups.get(index).push({ ...record, time: (timestamp - start) / 1000 })
+  }
+  const chunks = [...groups].map(([index, frames]) => {
+    const windowStart = index * windowSeconds, windowEnd = Math.min(durationSeconds, windowStart + windowSeconds)
+    const id = `${windowStart}-${windowEnd}`, artifact = { windowStart, windowEnd, frames }, encoded = jsonArtifact(artifact)
+    return { descriptor: { id, windowStart, windowEnd, path: `${pathPrefix}/${id}.json`, frameCount: frames.length, bytes: encoded.bytes, sha256: encoded.sha256 }, artifact, json: encoded.json }
+  })
+  return { manifest: { schemaVersion: 1, sourceId, evidenceKind, timeBasis, startUtc, endUtc, durationSeconds, cadenceSeconds,
+    duplicatePolicy, coverage, chunks: chunks.map(chunk => chunk.descriptor) }, chunks }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/data",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.13",
   "private": false,
   "type": "module",
   "description": "Offline data preparation primitives for Motion Studies.",
@@ -23,6 +23,10 @@
     "node": ">=24.0.0"
   },
   "exports": {
+    "./observation-windows": {
+      "types": "./observation-windows.d.mts",
+      "import": "./observation-windows.mjs"
+    },
     "./adsb-heatmap": {
       "types": "./adsb-heatmap.d.mts",
       "import": "./adsb-heatmap.mjs"
@@ -50,6 +54,38 @@
     "./network-chunk-cli": {
       "types": "./network-chunk-cli.d.mts",
       "import": "./network-chunk-cli.mjs"
+    },
+    "./source-store": {
+      "types": "./source-store.d.mts",
+      "import": "./source-store.mjs"
+    },
+    "./uk-service-day": {
+      "types": "./uk-service-day.d.mts",
+      "import": "./uk-service-day.mjs"
+    },
+    "./webtris": {
+      "types": "./webtris.d.mts",
+      "import": "./webtris.mjs"
+    },
+    "./rail-wtt": {
+      "types": "./rail-wtt.d.mts",
+      "import": "./rail-wtt.mjs"
+    },
+    "./rail-journeys": {
+      "types": "./rail-journeys.d.mts",
+      "import": "./rail-journeys.mjs"
+    },
+    "./rail-routing": {
+      "types": "./rail-routing.d.mts",
+      "import": "./rail-routing.mjs"
+    },
+    "./rail-public-calls": {
+      "types": "./rail-public-calls.d.mts",
+      "import": "./rail-public-calls.mjs"
+    },
+    "./rail-geometry": {
+      "types": "./rail-geometry.d.mts",
+      "import": "./rail-geometry.mjs"
     }
   },
   "files": [
@@ -63,6 +99,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.11"
+    "@motionstudies/core": "0.1.0-alpha.13",
+    "fast-xml-parser": "5.11.1"
   }
 }

package/rail-geometry.d.mts

@@ -0,0 +1,7 @@
+import type {RailCoordinate, RailOsm} from './rail-routing.mjs'
+export type RailStop = [number, number, string, string, string]
+export interface CorridorGeometry { stops: RailStop[]; paths: RailCoordinate[][]; wayIds?: number[]; pairPaths?: Record<string, RailCoordinate[]>; corridorPaths?: RailCoordinate[][] }
+export interface CorridorJourney { id: string; direction: 'inbound' | 'outbound'; stops: [number, number, number][] }
+export function distance(a: RailCoordinate, b: RailCoordinate): number
+export function railCorridorGeometry(osm: RailOsm, stationCodes: string[]): CorridorGeometry & {wayIds: number[]}
+export function assembleRailCorridor<T extends CorridorJourney, M extends {coverage?: Record<string, unknown>}, B> (input: {journeys: T[]; geometry: CorridorGeometry; metadata: M; bounds: B; excluded?: unknown[]}): {metadata: M & {coverage: {includedJourneys: number; excluded: unknown[]}}; bounds: B; stops: RailStop[]; paths: RailCoordinate[][]; edges: never[]; trains: (T & {start: number; end: number; pathSegments: number[]})[]; corridorPaths: RailCoordinate[][]; fadeKilometres: number}

package/rail-geometry.mjs

@@ -0,0 +1,108 @@
+export const distance = (a, b) => Math.hypot((a[0] - b[0]) * Math.cos((a[1] + b[1]) * Math.PI / 360), a[1] - b[1]) * 111.32
+/** Route on connected OSM rails through each station; never replace gaps with straight lines. */
+export function railCorridorGeometry(osm, stationCodes) {
+  if (!Array.isArray(stationCodes) || stationCodes.length < 2 || new Set(stationCodes).size !== stationCodes.length) throw new Error('Expected distinct corridor station codes')
+  const nodes = new Map(osm.elements.filter(e => e.type === 'node').map(e => [e.id, e]))
+  const graph = new Map()
+  for (const way of osm.elements.filter(e => e.type === 'way' && e.tags?.railway === 'rail' && !['yard', 'siding', 'spur'].includes(e.tags.service))) {
+    for (let i = 1; i < way.nodes.length; i++) {
+      const a = nodes.get(way.nodes[i - 1]), b = nodes.get(way.nodes[i])
+      if (!a || !b) throw new Error(`Missing OSM nodes on ${way.id}`)
+      const weight = distance([a.lon, a.lat], [b.lon, b.lat])
+      for (const [from, to] of [[a.id, b.id], [b.id, a.id]]) {
+        if (!graph.has(from)) graph.set(from, [])
+        graph.get(from).push({ to, weight, way: way.id })
+      }
+    }
+  }
+  const stations = stationCodes.map(code => {
+    const station = [...nodes.values()].find(node => node.tags?.railway === 'station' && node.tags['ref:crs'] === code)
+    if (!station) throw new Error(`Missing OSM station ${code}`)
+    return station
+  })
+  // The largest connected component excludes isolated rails and works-in-progress.
+  const visited = new Set(); let component = []
+  for (const start of graph.keys()) {
+    if (visited.has(start)) continue
+    const found = [], queue = [start]; visited.add(start)
+    for (let i = 0; i < queue.length; i++) {
+      const id = queue[i]; found.push(id)
+      for (const { to } of graph.get(id)) if (!visited.has(to)) { visited.add(to); queue.push(to) }
+    }
+    if (found.length > component.length) component = found
+  }
+  if (!component.length) throw new Error('No connected railway geometry')
+  const anchors = stations.map(station => {
+    const point = [station.lon, station.lat]
+    const id = component.reduce((best, id) => distance(point, [nodes.get(id).lon, nodes.get(id).lat]) < distance(point, [nodes.get(best).lon, nodes.get(best).lat]) ? id : best, component[0])
+    if (distance(point, [nodes.get(id).lon, nodes.get(id).lat]) > 0.25) throw new Error(`Station too far from connected railway: ${station.tags.name}`)
+    return id
+  })
+  const queue = [{ id: anchors[0], weight: 0 }], best = new Map([[anchors[0], 0]]), previous = new Map()
+  const target = anchors.at(-1)
+  while (queue.length) {
+    queue.sort((a, b) => b.weight - a.weight)
+    const current = queue.pop()
+    if (current.weight !== best.get(current.id)) continue
+    if (current.id === target) break
+    for (const edge of graph.get(current.id)) {
+      const weight = current.weight + edge.weight
+      if (weight >= (best.get(edge.to) ?? Infinity)) continue
+      best.set(edge.to, weight); previous.set(edge.to, { id: current.id, way: edge.way }); queue.push({ id: edge.to, weight })
+    }
+  }
+  if (!best.has(target)) throw new Error('Disconnected railway corridor')
+  const ids = [target], wayIds = new Set()
+  while (ids.at(-1) !== anchors[0]) {
+    const edge = previous.get(ids.at(-1)); wayIds.add(edge.way); ids.push(edge.id)
+  }
+  const line = ids.reverse().map(id => [nodes.get(id).lon, nodes.get(id).lat])
+  // Snap every intermediate station to this continuous route, avoiding jumps between parallel tracks.
+  const indexes = stations.map(station => line.reduce((best, point, i) => distance(point, [station.lon, station.lat]) < distance(line[best], [station.lon, station.lat]) ? i : best, 0))
+  const paths = []
+  for (let i = 0; i < indexes.length; i++) {
+    if (distance(line[indexes[i]], [stations[i].lon, stations[i].lat]) > 0.25) throw new Error(`Railway misses ${stationCodes[i]}`)
+    if (!i) continue
+    if (indexes[i] <= indexes[i - 1]) throw new Error(`Railway reverses at ${stationCodes[i]}`)
+    const path = line.slice(indexes[i - 1], indexes[i] + 1)
+    const length = path.slice(1).reduce((sum, point, j) => sum + distance(path[j], point), 0)
+    if (length > Math.max(2, distance(path[0], path.at(-1)) * 1.8)) throw new Error(`Implausible railway detour to ${stationCodes[i]}`)
+    paths.push(path)
+  }
+  return { stops: stations.map((station, i) => [...line[indexes[i]], station.tags.name, '', `crs:${stationCodes[i]}`]), paths, wayIds: [...wayIds].sort((a, b) => a - b) }
+}
+
+
+/** Shared output boundary for operator tables or normalized machine-readable schedules. */
+export function assembleRailCorridor({ journeys, geometry, metadata, bounds, excluded = [] }) {
+  const ids = new Set(), paths = [], pathIndexes = new Map()
+  const trains = journeys.map(train => {
+    if (ids.has(train.id)) throw new Error(`Duplicate rail identity: ${train.id}`)
+    ids.add(train.id)
+    if (train.stops.length < 2 || !['inbound', 'outbound'].includes(train.direction)) throw new Error(`Invalid rail journey: ${train.id}`)
+    for (let i = 0; i < train.stops.length; i++) {
+      const [stop, a, d] = train.stops[i]
+      if (!geometry.stops[stop] || !Number.isFinite(a) || !Number.isFinite(d) || d < a || (i && a < train.stops[i - 1][2])) throw new Error(`Non-monotonic rail journey: ${train.id}`)
+    }
+    return { ...train, start: train.stops[0][1], end: train.stops.at(-1)[2], pathSegments: train.stops.slice(1).map(([to], index) => {
+      const from = train.stops[index][0], key = `${from}:${to}`
+      if (from === to) throw new Error(`Repeated corridor station: ${train.id}`)
+      if (pathIndexes.has(key)) return pathIndexes.get(key)
+      if (geometry.pairPaths) {
+        const path = geometry.pairPaths[key]
+        if (!path || path.length < 2 || JSON.stringify(path[0]) !== JSON.stringify(geometry.stops[from].slice(0, 2)) || JSON.stringify(path.at(-1)) !== JSON.stringify(geometry.stops[to].slice(0, 2))) throw new Error(`Missing or disconnected rail path: ${key}`)
+        const pathIndex = paths.length
+        paths.push(path); pathIndexes.set(key, pathIndex)
+        return pathIndex
+      }
+      const segments = geometry.paths.slice(Math.min(from, to), Math.max(from, to))
+      if (segments.length !== Math.abs(to - from) || segments.some(path => path.length < 2)) throw new Error(`Missing corridor geometry: ${key}`)
+      for (let i = 1; i < segments.length; i++) if (JSON.stringify(segments[i - 1].at(-1)) !== JSON.stringify(segments[i][0])) throw new Error(`Disconnected corridor geometry: ${key}`)
+      const path = segments.flatMap((points, i) => i ? points.slice(1) : points)
+      const pathIndex = paths.length
+      paths.push(from < to ? path : [...path].reverse()); pathIndexes.set(key, pathIndex)
+      return pathIndex
+    }) }
+  }).sort((a, b) => a.start - b.start || a.id.localeCompare(b.id))
+  return { metadata: { ...metadata, coverage: { ...metadata.coverage, includedJourneys: trains.length, excluded } }, bounds, stops: geometry.stops, paths, edges: [], trains, corridorPaths: geometry.corridorPaths ?? geometry.paths, fadeKilometres: 4 }
+}

package/rail-journeys.d.mts

@@ -0,0 +1,14 @@
+import type { WttGrid } from './rail-wtt.mjs'
+export interface RailStation { id?: number; lon: number; lat: number; tags: Record<string, string> }
+export interface RailSource { table: string; sheet?: string; column?: number; days?: string; dates?: string; page?: number; sha256?: string; url?: string }
+export interface RailPoint { code: string; arrival: number; departure: number; passenger: boolean; pickupOnly: boolean; setDownOnly: boolean; block?: number; rows: number[]; source: number; arr?: number; dep?: number; pass?: number; publicSupplement?: RailSource }
+export interface RailJourney { uid: string; tid: string; operator: string; origin: string; destination: string; originDate: string; points: RailPoint[]; sources: RailSource[] }
+export interface RailConflict { id: string; point: RailPoint; previous: RailPoint | null; sources: RailSource[] }
+export interface JoinedRailJourneys { journeys: RailJourney[]; stations: Record<string, RailStation>; sources: RailSource[]; unmapped: Record<string, number>; conflicts: RailConflict[]; columnCounts: Record<string, number> }
+export interface JoinWttOptions { serviceDate: string; stations: Record<string, RailStation>; operators: string[]; resolveLocation: (name: string, operator: string, context?: {header: boolean}) => string | null | undefined; normalizeName: (name: string) => string; includeTrain?: (tid: string) => boolean }
+export function joinWttColumns(tables: {table: string; sha256: string; sheets: WttGrid}[], options: JoinWttOptions): JoinedRailJourneys
+export interface PublicCall { code: string; time: number; kind: 'arrival' | 'departure' }
+export interface PublicCallRecord extends PublicCall { operator: string; anchors: PublicCall[]; table: string; page: number; column: number }
+export interface PublicCallAudit { added: {uid: string; originDate: string; code: string; time: number; table: string; page: number; column: number}[]; unmatched: Pick<PublicCallRecord, 'code' | 'time' | 'table' | 'page' | 'column'>[]; ambiguous: {record: PublicCallRecord; uids: string[]}[]; sourceColumns: number }
+/** Mutates the supplied journeys. Callers must reject ambiguous/unreviewed unmatched records before emitting output. */
+export function supplementPublicCalls(result: Pick<JoinedRailJourneys, 'journeys'>, records: PublicCallRecord[]): PublicCallAudit

package/rail-journeys.mjs

@@ -0,0 +1,118 @@
+import {wttTiming,wttRunsOn,wttTerminal} from './rail-wtt.mjs'
+import {checkedDate} from './uk-service-day.mjs'
+const addDays=(date,days)=>new Date(Date.parse(date+'T12:00:00Z')+days*86400000).toISOString().slice(0,10)
+// Preserve the source reader's nearest-day tie handling (round half to even).
+const roundDay=x=>{const floor=Math.floor(x);return x-floor===.5?(floor%2===0?floor:floor+1):Math.round(x)}
+
+/** Join WTT banks by UID and originating date. Region/operator resolution is supplied by the edition. */
+export function joinWttColumns(tables,{serviceDate,stations,operators,resolveLocation,normalizeName,includeTrain=tid=>/^[129][A-Z][0-9]{2}$/.test(tid)}){
+ checkedDate(serviceDate)
+ if([0,1,6].includes(new Date(serviceDate+'T12:00:00Z').getUTCDay()))throw new Error('Sunday banks are unsupported; joined assembly requires all three adjacent banks (Tuesday to Friday only)')
+ const joined=new Map(),counts={},unmapped={},sources=[]
+ for(const {table,sha256,sheets} of tables){
+  sources.push({table,sha256})
+  for(const [sheet,rows] of Object.entries(sheets)){
+   if(!sheet.startsWith('Mondays to Fridays')&&!sheet.startsWith('Saturdays'))throw new Error(`Unexpected sheet ${sheet}`)
+   const expected=['TID','UID','Operator','Origin','Destination','Timing Load','Dates of Operation','Running Days','Service Code']
+   if(JSON.stringify(rows.slice(0,9).map(r=>r[1]??''))!==JSON.stringify(expected))throw new Error(`Unrecognized WTT headers: ${table}/${sheet}`)
+   const labelled=[];let location='',block=0
+   for(let i=9;i<rows.length;i++){const row=rows[i];if(row[0]){location=row[0];block++}if(['arr','dep','pass'].includes(row[1]))labelled.push([i+1,block,location,row[1],row])}
+   for(let column=2;column<rows[0].length;column++){
+    const cell=i=>rows[i][column]??'',tid=cell(0),uid=cell(1),operator=cell(2)
+    if(!operators.includes(operator)||!includeTrain(tid))continue
+    const [origin,originTime]=wttTerminal(cell(3)),[destination,destinationTime]=wttTerminal(cell(4)),days=cell(7),dateRange=cell(6)
+    const activeDays=[-1,0,1].filter(offset=>{
+     const date=addDays(serviceDate,offset),day=new Date(date+'T12:00:00Z').getUTCDay()
+     return (day===6&&sheet.startsWith('Saturdays')||day>=1&&day<=5&&sheet.startsWith('Mondays to Fridays'))&&wttRunsOn(days,dateRange,date)
+    })
+    if(!activeDays.length)continue
+    if(!uid)throw new Error('Missing UID')
+    const points=[];let previous=-1,day=0,firstTime=null
+    for(const [rowNumber,block,name,kind,row] of labelled){
+     const value=row[column]??'';if(value===''||value==='..')continue
+     let [time,symbols]=wttTiming(value);time+=day*86400
+     if(time<previous-43200){day++;time+=86400}
+     if(time<previous)throw new Error(`Non-monotonic WTT ${table}:${sheet}:${column+1}:${rowNumber}`)
+     previous=time;if(firstTime===null)firstTime=time
+     const code=resolveLocation(name,operator)
+     if(!code){if(symbols.includes('T')||symbols.startsWith('U')||symbols.startsWith('D'))unmapped[name]=(unmapped[name]??0)+1;continue}
+     if(!stations[code])throw new Error(`Unknown resolved station: ${code}`)
+     if(!points.length||points.at(-1).block!==block)points.push({code,block,rows:[],passenger:false,pickupOnly:false,setDownOnly:false})
+     const point=points.at(-1);point[kind]=time;point.rows.push(rowNumber)
+     const activity=symbols.split(' ')[0]
+     point.passenger ||= (activity.includes('T')||['U','D'].includes(activity))&&!activity.includes('N')&&!activity.includes('S')
+     point.pickupOnly ||= activity==='U';point.setDownOnly ||= activity==='D'
+    }
+    if(!points.length)continue
+    const originDay=originTime>firstTime+3600?-1:0
+    for(const offset of activeDays){
+     const originDate=addDays(serviceDate,offset+originDay),key=`${uid}:${originDate}`,source={table,sheet,column:column+1,days,dates:dateRange}
+     if(!joined.has(key))joined.set(key,{uid,tid,operator,origin,destination,originDate,points:[],sources:[]})
+     const entry=joined.get(key)
+     if(entry.origin!==origin||entry.destination!==destination||entry.operator!==operator)throw new Error(`Conflicting active UID ${key}`)
+     entry.sources.push(source)
+     for(const point of points){
+      let arrival=point.arr??point.dep??point.pass,departure=point.dep??point.arr??point.pass
+      const station=stations[point.code],publicTimes=[]
+      for(const [terminalName,terminalTime] of [[origin,originTime],[destination,destinationTime]])if(normalizeName(station.tags.name)===normalizeName(terminalName))publicTimes.push(terminalTime+roundDay((arrival-terminalTime)/86400)*86400)
+      if(publicTimes.length){const closest=publicTimes.reduce((a,b)=>Math.abs(b-arrival)<Math.abs(a-arrival)?b:a);if(Math.abs(closest-arrival)<=300)arrival=departure=closest}
+      entry.points.push({...point,rows:[...point.rows],arrival:arrival+offset*86400,departure:departure+offset*86400,source:entry.sources.length-1})
+     }
+     for(const [headerRow,name,terminalTime] of [[4,origin,originTime],[5,destination,destinationTime]]){
+      const code=resolveLocation(name,operator,{header:true});if(!code)continue
+      const reference=headerRow===4?firstTime:previous,time=terminalTime+roundDay((reference-terminalTime)/86400)*86400+offset*86400
+      if(!entry.points.some(p=>p.code===code&&Math.abs(p.arrival-time)<=300))entry.points.push({code,arrival:time,departure:time,passenger:true,pickupOnly:false,setDownOnly:false,block:-headerRow,rows:[headerRow],source:entry.sources.length-1})
+     }
+     counts[operator]=(counts[operator]??0)+1
+    }
+   }
+  }
+ }
+ const conflicts=[],journeys=[]
+ for(const [id,entry] of joined){
+  const points=[]
+  for(const point of entry.points.sort((a,b)=>a.arrival-b.arrival||a.departure-b.departure)){
+   let matches=points.slice(-8).filter(p=>p.code===point.code&&Math.abs(p.arrival-point.arrival)<=60&&Math.abs(p.departure-point.departure)<=60)
+   if(points.length&&points.at(-1).code===point.code&&point.arrival-points.at(-1).departure<=1200)matches=[points.at(-1)]
+   if(matches.length){const other=matches[0];other.arrival=Math.min(other.arrival,point.arrival);other.departure=Math.max(other.departure,point.departure);other.passenger ||= point.passenger;other.pickupOnly ||= point.pickupOnly;other.setDownOnly ||= point.setDownOnly}
+   else points.push(point)
+  }
+  if(points.length<2||points[0].arrival>=86400||points.at(-1).departure<0)continue
+  points.forEach((point,i)=>{if(point.departure<point.arrival||i&&point.arrival<points[i-1].departure)conflicts.push({id,point,previous:i?points[i-1]:null,sources:entry.sources})})
+  entry.points=points;journeys.push(entry)
+ }
+ return {journeys,stations,sources,unmapped,conflicts,columnCounts:counts}
+}
+
+/** Reconcile supplied public-call records using two surrounding passenger anchors.
+ * Parsing table layouts and accepting known calendar exclusions remain edition policy.
+ */
+export function supplementPublicCalls(result,records){
+ const byOperator=new Map();for(const train of result.journeys){if(!byOperator.has(train.operator))byOperator.set(train.operator,[]);byOperator.get(train.operator).push(train)}
+ const added=[],unmatched=[],ambiguous=[]
+ for(const record of records){
+  const candidates=[]
+  for(const train of byOperator.get(record.operator)??[])for(const day of [-1,0,1]){
+   const time=record.time+day*86400
+   if(time<0||time>=86400||time<train.points[0].arrival||time>train.points.at(-1).departure)continue
+   const matches=[]
+   for(const anchor of record.anchors)for(const point of train.points){
+    if(point.code!==anchor.code||!point.passenger)continue
+    const delta=((point[anchor.kind]-anchor.time+43200)%86400+86400)%86400-43200
+    if(Math.abs(delta)<=60)matches.push([point,Math.abs(delta)])
+   }
+   const before=matches.filter(([p])=>p.departure<=time),after=matches.filter(([p])=>p.arrival>=time)
+   if(before.length&&after.length&&new Set(matches.map(([p])=>p.code)).size>=2)candidates.push({score:matches.reduce((n,[,d])=>n+d,0)/matches.length,train,time,bracket:[Math.max(...before.map(([p])=>p.departure)),Math.min(...after.map(([p])=>p.arrival))]})
+  }
+  if(!candidates.length){const {code,time,table,page,column}=record;unmatched.push({code,time,table,page,column});continue}
+  const best=Math.min(...candidates.map(c=>c.score)),selected=candidates.filter(c=>c.score===best)
+  if(new Set(selected.map(c=>JSON.stringify(c.bracket))).size>1){ambiguous.push({record,uids:selected.map(c=>c.train.uid)});continue}
+  for(const {train,time} of selected){
+   if(train.points.some(p=>p.code===record.code&&Math.abs(p.arrival-time)<=120))continue
+   const source={table:record.table,page:record.page,column:record.column};train.sources.push(source)
+   train.points.push({code:record.code,arrival:time,departure:time,passenger:true,pickupOnly:false,setDownOnly:false,rows:[],source:train.sources.length-1,publicSupplement:source});train.points.sort((a,b)=>a.arrival-b.arrival)
+   added.push({uid:train.uid,originDate:train.originDate,code:record.code,time,...source})
+  }
+ }
+ return {added,unmatched,ambiguous,sourceColumns:records.length}
+}

package/rail-public-calls.d.mts

@@ -0,0 +1,4 @@
+import type {PublicCallRecord} from './rail-journeys.mjs'
+export interface PublicTimetablePage { page: number; rows: [number, [number, number, string][]][]; text: string }
+export function publicTimetablePages(bytes: Uint8Array): PublicTimetablePage[]
+export function publicTimetableColumns(pages: PublicTimetablePage[], options: {table: string; target: string; operator: string; acceptPage: (page: PublicTimetablePage) => boolean; resolveCode: (name: string) => string | null | undefined}): PublicCallRecord[]

package/rail-public-calls.mjs

@@ -0,0 +1,48 @@
+import {parseRailXml, xmlContent, xmlAttribute, xmlText} from './rail-xml.mjs'
+
+const descendants = (nodes, name) => nodes.flatMap(node => Object.entries(node).flatMap(([key, value]) => key === ':@' ? [] : [...(key.split(':').at(-1) === name ? [node] : []), ...(Array.isArray(value) ? descendants(value, name) : [])]))
+
+/** Read pdftotext bbox words. Page/calendar acceptance and station names belong to the caller. */
+export function publicTimetablePages(bytes) {
+  // pdftotext emits a fixed XHTML declaration. It is metadata, never fetched or expanded.
+  const text = Buffer.from(bytes).toString('utf8').replace(/<!DOCTYPE html PUBLIC "-\/\/W3C\/\/DTD XHTML 1\.0 Transitional\/\/EN"\s+"http:\/\/www\.w3\.org\/TR\/xhtml1\/DTD\/xhtml1-transitional\.dtd">/, '')
+  return descendants(parseRailXml(Buffer.from(text)), 'page').map((page, index) => {
+    const rows = []
+    const words = descendants(xmlContent(page), 'word').map(word => ({ y: Number(xmlAttribute(word, 'yMin')), a: Number(xmlAttribute(word, 'xMin')), b: Number(xmlAttribute(word, 'xMax')), text: xmlText(xmlContent(word)) }))
+    if (words.some(w => ![w.y, w.a, w.b].every(Number.isFinite))) throw new Error('Invalid public timetable word bounds')
+    for (const word of words.sort((a, b) => a.y - b.y)) {
+      if (!rows.length || Math.abs(rows.at(-1)[0] - word.y) > .8) rows.push([word.y, []])
+      rows.at(-1)[1].push([word.a, word.b, word.text])
+    }
+    for (const [, words] of rows) words.sort((a, b) => a[0] - b[0] || a[1] - b[1] || (a[2] < b[2] ? -1 : a[2] > b[2] ? 1 : 0))
+    return { page: index + 1, rows, text: rows.flatMap(([, words]) => words.map(w => w[2])).join(' ') }
+  })
+}
+
+export function publicTimetableColumns(pages, {table, target, operator, acceptPage, resolveCode}) {
+  const records = []
+  for (const page of pages) {
+    if (!acceptPage(page)) continue
+    const {rows} = page, starts = rows.flatMap(([, words], i) => words.some(w => w[2] === 'Operator') ? [i] : [])
+    for (let bank = 0; bank < starts.length; bank++) {
+      const start = starts[bank], end = starts[bank + 1] ?? rows.length, header = rows[start][1], word = header.find(w => w[2] === 'Operator')
+      const columns = header.filter(w => w[0] > word[1] && w[2] !== 'Operator').map(w => (w[0] + w[1]) / 2)
+      if (!columns.length) continue
+      const calls = columns.map(() => [])
+      for (const [, words] of rows.slice(start + 1, end)) {
+        const name = words.filter(w => w[1] < columns[0] - 5).map(w => w[2]).join(' '), code = resolveCode(name)
+        if (!code) continue
+        const kind = name.trimEnd().endsWith('a') ? 'arrival' : 'departure'
+        for (const [a, b, word] of words) {
+          const time = /^(\d{2})(\d{2})([a-z]?)$/.exec(word)
+          if (!time || +time[1] > 23 || +time[2] > 59) continue
+          const middle = (a + b) / 2, column = columns.reduce((best, x, i) => Math.abs(x - middle) < Math.abs(columns[best] - middle) ? i : best, 0)
+          if (Math.abs(columns[column] - middle) > 5) continue
+          calls[column].push({code, time: +time[1] * 3600 + +time[2] * 60, kind: time[3] === 'a' ? 'arrival' : kind})
+        }
+      }
+      calls.forEach((values, i) => { for (const call of values) if (call.code === target) records.push({...call, operator, anchors: values.filter(v => v.code !== target), table, page: page.page, column: i + 1}) })
+    }
+  }
+  return records
+}

package/rail-routing.d.mts

@@ -0,0 +1,16 @@
+import type {RailStation, JoinedRailJourneys} from './rail-journeys.mjs'
+export type RailCoordinate = [number, number]
+export interface RailOsmNode { type: 'node'; id: number; lon: number; lat: number; tags?: Record<string, string> }
+export interface RailOsmWay { type: 'way'; id: number; nodes: number[]; tags?: Record<string, string> }
+export interface RailOsm { elements: (RailOsmNode | RailOsmWay | {type: 'relation'; id: number})[] }
+export interface RailRoutingOptions { project: (point: RailCoordinate) => RailCoordinate; measure?: (a: RailCoordinate, b: RailCoordinate) => number; includeWay?: (way: RailOsmWay, nodes: (RailOsmNode | undefined)[]) => boolean; anchorRadius?: (code: string) => number }
+export class RailwayGraph {
+ constructor(osm: RailOsm, stations: Record<string, RailStation>, options: RailRoutingOptions)
+ stationCandidates(code: string): [number, number][]
+ distance(a: RailCoordinate, b: RailCoordinate): number
+ route(a: string, b: string): [RailCoordinate[], number[], number]
+}
+export function railBoundaryDistance(point: RailCoordinate, rings: RailCoordinate[][], project: RailRoutingOptions['project']): number
+export type RailBoundary = {type: 'Polygon'; coordinates: RailCoordinate[][]} | {type: 'MultiPolygon'; coordinates: RailCoordinate[][][]}
+export interface RoutedRailJourneys extends JoinedRailJourneys { geometry: Record<string, {path: RailCoordinate[]; ways: number[]; length: number}>; stationBoundaryDistances: Record<string, number>; geometryFailures: Record<string, string>; excludedGeometry: {uid: string; originDate: string; operator: string; missing: string[]}[] }
+export function routeRailJourneys(result: JoinedRailJourneys, osm: RailOsm, options: RailRoutingOptions & {boundary: RailBoundary; routeMargin?: number; visibleMargin?: number}): RoutedRailJourneys

package/rail-routing.mjs

@@ -0,0 +1,119 @@
+/** Connected OSM routing. Projection and regional track exceptions are explicit caller policy. */
+export class RailwayGraph {
+  constructor(osm, stations, { project, measure, includeWay = way => way.tags?.railway === 'rail', anchorRadius = () => .25 } = {}) {
+    if (typeof project !== 'function') throw new Error('A kilometre projection is required')
+    this.project = project; this.measure = measure; this.stations = stations; this.anchorRadius = anchorRadius
+    this.nodes = new Map(osm.elements.filter(e => e.type === 'node').map(e => [e.id, e]))
+    this.graph = new Map(); this.grid = new Map(); this.candidates = new Map(); this.cache = new Map()
+    for (const way of osm.elements) {
+      if (way.type !== 'way' || ['yard', 'siding', 'spur'].includes(way.tags?.service)) continue
+      const nodes = way.nodes.map(id => this.nodes.get(id))
+      if (!includeWay(way, nodes)) continue
+      if (nodes.some(n => !n)) throw new Error(`Missing OSM nodes on ${way.id}`)
+      for (let i = 1; i < nodes.length; i++) {
+        const a = nodes[i - 1], b = nodes[i], length = this.distance([a.lon, a.lat], [b.lon, b.lat])
+        for (const [from, to] of [[a.id, b.id], [b.id, a.id]]) {
+          if (!this.graph.has(from)) this.graph.set(from, [])
+          this.graph.get(from).push([to, length, way.id])
+        }
+      }
+    }
+    for (const id of this.graph.keys()) {
+      const n = this.nodes.get(id), [x, y] = project([n.lon, n.lat]), key = `${Math.floor(x / .25)}:${Math.floor(y / .25)}`
+      if (!this.grid.has(key)) this.grid.set(key, [])
+      this.grid.get(key).push(id)
+    }
+  }
+  distance(a, b) { if (this.measure) return this.measure(a, b); const x = this.project(a), y = this.project(b); return Math.hypot(x[0] - y[0], x[1] - y[1]) }
+  stationCandidates(code) {
+    if (this.candidates.has(code)) return this.candidates.get(code)
+    const station = this.stations[code]
+    if (!station) throw new Error(`Unknown station ${code}`)
+    const point = [station.lon, station.lat], [x, y] = this.project(point), gx = Math.floor(x / .25), gy = Math.floor(y / .25), found = [], radius = this.anchorRadius(code)
+    if (!(radius > 0 && radius <= .5)) throw new Error('Anchor radius must be within 0–0.5 km')
+    for (let dx = -2; dx <= 2; dx++) for (let dy = -2; dy <= 2; dy++) for (const id of this.grid.get(`${gx + dx}:${gy + dy}`) ?? []) {
+      const n = this.nodes.get(id), length = this.distance(point, [n.lon, n.lat])
+      if (length <= radius) found.push([id, length])
+    }
+    found.sort((a, b) => a[1] - b[1]); this.candidates.set(code, found.slice(0, 100)); return this.candidates.get(code)
+  }
+  route(a, b) {
+    const key = `${a}:${b}`, reverse = this.cache.get(`${b}:${a}`)
+    if (this.cache.has(key)) return this.cache.get(key)
+    if (reverse) return [[...reverse[0]].reverse(), reverse[1], reverse[2]]
+    const na = this.stations[a], nb = this.stations[b]
+    if (!na || !nb) throw new Error(`Unknown route station ${!na ? a : b}`)
+    const pa = [na.lon, na.lat], pb = [nb.lon, nb.lat], starts = this.stationCandidates(a), targets = new Map(this.stationCandidates(b))
+    if (!starts.length || !targets.size) throw new Error(`Station lacks a connected railway anchor: ${!starts.length ? a : b}`)
+    const queue = new MinHeap(), best = new Map(), previous = new Map()
+    const heuristic = id => { const n = this.nodes.get(id); return this.distance([n.lon, n.lat], pb) }
+    for (const [id, length] of starts) { best.set(id, length); queue.push([length + heuristic(id), length, id]) }
+    let finish, total = Infinity
+    while (queue.length) {
+      const [estimate, cost, id] = queue.pop()
+      if (estimate >= total) break
+      if (cost !== best.get(id)) continue
+      if (targets.has(id) && cost + targets.get(id) < total) { finish = id; total = cost + targets.get(id) }
+      for (const [target, length, way] of this.graph.get(id)) {
+        const candidate = cost + length
+        if (candidate >= (best.get(target) ?? Infinity)) continue
+        best.set(target, candidate); previous.set(target, [id, way]); queue.push([candidate + heuristic(target), candidate, target])
+      }
+    }
+    if (finish === undefined) throw new Error(`Disconnected rail path ${a}–${b}`)
+    const nodes = [finish], ways = new Set()
+    while (previous.has(nodes.at(-1))) { const [id, way] = previous.get(nodes.at(-1)); nodes.push(id); ways.add(way) }
+    const path = [pa, ...nodes.reverse().map(id => { const n = this.nodes.get(id); return [n.lon, n.lat] }), pb].filter((p, i, all) => !i || p[0] !== all[i - 1][0] || p[1] !== all[i - 1][1])
+    if (total > Math.max(3, this.distance(pa, pb) * 2.6)) throw new Error(`Rail detour ${a}–${b}: ${total.toFixed(2)} km vs ${this.distance(pa, pb).toFixed(2)} km direct`)
+    const result = [path, [...ways].sort((a, b) => a - b), total]; this.cache.set(key, result); return result
+  }
+}
+
+// Numeric lexicographic ordering preserves deterministic A* ties.
+class MinHeap {
+  items = []
+  get length() { return this.items.length }
+  less(a, b) { return (a[0] - b[0] || a[1] - b[1] || a[2] - b[2]) < 0 }
+  push(value) { const a = this.items; let i = a.length; a.push(value); while (i) { const p = (i - 1) >> 1; if (!this.less(value, a[p])) break; a[i] = a[p]; i = p } a[i] = value }
+  pop() { const a = this.items, value = a[0], last = a.pop(); if (a.length) { let i = 0; while (i * 2 + 1 < a.length) { let c = i * 2 + 1; if (c + 1 < a.length && this.less(a[c + 1], a[c])) c++; if (!this.less(a[c], last)) break; a[i] = a[c]; i = c } a[i] = last } return value }
+}
+
+export function railBoundaryDistance(point, rings, project) {
+  let inside = false, nearest = Infinity
+  const [px, py] = project(point)
+  for (const ring of rings) for (let i = 0; i < ring.length; i++) {
+    const a = ring[i], b = ring[(i + 1) % ring.length]
+    if ((a[1] > point[1]) !== (b[1] > point[1]) && point[0] < (b[0] - a[0]) * (point[1] - a[1]) / (b[1] - a[1]) + a[0]) inside = !inside
+    const [ax, ay] = project(a), [bx, by] = project(b), dx = bx - ax, dy = by - ay, length = dx * dx + dy * dy
+    const t = length ? Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / length)) : 0
+    nearest = Math.min(nearest, Math.hypot(px - ax - t * dx, py - ay - t * dy))
+  }
+  if (!Number.isFinite(nearest)) throw new Error('Empty railway study boundary')
+  return inside ? -nearest : nearest
+}
+
+export function routeRailJourneys(result, osm, { boundary, routeMargin = 5, visibleMargin = 4, ...options }) {
+  if (result.conflicts.length) throw new Error('Resolve timetable conflicts before compiling geometry')
+  if (!['Polygon', 'MultiPolygon'].includes(boundary.type)) throw new Error('Expected polygon boundary')
+  if (!(routeMargin >= visibleMargin && visibleMargin >= 0)) throw new Error('Invalid railway boundary margins')
+  const rings = boundary.type === 'Polygon' ? boundary.coordinates : boundary.coordinates.flat()
+  const graph = new RailwayGraph(osm, result.stations, options)
+  const distances = Object.fromEntries(Object.entries(result.stations).map(([code, n]) => [code, railBoundaryDistance([n.lon, n.lat], rings, options.project)]))
+  const pairs = new Map()
+  for (const train of result.journeys) for (let i = 1; i < train.points.length; i++) { const a = train.points[i - 1].code, b = train.points[i].code; if (a !== b) pairs.set(`${a}:${b}`, [a, b]) }
+  const failed = {}, geometry = {}
+  for (const [key, [a, b]] of [...pairs].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+    if (distances[a] > routeMargin && distances[b] > routeMargin) continue
+    try { const [path, ways, length] = graph.route(a, b); geometry[key] = { path, ways, length } } catch (error) { failed[key] = error.message }
+  }
+  const included = [], excluded = []
+  for (const train of result.journeys) {
+    const visible = train.points.flatMap((p, i) => distances[p.code] <= visibleMargin ? [i] : [])
+    if (!visible.length) continue
+    const points = train.points.slice(Math.max(0, visible[0] - 1), visible.at(-1) + 2)
+    const missing = points.slice(1).map((p, i) => `${points[i].code}:${p.code}`).filter(key => !geometry[key])
+    if (missing.length) excluded.push({ uid: train.uid, originDate: train.originDate, operator: train.operator, missing })
+    else included.push({ ...train, points })
+  }
+  return { ...result, journeys: included, geometry, stationBoundaryDistances: distances, geometryFailures: failed, excludedGeometry: excluded }
+}

package/rail-wtt.d.mts

@@ -0,0 +1,12 @@
+export type WttGrid = Record<string, string[][]>
+export interface WttEvent { location: string; kind: 'arr' | 'dep' | 'pass'; sourceTime: string; wallSecondsFromBankMidnight: number; symbols: string; row: number }
+export interface WttIdentity { table: string; sheet: string; column: number; uid: string }
+export interface WttColumn extends WttIdentity { tid: string; operator: string; origin: string; destination: string; datesOfOperation: string; runningDays: string; serviceCode: string; events: WttEvent[] }
+export interface WttRejection extends WttIdentity { reason: string }
+export function listRailArchive(archive: string): Promise<string[]>
+export function readRailArchiveEntry(archive: string, member: string, maxBytes?: number): Promise<Uint8Array>
+export function readWtt(input: string | Uint8Array, options?: { weekends?: boolean; maxWorkbookBytes?: number; maxExpandedBytes?: number; maxCells?: number }): Promise<WttGrid>
+export function wttTiming(value: string): [number, string]
+export function wttRunsOn(code: string, dateRange: string, date: string): boolean
+export function wttTerminal(value: string): [string, number]
+export function auditWttGrid(sheets: WttGrid, table: string, serviceDate: string, options?: { includeColumn?: (column: WttColumn) => boolean }): { columns: WttColumn[]; rejected: WttRejection[] }

package/rail-wtt.mjs

@@ -0,0 +1,135 @@
+import {execFile} from 'node:child_process'
+import {promisify} from 'node:util'
+import {mkdtemp,writeFile,rm,stat} from 'node:fs/promises'
+import {tmpdir} from 'node:os'
+import {join,posix} from 'node:path'
+import {parseRailXml,xmlChildren,xmlContent,xmlText,xmlAttribute} from './rail-xml.mjs'
+import {checkedDate} from './uk-service-day.mjs'
+const execute=promisify(execFile)
+const spreadsheetNamespace='http://schemas.openxmlformats.org/spreadsheetml/2006/main'
+function rootContent(nodes,name,namespace=spreadsheetNamespace){
+ const roots=xmlChildren(nodes,name)
+ if(roots.length!==1)throw new Error(`Missing or ambiguous workbook root: ${name}`)
+ const node=roots[0],key=Object.keys(node).find(k=>k!==':@'),prefix=key.includes(':')?key.split(':')[0]:null
+ if(node[':@']?.[prefix?'@_xmlns:'+prefix:'@_xmlns']!==namespace)throw new Error(`Unsupported workbook namespace: ${name}`)
+ return xmlContent(node)
+}
+
+export async function listRailArchive(archive){
+ const {stdout}=await execute('unzip',['-Z1',archive],{maxBuffer:8*1024*1024,timeout:30000})
+ const entries=stdout.split('\n').filter(Boolean)
+ if(new Set(entries).size!==entries.length)throw new Error('Duplicate archive member names')
+ return entries
+}
+export async function readRailArchiveEntry(archive,member,maxBytes=32*1024*1024){
+ if(!member||/[?*[\r\n]/.test(member)||!Number.isSafeInteger(maxBytes)||maxBytes<1)throw new Error('Invalid archive member or byte limit')
+ const {stdout}=await execute('unzip',['-p',archive,member],{encoding:'buffer',maxBuffer:maxBytes,timeout:30000})
+ return stdout
+}
+/** XLSX source cells only: formula results are retained; formulas are never evaluated. */
+export async function readWtt(input,{weekends=false,maxWorkbookBytes=32*1024*1024,maxExpandedBytes=128*1024*1024,maxCells=8_000_000}={}){
+ for(const value of [maxWorkbookBytes,maxExpandedBytes,maxCells])if(!Number.isSafeInteger(value)||value<1)throw new Error('Invalid workbook resource limit')
+ let archive=input,temporary
+ if(typeof input!=='string'){
+  if(!(input instanceof Uint8Array)||input.length>maxWorkbookBytes)throw new Error('Workbook exceeds limit')
+  temporary=await mkdtemp(join(tmpdir(),'motion-wtt-'));archive=join(temporary,'workbook.xlsx');await writeFile(archive,input,{mode:0o600})
+ }
+ try{
+  if((await stat(archive)).size>maxWorkbookBytes)throw new Error('Workbook exceeds limit')
+  const entries=new Set(await listRailArchive(archive));let expanded=0,allocated=0
+  const read=async name=>{
+   if(!entries.has(name))throw new Error(`Missing workbook member: ${name}`)
+   const bytes=await readRailArchiveEntry(archive,name,maxExpandedBytes-expanded)
+   expanded+=bytes.length;return parseRailXml(bytes)
+  }
+  const strings=entries.has('xl/sharedStrings.xml')?xmlChildren(rootContent(await read('xl/sharedStrings.xml'),'sst'),'si').map(n=>xmlText(xmlContent(n))):[]
+  const links=xmlChildren(rootContent(await read('xl/_rels/workbook.xml.rels'),'Relationships','http://schemas.openxmlformats.org/package/2006/relationships'),'Relationship')
+  const targets=new Map()
+  for(const link of links){const id=xmlAttribute(link,'Id');if(targets.has(id))throw new Error('Duplicate workbook relationship');targets.set(id,link)}
+  const book=rootContent(await read('xl/workbook.xml'),'workbook'),sheetsNode=xmlChildren(book,'sheets')[0]
+  const result={}
+  for(const sheet of xmlChildren(xmlContent(sheetsNode),'sheet')){
+   const name=xmlAttribute(sheet,'name')
+   if(!name.startsWith('Mondays to Fridays')&&!(weekends&&name.startsWith('Saturdays')))continue
+   if(Object.hasOwn(result,name))throw new Error('Duplicate workbook sheet')
+   const link=targets.get(xmlAttribute(sheet,'id'));if(!link||xmlAttribute(link,'TargetMode')==='External')throw new Error('Invalid workbook relationship')
+   const target=xmlAttribute(link,'Target'),member=posix.normalize(target.startsWith('/')?target.slice(1):'xl/'+target)
+   if(!member.startsWith('xl/'))throw new Error('Worksheet escapes workbook')
+   const worksheet=rootContent(await read(member),'worksheet'),data=xmlChildren(worksheet,'sheetData')[0],rows=[]
+   const rowIds=new Set()
+   for(const row of xmlChildren(xmlContent(data),'row')){
+    const index=Number(xmlAttribute(row,'r'))-1
+    if(!Number.isInteger(index)||index<0||index>=10000||rowIds.has(index))throw new Error('Invalid or duplicate worksheet row')
+    rowIds.add(index);while(rows.length<=index)rows.push([])
+    const cols=new Set()
+    for(const cell of xmlChildren(xmlContent(row),'c')){
+     const address=/^([A-Z]+)(\d+)$/.exec(xmlAttribute(cell,'r')??'')
+     if(!address||Number(address[2])!==index+1)throw new Error('Invalid cell address')
+     let col=0;for(const letter of address[1])col=col*26+letter.charCodeAt(0)-64
+     if(col>16384||cols.has(col))throw new Error('Invalid or duplicate cell column');cols.add(col)
+     allocated+=Math.max(0,col-rows[index].length);if(allocated>maxCells)throw new Error('Worksheet cell budget exceeded')
+     while(rows[index].length<col)rows[index].push('')
+     const content=xmlContent(cell),value=xmlChildren(content,'v')[0],type=xmlAttribute(cell,'t')
+     let text=value?xmlText(xmlContent(value)):''
+     if(type==='s'){const i=Number(text);if(!/^\d+$/.test(text)||i>=strings.length)throw new Error('Invalid shared string reference');text=strings[i]}
+     else if(type==='inlineStr'){const inline=xmlChildren(content,'is')[0];text=inline?xmlText(xmlContent(inline)):''}
+     rows[index][col-1]=text
+    }
+   }
+   result[name]=rows
+  }
+  return result
+ }finally{if(temporary)await rm(temporary,{recursive:true,force:true})}
+}
+const SYMBOLS=new Set(['','/','T','TF','TB','U','D','A','T X','OP','S','T -D','T -U','T -DK','TBX','T -UK','T RM','T K -D','TBK','T K -U','TBN','U -D','D -U','TBS','TFN','TFS','T A','OPC','TBK KE','C A','C','X OP','OPX','RMN','RMD','RMU','D RM'])
+export function wttTiming(value){
+ const m=/^(\d{2})([A-Z/ -]*)(\d{2})(½?)$/.exec(value)
+ if(!m||!SYMBOLS.has(m[2])||Number(m[1])>23||Number(m[3])>59)throw new Error(`Unreviewed WTT time: ${value}`)
+ return [Number(m[1])*3600+Number(m[3])*60+(m[4]?30:0),m[2]]
+}
+export function wttRunsOn(code,dateRange,date){
+ checkedDate(date)
+ const parts=/^(\d{2})\/(\d{2})\/(\d{4}) to (\d{2})\/(\d{2})\/(\d{4})$/.exec(dateRange)
+ if(!parts)throw new Error(`Unreviewed date range: ${dateRange}`)
+ const start=checkedDate(`${parts[3]}-${parts[2]}-${parts[1]}`),end=checkedDate(`${parts[6]}-${parts[5]}-${parts[4]}`)
+ if(start>end)throw new Error('Reversed WTT date range')
+ if(date<start||date>end)return false
+ const m=/^((?:Th|Sun|[MTWFS])+)([OX])$/.exec(code)
+ if(!m)throw new Error(`Unreviewed running days: ${code}`)
+ const day=['Sun','M','T','W','Th','F','S'][new Date(date+'T12:00:00Z').getUTCDay()]
+ return m[1].match(/Th|Sun|[MTWFS]/g).includes(day)===(m[2]==='O')
+}
+export function wttTerminal(value){const i=value.lastIndexOf('\n');if(i<0)throw new Error('Missing terminal time');return [value.slice(0,i),wttTiming(value.slice(i+1).replaceAll(':',''))[0]]}
+
+/** Audit source columns without assigning stations or joining different table banks. */
+export function auditWttGrid(sheets,table,serviceDate,{includeColumn=()=>true}={}){
+ checkedDate(serviceDate)
+ const day=new Date(serviceDate+'T12:00:00Z').getUTCDay()
+ if(day===0)throw new Error('Sunday is not supported by the reviewed reader; no partial Sunday audit is produced')
+ const prefix=day===6?'Saturdays':'Mondays to Fridays',selected=Object.entries(sheets).filter(([name])=>name.startsWith(prefix))
+ if(!selected.length)throw new Error(`No ${prefix} bank in ${table}`)
+ const columns=[],rejected=[],expected=['TID','UID','Operator','Origin','Destination','Timing Load','Dates of Operation','Running Days','Service Code']
+ for(const [sheet,rows] of selected){
+  if(JSON.stringify(rows.slice(0,9).map(r=>r[1]??''))!==JSON.stringify(expected))throw new Error(`Unrecognized WTT headers: ${table}/${sheet}`)
+  let location='';const locations=[]
+  for(let i=9;i<rows.length;i++){const row=rows[i];if(row[0])location=row[0];if(['arr','dep','pass'].includes(row[1]))locations.push([i+1,location,row[1],row])}
+  for(let c=2;c<rows[0].length;c++){
+   const cell=r=>rows[r][c]??'',identity={table,sheet,column:c+1,uid:cell(1)}
+   try{
+    if(!wttRunsOn(cell(7),cell(6),serviceDate))continue
+    if(!cell(1))throw new Error('Missing UID')
+    const events=[];let previous=null,rollover=0
+    for(const [row,location,kind,values] of locations){
+     const sourceTime=values[c]??'';if(sourceTime===''||sourceTime==='..')continue
+     const [seconds,symbols]=wttTiming(sourceTime);let local=seconds+rollover*86400
+     if(previous!==null&&local<previous-43200){rollover++;local+=86400}
+     if(previous!==null&&local<previous)throw new Error('Non-monotonic timing sequence')
+     previous=local;events.push({location,kind,sourceTime,wallSecondsFromBankMidnight:local,symbols,row})
+    }
+    const column={...identity,tid:cell(0),operator:cell(2),origin:cell(3),destination:cell(4),datesOfOperation:cell(6),runningDays:cell(7),serviceCode:cell(8),events}
+    if(includeColumn(column))columns.push(column)
+   }catch(error){rejected.push({...identity,reason:error.message})}
+  }
+ }
+ return {columns,rejected}
+}

package/rail-xml.mjs

@@ -0,0 +1,12 @@
+import {XMLParser,XMLValidator} from 'fast-xml-parser'
+const parser=new XMLParser({preserveOrder:true,ignoreAttributes:false,parseTagValue:false,parseAttributeValue:false,trimValues:false,ignoreDeclaration:true,ignorePiTags:true})
+export function parseRailXml(bytes){
+ const xml=Buffer.from(bytes).toString('utf8')
+ if(/<!DOCTYPE|<!ENTITY/i.test(xml)||XMLValidator.validate(xml)!==true)throw new Error('Unsupported or invalid source XML')
+ return parser.parse(xml)
+}
+const local=name=>name.split(':').at(-1)
+export function xmlChildren(nodes,name){return (nodes??[]).filter(n=>Object.keys(n).some(k=>k!==':@'&&local(k)===name))}
+export function xmlContent(node){const key=Object.keys(node).find(k=>k!==':@');return node[key]}
+export function xmlText(nodes){return (nodes??[]).map(n=>Object.entries(n).filter(([k])=>k!==':@').map(([k,v])=>k==='#text'?String(v):Array.isArray(v)?xmlText(v):'').join('')).join('')}
+export function xmlAttribute(node,name){const attributes=node[':@']??{};const key=Object.keys(attributes).find(k=>local(k.replace(/^@_/,''))===name);return key===undefined?undefined:attributes[key]}

package/source-store.d.mts

@@ -0,0 +1,13 @@
+import type {Buffer} from 'node:buffer'
+export interface CaptureSource {id:string;publisher:string;kind:string;documentation:string;license:string;attribution?:string;origins:readonly string[]}
+export interface CaptureRecord {schemaVersion:1;source:Omit<CaptureSource,'origins'>;url:string;sha256:string;bytes:number;retrievedAt:string|null;importedAt?:string;acquisition:'http'|'local-import';validation:string;httpStatus?:number;contentType?:string|null;lastModified?:string|null;etag?:string|null}
+export interface CaptureResult {bytes:Buffer;record:CaptureRecord;cached:boolean}
+export type CaptureValidator=(bytes:Buffer)=>unknown|Promise<unknown>
+export interface CaptureOptions {store:string;source:CaptureSource;url:string;offline?:boolean;refresh?:boolean;maxBytes?:number;timeoutMs?:number;retries?:number;validate?:CaptureValidator;fetchImpl?:typeof fetch;userAgent?:string}
+export function sha256(bytes:string|Uint8Array):string
+export function publicSourceUrl(source:CaptureSource,value:string):string
+export function atomicJson(path:string,value:unknown):Promise<void>
+export function readCapture(store:string,source:CaptureSource,url:string,validate?:CaptureValidator):Promise<CaptureResult>
+export function importCapture(options:Pick<CaptureOptions,'store'|'source'|'url'|'maxBytes'|'validate'>&{input:string}):Promise<CaptureResult>
+export function capture(options:CaptureOptions):Promise<CaptureResult>
+export function jsonDocument(bytes:Buffer):Record<string,unknown>|unknown[]

package/source-store.mjs

@@ -0,0 +1,127 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { mkdir, readFile, writeFile, rename, rm, stat } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+
+export const sha256 = bytes => createHash('sha256').update(bytes).digest('hex')
+
+export function publicSourceUrl(source, value) {
+  const url = new URL(value)
+  if (url.protocol !== 'https:' || url.username || url.password || url.hash ||
+      [...url.searchParams.keys()].some(key => /key|token|password|secret|signature|credential/i.test(key))) {
+    throw new Error('Source URLs must be public HTTPS URLs without credentials or fragments')
+  }
+  if (!source.origins.includes(url.origin)) throw new Error(`URL origin is not configured for ${source.id}`)
+  return url.href
+}
+
+export async function atomicJson(path, value) {
+  await atomicWrite(path, Buffer.from(`${JSON.stringify(value, null, 2)}\n`))
+}
+
+async function atomicWrite(path, bytes) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+  const temporary = `${path}.${randomUUID()}.partial`
+  try {
+    await writeFile(temporary, bytes, { mode: 0o600 })
+    await rename(temporary, path)
+  } finally {
+    await rm(temporary, { force: true })
+  }
+}
+
+function requestKey(source, url) { return sha256(`${source.id}\n${url}`) }
+
+export async function readCapture(store, source, url, validate = () => {}) {
+  const record = JSON.parse(await readFile(join(store, 'requests', `${requestKey(source, url)}.json`), 'utf8'))
+  if (record.source.id !== source.id || record.url !== url || !/^[a-f0-9]{64}$/.test(record.sha256)) throw new Error('Capture identity mismatch')
+  const bytes = await readFile(join(store, 'objects', record.sha256))
+  if (bytes.length !== record.bytes || sha256(bytes) !== record.sha256) throw new Error('Capture integrity check failed')
+  await validate(bytes)
+  return { bytes, record, cached: true }
+}
+
+async function persist(store, source, url, bytes, acquisition, response = {}) {
+  const hash = sha256(bytes)
+  const record = {
+    schemaVersion: 1, source: { id: source.id, publisher: source.publisher, kind: source.kind, documentation: source.documentation, license: source.license, ...(source.attribution ? { attribution: source.attribution } : {}) },
+    url, sha256: hash, bytes: bytes.length,
+    ...(acquisition === 'http' ? { retrievedAt: new Date().toISOString() } : { retrievedAt: null, importedAt: new Date().toISOString() }),
+    acquisition, validation: 'raw-capture; see adapter audit for fitness', ...response,
+  }
+  await atomicWrite(join(store, 'objects', hash), bytes)
+  await atomicJson(join(store, 'records', `${randomUUID()}.json`), record)
+  await atomicJson(join(store, 'requests', `${requestKey(source, url)}.json`), record)
+  return { bytes, record, cached: false }
+}
+
+export async function importCapture({ store, source, url, input, maxBytes = 512 * 1024 * 1024, validate = () => {} }) {
+  url = publicSourceUrl(source, url)
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new Error('Expected a positive byte limit')
+  if ((await stat(input)).size > maxBytes) throw new Error('Source file exceeds byte limit')
+  const bytes = await readFile(input)
+  if (!bytes.length || bytes.length > maxBytes) throw new Error('Source file is empty or exceeds byte limit')
+  await validate(bytes)
+  return persist(store, source, url, bytes, 'local-import')
+}
+
+export async function capture({ store, source, url, offline = false, refresh = false, maxBytes = 32 * 1024 * 1024, timeoutMs = 20000, retries = 2, validate = () => {}, fetchImpl = fetch, userAgent = 'Motion Studies source capture' }) {
+  url = publicSourceUrl(source, url)
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || !Number.isSafeInteger(retries) || retries < 0 || retries > 10) throw new Error('Invalid capture limits')
+  if (offline && refresh) throw new Error('Offline and refresh cannot be combined')
+  if (!refresh) {
+    try { return await readCapture(store, source, url, validate) }
+    catch (error) { if (error.code !== 'ENOENT') throw error }
+  }
+  if (offline) throw new Error(`No cached capture for ${source.id}; offline mode never downloads`)
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    let retryable = true
+    try {
+      const response = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs), headers: { 'User-Agent': userAgent } })
+      if (response.status === 204) {
+        retryable = false
+        throw new Error('Source returned HTTP 204: no report content; this does not mean zero traffic')
+      }
+      if (!response.ok) {
+        retryable = response.status === 429 || response.status >= 500
+        await response.body?.cancel()
+        throw new Error(`Source returned HTTP ${response.status}`)
+      }
+      if (Number(response.headers.get('content-length')) > maxBytes) {
+        retryable = false
+        await response.body?.cancel()
+        throw new Error('Source exceeds byte limit')
+      }
+      if (!response.body) throw new Error('Source response has no body')
+      const reader = response.body.getReader()
+      const chunks = []
+      let size = 0
+      try {
+        while (true) {
+          const { value, done } = await reader.read()
+          if (done) break
+          size += value.length
+          if (size > maxBytes) { retryable = false; await reader.cancel(); throw new Error('Source exceeds byte limit') }
+          chunks.push(value)
+        }
+      } finally { reader.releaseLock() }
+      const bytes = Buffer.concat(chunks)
+      retryable = false
+      if (!bytes.length) throw new Error('Source response is empty')
+      await validate(bytes)
+      return await persist(store, source, url, bytes, 'http', {
+        httpStatus: response.status, contentType: response.headers.get('content-type'),
+        lastModified: response.headers.get('last-modified'), etag: response.headers.get('etag'),
+      })
+    } catch (error) {
+      if (!retryable || attempt === retries) throw error
+      await delay(250 * 2 ** attempt)
+    }
+  }
+}
+
+export function jsonDocument(bytes) {
+  const value = JSON.parse(bytes.toString('utf8'))
+  if (!value || typeof value !== 'object') throw new Error('Expected a JSON document')
+  return value
+}

package/uk-service-day.d.mts

@@ -0,0 +1,6 @@
+/** UK civil day boundaries. GTFS service time has a separate noon-based origin. */
+export interface UkStudyDay {serviceDate:string;timezone:'Europe/London';startUtc:string;endUtc:string;durationSeconds:number}
+export function checkedDate(value:string):string
+export function studyDay(serviceDate:string):UkStudyDay
+export function utcDatesForDay(day:UkStudyDay):string[]
+export function gtfsServiceInstant(serviceDate:string,seconds:number):string

package/uk-service-day.mjs

@@ -0,0 +1,49 @@
+const TIMEZONE = 'Europe/London'
+
+export function checkedDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value ?? '') || !Number.isFinite(Date.parse(`${value}T00:00:00Z`)) ||
+      new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) !== value) {
+    throw new Error('An actual service date in YYYY-MM-DD form is required')
+  }
+  return value
+}
+
+// UK midnight is unambiguous on both DST transition days. Never infer a full day as 86400 seconds.
+function londonMidnight(date) {
+  const nominal = Date.parse(`${date}T00:00:00Z`)
+  const formatter = new Intl.DateTimeFormat('en-GB', { timeZone: TIMEZONE, timeZoneName: 'longOffset' })
+  let instant = nominal
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const offset = formatter.formatToParts(instant).find(part => part.type === 'timeZoneName').value
+    const match = /^GMT([+-])(\d{2}):(\d{2})$/.exec(offset)
+    if (offset !== 'GMT' && !match) throw new Error('Unsupported timezone offset')
+    const minutes = match ? (match[1] === '+' ? 1 : -1) * (Number(match[2]) * 60 + Number(match[3])) : 0
+    instant = nominal - minutes * 60000
+  }
+  return instant
+}
+
+export function studyDay(serviceDate) {
+  checkedDate(serviceDate)
+  const next = new Date(Date.parse(`${serviceDate}T00:00:00Z`) + 86400000).toISOString().slice(0, 10)
+  const start = londonMidnight(serviceDate)
+  const end = londonMidnight(next)
+  return { serviceDate, timezone: TIMEZONE, startUtc: new Date(start).toISOString(), endUtc: new Date(end).toISOString(), durationSeconds: (end - start) / 1000 }
+}
+
+export function utcDatesForDay(day) {
+  const first = Date.parse(day.startUtc.slice(0, 10))
+  const last = Date.parse(new Date(Date.parse(day.endUtc) - 1).toISOString().slice(0, 10))
+  const dates = []
+  for (let time = first; time <= last; time += 86400000) dates.push(new Date(time).toISOString().slice(0, 10))
+  return dates
+}
+
+// GTFS defines service time from local noon minus twelve elapsed hours. On UK
+// DST transition days this differs from the observed civil-day midnight.
+export function gtfsServiceInstant(serviceDate, seconds) {
+  if (!Number.isSafeInteger(seconds) || seconds < 0) throw new Error('GTFS seconds must be a nonnegative whole number')
+  const day = studyDay(serviceDate)
+  const noonMinusTwelveHours = Date.parse(day.endUtc) - 86400000
+  return new Date(noonMinusTwelveHours + seconds * 1000).toISOString()
+}

package/webtris.d.mts

@@ -0,0 +1,14 @@
+export interface WebtrisSite {id:string;description:string}
+export interface WebtrisSample {interval:number;periodEnding:string;totalVolume:number|null;averageSpeedMph:number|null;lengthClassCounts:(number|null)[];classTotalMatches:boolean|null}
+export interface WebtrisReport<S extends WebtrisSite=WebtrisSite> {
+ schemaVersion:1;kind:'observed-detector-report-audit';serviceDate:string;
+ clock:{basis:string;timezone:null;utcMapping:string;nominalIntervals:96;completeness:string};
+ lengthClasses:string[];representation:string;
+ audit:{inputRows:number;foreignSite:number;foreignDate:number;invalidInterval:number;exactDuplicates:number;conflictingIntervals:number};
+ observations:{site:S;samples:WebtrisSample[];reportIntervals:number;validVolumeIntervals:number;validSpeedIntervals:number;missingNominalIntervals:number[];conflictingIntervals:number[];classTotalMismatches:number}[];
+}
+export function reportUrl(siteIds:readonly string[],serviceDate:string,page:number,pageSize?:number):string
+/** Source slots and labels are retained. No UTC placement, flow-rate conversion or class inference. */
+export function normalizeReports<S extends WebtrisSite>(rows:readonly Record<string,unknown>[],sites:readonly S[],serviceDate:string):WebtrisReport<S>
+/** Pass stable source-record references (for example capture SHA-256 identities). */
+export function aggregateRoadSeries(observation:WebtrisReport['observations'][number],serviceDate:string,dataset:string,sourceRecordIds:readonly string[]):import('@motionstudies/core/domain/aggregate-road').AggregateRoadSeries

package/webtris.mjs

@@ -0,0 +1,67 @@
+import { checkedDate } from './uk-service-day.mjs'
+
+const ENDPOINT = 'https://webtris.nationalhighways.co.uk/api/v1.0/reports/daily'
+const CLASSES = ['0 - 520 cm', '521 - 660 cm', '661 - 1160 cm', '1160+ cm']
+const number = (v, integer = false) => {
+  if (!['number', 'string'].includes(typeof v) || String(v).trim() === '') return null
+  const n = Number(v)
+  return Number.isFinite(n) && n >= 0 && (!integer || Number.isInteger(n)) ? n : null
+}
+export function reportUrl(siteIds, serviceDate, page, pageSize = 1000) {
+  checkedDate(serviceDate)
+  if (!siteIds.length || siteIds.length > 10 || siteIds.some(id => !/^\d+$/.test(id)) || new Set(siteIds).size !== siteIds.length) throw new Error('Select 1..10 distinct numeric site IDs')
+  if (!Number.isSafeInteger(page) || page < 1 || !Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 1000) throw new Error('Expected a positive page and page size of 1..1000')
+  const date = serviceDate.split('-').reverse().join('')
+  return `${ENDPOINT}?${new URLSearchParams({ sites: siteIds.join(','), start_date: date, end_date: date, page: String(page), page_size: String(pageSize) }).toString().replaceAll('%2C', ',')}`
+}
+
+export function normalizeReports(rows, sites, serviceDate) {
+  checkedDate(serviceDate)
+  if (!Array.isArray(rows) || !Array.isArray(sites) || sites.some(s => !s || typeof s.id !== 'string' || typeof s.description !== 'string') || new Set(sites.map(s => s.id)).size !== sites.length) throw new Error('Expected rows and unique named sites')
+  const names = new Map(sites.map(site => [site.description, site]))
+  if (names.size !== sites.length) throw new Error('Selected site descriptions are ambiguous')
+  const grouped = new Map(sites.map(site => [site.id, new Map()]))
+  const audit = { inputRows: rows.length, foreignSite: 0, foreignDate: 0, invalidInterval: 0, exactDuplicates: 0, conflictingIntervals: 0 }
+  for (const row of rows) {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) throw new Error('Invalid WebTRIS row')
+    const site = names.get(row['Site Name'])
+    if (!site) { audit.foreignSite++; continue }
+    if (row['Report Date'] !== `${serviceDate}T00:00:00`) { audit.foreignDate++; continue }
+    const interval = number(row['Time Interval'], true)
+    const ending = row['Time Period Ending']
+    // Preserve the source's minute-inclusive ending label (00:14 etc). No invented UTC offset.
+    if (interval === null || interval > 99 || !/^([01]\d|2[0-3]):[0-5]\d:[0-5]\d$/.test(ending ?? '')) { audit.invalidInterval++; continue }
+    const sample = { interval, periodEnding: ending, totalVolume: number(row['Total Volume'], true), averageSpeedMph: number(row['Avg mph']), lengthClassCounts: CLASSES.map(key => number(row[key], true)) }
+    sample.classTotalMatches = sample.totalVolume === null || sample.lengthClassCounts.includes(null) ? null : sample.lengthClassCounts.reduce((a,b) => a+b,0) === sample.totalVolume
+    const map = grouped.get(site.id)
+    if (map.has(interval)) {
+      if (JSON.stringify(map.get(interval)) === JSON.stringify(sample)) audit.exactDuplicates++
+      else { if (map.get(interval) !== null) audit.conflictingIntervals++; map.set(interval, null) }
+    } else map.set(interval, sample)
+  }
+  const observations = sites.map(site => {
+    const map = grouped.get(site.id)
+    const samples = [...map.values()].filter(Boolean).sort((a,b) => a.interval-b.interval)
+    return { site, samples, reportIntervals: samples.length, validVolumeIntervals: samples.filter(x => x.totalVolume !== null).length, validSpeedIntervals: samples.filter(x => x.averageSpeedMph !== null).length,
+      missingNominalIntervals: Array.from({ length: 96 }, (_,i) => i).filter(i => !map.get(i)),
+      conflictingIntervals: [...map].filter(([,v]) => v === null).map(([i])=>i).sort((a,b)=>a-b),
+      classTotalMismatches: samples.filter(x => x.classTotalMatches === false).length }
+  })
+  return { schemaVersion: 1, kind: 'observed-detector-report-audit', serviceDate, clock: { basis: 'Provider report date, interval index and period-ending label', timezone: null, utcMapping: 'Unverified; not placed on the scene clock', nominalIntervals: 96, completeness: '96-slot reference only; DST and source time semantics require verification' }, lengthClasses: CLASSES, audit, observations,
+    representation: 'Point detector counts and reported mph; no reconstructed vehicles, light/heavy inference or gap interpolation' }
+}
+
+
+/** Translate source observations without placing their unverified clock onto UTC. */
+export function aggregateRoadSeries(observation, serviceDate, dataset, sourceRecordIds) {
+  checkedDate(serviceDate)
+  if (!dataset || !observation?.site?.id || !Array.isArray(sourceRecordIds) || !sourceRecordIds.length || sourceRecordIds.some(id => typeof id !== 'string' || !id)) throw new Error('Aggregate evidence requires dataset, site and source records')
+  return {
+    id: JSON.stringify(['webtris', dataset, observation.site.id]), provider: 'webtris', dataset, siteId: observation.site.id,
+    samples: observation.samples.map(s => ({
+      interval: { kind: 'provider-slot', serviceDate, index: s.interval, endingLabel: s.periodEnding },
+      vehicleCount: s.totalVolume, averageSpeed: s.averageSpeedMph === null ? null : { value: s.averageSpeedMph, unit: 'mph' },
+      sourceRecordIds: [...sourceRecordIds],
+    })),
+  }
+}