@motionstudies/data 0.1.0-alpha.2 → 0.1.0-alpha.21

package/air-endpoints.mjs

@@ -0,0 +1,130 @@
+import { readFile, readdir, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { gunzipSync } from 'node:zlib'
+import { createHash } from 'node:crypto'
+import { parseCsvLine } from './gtfs.mjs'
+import { decodeAdsbHeatmap } from './adsb-heatmap.mjs'
+
+export function parseAirports(csv) {
+  const [header, ...lines] = csv.trim().split(/\r?\n/)
+  const keys = parseCsvLine(header)
+  return lines.map(line => Object.fromEntries(parseCsvLine(line).map((value, index) => [keys[index], value])))
+    .filter(row => ['large_airport', 'medium_airport'].includes(row.type) && row.ident && row.elevation_ft)
+    .map(row => ({ icao: row.ident, iata: row.iata_code, name: row.name, city: row.municipality,
+      longitude: Number(row.longitude_deg), latitude: Number(row.latitude_deg), elevation: Number(row.elevation_ft) }))
+    .filter(row => [row.longitude, row.latitude, row.elevation].every(Number.isFinite))
+}
+
+function distance(sample, airport) {
+  const longitude = ((sample[1] - airport.longitude + 540) % 360) - 180
+  return Math.hypot(longitude * 111.32 * Math.cos((sample[2] + airport.latitude) * Math.PI / 360), (sample[2] - airport.latitude) * 111.32)
+}
+
+function atAirport(sample, airport) {
+  return sample[3] >= airport.elevation - 500 && sample[3] <= airport.elevation + 1500 && sample[4] <= 250 && distance(sample, airport) <= 6
+}
+
+/** Conservative endpoint association; cruise-only traces and ambiguous neighbouring airports stay unknown. */
+export function inferAirEndpoints(samples, airports) {
+  if (samples.length < 4) return {}
+  const maximumAltitude = Math.max(...samples.map(sample => sample[3]))
+  const endpoint = (arrival) => {
+    const ordered = arrival ? [...samples].reverse() : samples
+    const candidates = airports.filter(airport => atAirport(ordered[0], airport) && maximumAltitude >= airport.elevation + 3000)
+    if (candidates.length !== 1) return undefined
+    const airport = candidates[0]
+    let boundary = ordered[0]
+    for (const sample of ordered.slice(1)) {
+      if (!atAirport(sample, airport)) break
+      boundary = sample
+    }
+    return { icao: airport.icao, iata: airport.iata, name: airport.name, city: airport.city, time: boundary[0], evidence: 'observed-endpoint' }
+  }
+  const origin = endpoint(false), destination = endpoint(true)
+  if (origin && destination && (origin.icao === destination.icao || origin.time >= destination.time)) return {}
+  return { ...(origin ? { origin } : {}), ...(destination ? { destination } : {}) }
+}
+
+function segmentsFor(samples) {
+  const segments = []
+  let current = []
+  for (const sample of samples.sort((a, b) => a[0] - b[0])) {
+    const previous = current.at(-1)
+    if (previous && previous[0] === sample[0]) continue
+    if (previous && (sample[0] - previous[0] > 1800 || sample[5] !== previous[5])) {
+      segments.push(current)
+      current = []
+    }
+    current.push(sample)
+  }
+  if (current.length) segments.push(current)
+  return segments
+}
+
+/** Enrich an existing study and its chunks using cached, same-date global heatmaps. No network requests. */
+export async function enrichAirEndpoints({ manifestPath, snapshotPaths = [], heatmapDirectory, airportCsvPath, utcOffsetHours }) {
+  const readJson = async path => JSON.parse(await readFile(path, 'utf8'))
+  const manifest = await readJson(manifestPath)
+  const snapshots = await Promise.all(snapshotPaths.map(readJson))
+  const date = manifest.metadata.serviceDate
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || !Number.isFinite(utcOffsetHours)) throw new Error('A service date and UTC offset are required')
+  if (snapshots.some(snapshot => snapshot.metadata.serviceDate !== date)) throw new Error('Air snapshots must share the manifest service date')
+  const tracks = [...manifest.aircraft, ...snapshots.flatMap(snapshot => snapshot.tracks)]
+  const wanted = new Set(tracks.map(track => parseInt(track.icaoAddress ?? track.id.split('-')[0], 16)))
+  const records = new Map()
+  const files = (await readdir(heatmapDirectory)).filter(file => file.endsWith('.bin.ttf')).sort()
+  if (!files.length) throw new Error('No cached heatmap slices found')
+  const sources = []
+  for (const file of files) {
+    const raw = await readFile(join(heatmapDirectory, file))
+    const used = decodeAdsbHeatmap(gunzipSync(raw), {
+      serviceDate: date, utcOffsetHours, windowStart: 0, windowEnd: 86400, addresses: wanted,
+    }, (id, sample) => {
+      const samples = records.get(id) ?? []
+      sample[5] ??= samples.at(-1)?.[5] ?? ''
+      samples.push(sample)
+      records.set(id, samples)
+    })
+    if (used) sources.push({ file, sha256: createHash('sha256').update(raw).digest('hex') })
+  }
+  const csv = await readFile(airportCsvPath, 'utf8')
+  if (!sources.length) throw new Error('No same-date observations matched the study aircraft')
+  const airports = parseAirports(csv)
+  if (!airports.length) throw new Error('No usable airports in the reference CSV')
+  const segments = new Map([...records].map(([id, samples]) => [id, segmentsFor(samples).map(samples => ({
+    start: samples[0][0], end: samples.at(-1)[0], callsign: samples[0][5], ...inferAirEndpoints(samples, airports),
+  }))]))
+  const enrich = (track) => {
+    const candidates = (segments.get(parseInt(track.icaoAddress ?? track.id.split('-')[0], 16)) ?? [])
+      .filter(segment => segment.callsign && segment.callsign === track.callsign && segment.start <= track.start + 30 && segment.end >= track.end - 30)
+    const { origin: _origin, destination: _destination, ...rest } = track
+    if (candidates.length !== 1) return rest
+    const { origin, destination } = candidates[0]
+    return { ...rest, ...(origin ? { origin } : {}), ...(destination ? { destination } : {}) }
+  }
+  const metadata = {
+    serviceDate: date, method: 'observed-endpoint', note: 'Origin/destination inferred from full-trace endpoints within 6 km and 1500 ft above an airport; observed times, not schedules or confirmed flight plans.',
+    airportSource: 'https://ourairports.com/data/', airportLicense: 'Public Domain', airportSha256: createHash('sha256').update(csv).digest('hex'),
+    traceSource: manifest.metadata.sourceUrl, traceLicense: 'ODbL 1.0', utcOffsetHours, sourceFiles: sources,
+  }
+  const aircraft = manifest.aircraft.map(enrich)
+  const byId = new Map(aircraft.map(track => [track.id, track]))
+  const writes = []
+  for (const descriptor of manifest.chunks) {
+    const path = join(dirname(manifestPath), descriptor.path)
+    const chunk = await readJson(path)
+    chunk.tracks = chunk.tracks.map(track => {
+      const { origin: _origin, destination: _destination, ...rest } = track
+      const full = byId.get(track.id)
+      return { ...rest, ...(full?.origin ? { origin: full.origin } : {}), ...(full?.destination ? { destination: full.destination } : {}) }
+    })
+    const bytes = Buffer.from(`${JSON.stringify(chunk)}\n`)
+    if ('bytes' in descriptor) descriptor.bytes = bytes.length
+    if ('sha256' in descriptor) descriptor.sha256 = createHash('sha256').update(bytes).digest('hex')
+    writes.push([path, chunk])
+  }
+  writes.push([manifestPath, { ...manifest, metadata: { ...manifest.metadata, routeEnrichment: metadata }, aircraft }])
+  snapshots.forEach((snapshot, index) => writes.push([snapshotPaths[index], { ...snapshot, metadata: { ...snapshot.metadata, routeEnrichment: metadata }, tracks: snapshot.tracks.map(enrich) }]))
+  for (const [path, value] of writes) await writeFile(path, `${JSON.stringify(value)}\n`)
+  return { tracks: aircraft.length, origins: aircraft.filter(track => track.origin).length, destinations: aircraft.filter(track => track.destination).length }
+}

