@motionstudies/data 0.1.0-alpha.3 → 0.1.0-alpha.31

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/recorder-evidence.d.mts

@@ -0,0 +1,14 @@
+import type { FeedHealth } from './feed-observability.mjs'
+export interface RecorderEvidencePlan {
+  schemaVersion: 1
+  kind: 'recorder-evidence-plan'
+  producerId: string
+  validUntil: string
+  feeds: {
+    feedId: string
+    archive?: { journalPath: string; closeoutPath: string; expectedEnd: string; deadlineAt: string }
+    publication?: { pointerPath: string; operator: string; expectedThrough: string; deadlineAt: string }
+  }[]
+}
+/** Reads explicitly selected local files, with integrity checks, 256 MiB per journal and a 512 MiB total read budget. */
+export function recorderEvidenceHealth(registry: unknown, report: unknown, plan: unknown): Promise<FeedHealth>