package/network-chunk-cli.d.mts

@@ -0,0 +1 @@
+export function runNetworkChunkCli(argv?: readonly string[]): Promise<void>

package/network-chunk-cli.mjs

@@ -0,0 +1,65 @@
+import { chunkNetworkSnapshot, extractNetworkWindow } from './network-chunks.mjs'
+
+import { createWriteStream } from 'node:fs'
+import { mkdir, readFile } from 'node:fs/promises'
+import { basename, dirname, extname, join, resolve } from 'node:path'
+
+function argument(argv, name, fallback) {
+  const index = argv.indexOf(`--${name}`)
+  return index === -1 ? fallback : argv[index + 1]
+}
+
+function parseClock(value) {
+  const [hours, minutes = 0] = value.split(':').map(Number)
+  if (!Number.isFinite(hours) || !Number.isFinite(minutes)) {
+    throw new Error(`Invalid clock value ${value}`)
+  }
+  return hours * 3600 + minutes * 60
+}
+
+async function writeJson(filePath, value) {
+  await mkdir(dirname(filePath), { recursive: true })
+  await new Promise((resolvePromise, rejectPromise) => {
+    const output = createWriteStream(filePath)
+    output.once('error', rejectPromise)
+    output.once('finish', resolvePromise)
+    output.end(JSON.stringify(value))
+  })
+}
+
+export async function runNetworkChunkCli(argv = process.argv.slice(2)) {
+  const input = argument(argv, 'input')
+  const manifestOutput = argument(argv, 'manifest')
+  const openingOutput = argument(argv, 'opening')
+  if (!input || !manifestOutput || !openingOutput) {
+    throw new Error(
+      'Usage: node scripts/chunk-network-snapshot.mjs --input day.json --manifest day-manifest.json --opening morning.json [--chunk-hours 2] [--opening-start 06:45] [--opening-end 08:45] [--focus 07:45]',
+    )
+  }
+  const snapshot = JSON.parse(await readFile(resolve(input), 'utf8'))
+  const manifestPath = resolve(manifestOutput)
+  const outputDirectory = dirname(manifestPath)
+  const outputStem = basename(manifestPath, extname(manifestPath)).replace(/-manifest$/, '')
+  const chunkDirectoryName = `${outputStem}-chunks`
+  const { manifest, chunks } = chunkNetworkSnapshot(
+    snapshot,
+    Number(argument(argv, 'chunk-hours', '2')) * 3600,
+    chunkDirectoryName,
+  )
+  const opening = extractNetworkWindow(
+    snapshot,
+    parseClock(argument(argv, 'opening-start', '06:45')),
+    parseClock(argument(argv, 'opening-end', '08:45')),
+    parseClock(argument(argv, 'focus', '07:45')),
+  )
+  await Promise.all([
+    writeJson(manifestPath, manifest),
+    writeJson(resolve(openingOutput), opening),
+    ...chunks.map(({ descriptor, payload }) =>
+      writeJson(join(outputDirectory, descriptor.path), payload),
+    ),
+  ])
+  console.log(
+    `Wrote ${manifestOutput}, ${chunks.length} progressive chunks and ${opening.trains.length} opening journeys.`,
+  )
+}

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.2",
+  "version": "0.1.0-alpha.21",
   "private": false,
   "type": "module",
   "description": "Offline data preparation primitives for Motion Studies.",
@@ -20,9 +20,21 @@
     "tag": "next"
   },
   "engines": {
-    "node": ">=20"
+    "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"
+    },
+    "./air-endpoints": {
+      "types": "./air-endpoints.d.mts",
+      "import": "./air-endpoints.mjs"
+    },
     "./gtfs": {
       "types": "./gtfs.d.mts",
       "import": "./gtfs.mjs"
@@ -38,6 +50,42 @@
     "./merge-network": {
       "types": "./merge-network.d.mts",
       "import": "./merge-network.mjs"
+    },
+    "./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": [
@@ -46,11 +94,14 @@
     "**/*.d.ts",
     "**/*.d.mts",
     "**/*.css",
+    "**/*.woff2",
+    "**/*-OFL.txt",
     "README.md",
     "LICENSE"
   ],
   "sideEffects": false,
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.2"
+    "@motionstudies/core": "0.1.0-alpha.21",
+    "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