@motionstudies/core 0.1.0-alpha.2 → 0.1.0-alpha.20

package/domain/gridded-series.d.ts

@@ -0,0 +1,30 @@
+/** A regular latitude/longitude grid of one or more variables at listed instants, such as cloud
+ * cover, rainfall or a model wind component. Values keep the source's own units; null marks a
+ * missing sample. Readings interpolate bilinearly in space and linearly in time, and a missing
+ * sample with any weight makes the whole reading unavailable rather than bridging the gap.
+ */
+export interface GriddedSeriesGrid {
+    readonly west: number;
+    readonly south: number;
+    readonly step: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface GriddedSeries<K extends string = string> {
+    /** ISO instants in ascending order. */
+    readonly times: readonly string[];
+    readonly grid: GriddedSeriesGrid;
+    /** One frame per instant; rows run south to north. */
+    readonly frames: readonly Readonly<Partial<Record<K, readonly (number | null)[]>>>[];
+}
+export interface TimeBracket {
+    readonly a: number;
+    readonly b: number;
+    readonly fraction: number;
+}
+/** The adjacent frames around an instant. Exact instants bracket themselves; instants outside the series are null. */
+export declare function bracketTime(times: readonly string[], time: string | number): TimeBracket | null;
+/** One variable at a place and instant, or null outside the grid, outside the times, or beside a missing sample. */
+export declare function sampleGriddedSeries<K extends string>(series: GriddedSeries<K>, key: K, latitude: number, longitude: number, time: string | number): number | null;
+/** Area-weighted mean of one variable over the whole grid at an instant. Any missing or out-of-range weighted sample makes the mean unavailable. */
+export declare function meanGriddedSeries<K extends string>(series: GriddedSeries<K>, key: K, time: string | number, range?: readonly [number, number]): number | null;

package/domain/gridded-series.js

@@ -0,0 +1,61 @@
+/** The adjacent frames around an instant. Exact instants bracket themselves; instants outside the series are null. */
+export function bracketTime(times, time) {
+    const value = typeof time === 'number' ? time : Date.parse(time);
+    if (!times.length || !Number.isFinite(value) || value < Date.parse(times[0]) || value > Date.parse(times[times.length - 1]))
+        return null;
+    for (let i = 0; i < times.length; i++) {
+        const stamp = Date.parse(times[i]);
+        if (value === stamp)
+            return { a: i, b: i, fraction: 0 };
+        if (stamp > value)
+            return { a: i - 1, b: i, fraction: (value - Date.parse(times[i - 1])) / (stamp - Date.parse(times[i - 1])) };
+    }
+    return null;
+}
+const valid = (sample, range) => typeof sample === 'number' && Number.isFinite(sample) && (!range || (sample >= range[0] && sample <= range[1]));
+/** One variable at a place and instant, or null outside the grid, outside the times, or beside a missing sample. */
+export function sampleGriddedSeries(series, key, latitude, longitude, time) {
+    const bracket = bracketTime(series.times, time), { west, south, step, width, height } = series.grid, x = (longitude - west) / step, y = (latitude - south) / step;
+    if (!bracket || !(x >= 0 && y >= 0 && x <= width - 1 && y <= height - 1))
+        return null;
+    const x0 = Math.floor(x), y0 = Math.floor(y), fx = x - x0, fy = y - y0;
+    let value = 0;
+    for (const [t, wt] of [[bracket.a, 1 - bracket.fraction], [bracket.b, bracket.fraction]]) {
+        for (const [ix, wx] of [[x0, 1 - fx], [Math.min(x0 + 1, width - 1), fx]])
+            for (const [iy, wy] of [[y0, 1 - fy], [Math.min(y0 + 1, height - 1), fy]]) {
+                const weight = wt * wx * wy;
+                if (weight === 0)
+                    continue;
+                const sample = series.frames[t]?.[key]?.[iy * width + ix];
+                if (!valid(sample))
+                    return null;
+                value += sample * weight;
+            }
+    }
+    return value;
+}
+/** Area-weighted mean of one variable over the whole grid at an instant. Any missing or out-of-range weighted sample makes the mean unavailable. */
+export function meanGriddedSeries(series, key, time, range) {
+    const bracket = bracketTime(series.times, time);
+    if (!bracket)
+        return null;
+    const { south, step, width, height } = series.grid;
+    let sum = 0, weight = 0;
+    for (let y = 0; y < height; y++) {
+        const area = Math.cos((south + y * step) * Math.PI / 180);
+        for (let x = 0; x < width; x++) {
+            let value = 0;
+            for (const [frame, w] of [[bracket.a, 1 - bracket.fraction], [bracket.b, bracket.fraction]]) {
+                if (w === 0)
+                    continue;
+                const sample = series.frames[frame]?.[key]?.[y * width + x];
+                if (!valid(sample, range))
+                    return null;
+                value += sample * w;
+            }
+            sum += value * area;
+            weight += area;
+        }
+    }
+    return weight ? sum / weight : null;
+}

package/domain/live-airport.d.ts

@@ -0,0 +1,42 @@
+/** Live boards use Unix seconds throughout, independent of an edition's recorded service day. */
+export interface LiveAirportMovement {
+    readonly id: string;
+    readonly service: string;
+    readonly scheduledTime?: number;
+    /** Provider revision: may be estimated or actual; do not relabel as confirmed. */
+    readonly revisedTime?: number;
+    readonly place?: string;
+    readonly gate?: string;
+    readonly status?: string;
+    readonly tone?: 'neutral' | 'accent' | 'warning';
+}
+export interface LiveAirportSnapshot {
+    readonly airport: {
+        readonly iata: string;
+        readonly name: string;
+        readonly city: string;
+        readonly timeZone: string;
+    };
+    readonly fetchedAt: number;
+    readonly freshUntil: number;
+    readonly expiresAt: number;
+    readonly windowStart: number;
+    readonly windowEnd: number;
+    readonly departures: readonly LiveAirportMovement[];
+    readonly arrivals: readonly LiveAirportMovement[];
+}
+export type AirportFeedReason = 'disabled' | 'not-configured' | 'subscription' | 'budget' | 'provider' | 'rate-limit';
+export interface AirportFeedResponse {
+    readonly version: 1;
+    readonly status: 'fresh' | 'stale' | 'unavailable' | 'disabled';
+    readonly reason?: AirportFeedReason;
+    readonly retryAfterSeconds: number;
+    readonly snapshot?: LiveAirportSnapshot;
+}
+export interface AirportFeedCapabilities {
+    readonly version: 1;
+    readonly enabled: boolean;
+    readonly airports: readonly string[];
+}
+/** Validate the network boundary before publishing data to a card. */
+export declare function isAirportFeedResponse(value: unknown): value is AirportFeedResponse;

package/domain/live-airport.js

@@ -0,0 +1,32 @@
+const record = (value) => !!value && typeof value === 'object';
+const finite = (value) => typeof value === 'number' && Number.isFinite(value);
+function movement(value) {
+    return record(value) && typeof value.id === 'string' && typeof value.service === 'string'
+        && ['scheduledTime', 'revisedTime'].every((key) => value[key] === undefined || finite(value[key]))
+        && ['place', 'gate', 'status'].every((key) => value[key] === undefined || typeof value[key] === 'string')
+        && (value.tone === undefined || ['neutral', 'accent', 'warning'].includes(String(value.tone)));
+}
+/** Validate the network boundary before publishing data to a card. */
+export function isAirportFeedResponse(value) {
+    if (!record(value) || value.version !== 1 || !['fresh', 'stale', 'unavailable', 'disabled'].includes(String(value.status))
+        || !finite(value.retryAfterSeconds) || value.retryAfterSeconds < 0)
+        return false;
+    if (value.status === 'disabled' || value.status === 'unavailable')
+        return value.snapshot === undefined;
+    const s = value.snapshot;
+    try {
+        if (!record(s) || !record(s.airport) || typeof s.airport.timeZone !== 'string')
+            return false;
+        new Intl.DateTimeFormat('en', { timeZone: s.airport.timeZone }).format(0);
+    }
+    catch {
+        return false;
+    }
+    return record(s) && record(s.airport)
+        && ['iata', 'name', 'city', 'timeZone'].every((key) => typeof s.airport[key] === 'string')
+        && ['fetchedAt', 'freshUntil', 'expiresAt', 'windowStart', 'windowEnd'].every((key) => finite(s[key]))
+        && Number(s.fetchedAt) <= Number(s.freshUntil) && Number(s.freshUntil) <= Number(s.expiresAt)
+        && Number(s.windowStart) < Number(s.windowEnd)
+        && Array.isArray(s.departures) && s.departures.every(movement)
+        && Array.isArray(s.arrivals) && s.arrivals.every(movement);
+}

package/domain/movement-board.d.ts

@@ -0,0 +1,21 @@
+/** All values use the study's time coordinate, in seconds (including times beyond midnight). */
+export interface MovementBoardStudy {
+    readonly time: number;
+    readonly windowStart: number;
+    readonly windowEnd: number;
+}
+export interface MovementBoardHorizon {
+    readonly lookBehindSeconds?: number;
+    readonly lookAheadSeconds?: number;
+}
+export interface MovementBoardWindow {
+    readonly start: number;
+    readonly end: number;
+}
+/** Keep recent movements briefly, then show the next hour, clipped to the selected study. */
+export declare function movementBoardWindow(study: MovementBoardStudy, { lookBehindSeconds, lookAheadSeconds }?: MovementBoardHorizon): MovementBoardWindow | undefined;
+/** Unknown times cannot be placed in a time-windowed board. Never mutate the caller's rows. */
+export declare function movementsForBoard<T extends {
+    readonly id: string;
+    readonly time?: number;
+}>(movements: readonly T[], window: MovementBoardWindow | undefined, maxRows?: number): readonly T[];

package/domain/movement-board.js

@@ -0,0 +1,23 @@
+/** Keep recent movements briefly, then show the next hour, clipped to the selected study. */
+export function movementBoardWindow(study, { lookBehindSeconds = 600, lookAheadSeconds = 3600 } = {}) {
+    const { time, windowStart, windowEnd } = study;
+    if (![time, windowStart, windowEnd, lookBehindSeconds, lookAheadSeconds].every(Number.isFinite)
+        || windowStart > windowEnd || time < windowStart || time > windowEnd
+        || lookBehindSeconds < 0 || lookAheadSeconds < 0)
+        return undefined;
+    return {
+        start: Math.max(windowStart, time - lookBehindSeconds),
+        end: Math.min(windowEnd, time + lookAheadSeconds),
+    };
+}
+/** Unknown times cannot be placed in a time-windowed board. Never mutate the caller's rows. */
+export function movementsForBoard(movements, window, maxRows = 8) {
+    if (!window || ![window.start, window.end, maxRows].every(Number.isFinite)
+        || window.start > window.end || maxRows < 1)
+        return [];
+    return movements
+        .filter((entry) => entry.time !== undefined && Number.isFinite(entry.time)
+        && entry.time >= window.start && entry.time <= window.end)
+        .sort((first, second) => first.time - second.time || (first.id < second.id ? -1 : first.id > second.id ? 1 : 0))
+        .slice(0, Math.floor(maxRows));
+}

package/domain/network-patterns.d.ts

@@ -0,0 +1,19 @@
+import type { NetworkDayChunk, NetworkTrain, ServiceCategory } from './network.ts';
+export declare const NETWORK_PATTERN_FORMAT = "network-patterns-v1";
+export type NetworkPattern = Omit<NetworkTrain, 'id' | 'start'>;
+export interface PatternNetworkChunk {
+    readonly format: string;
+    readonly windowStart: number;
+    readonly windowEnd: number;
+    readonly patterns: readonly NetworkPattern[];
+    readonly journeys: readonly (readonly [id: string, start: number, pattern: number])[];
+}
+export interface PatternChunkOptions {
+    /** A consumer may retain a previously published wire-format tag. */
+    readonly format?: string;
+    readonly categories?: readonly ServiceCategory[];
+}
+/** Deduplicate relative schedules on disk; identities and absolute calls survive decoding. */
+export declare function encodeNetworkPatterns(chunk: NetworkDayChunk, options?: PatternChunkOptions): PatternNetworkChunk;
+export declare function validateNetworkPatterns(value: unknown, options?: PatternChunkOptions): asserts value is PatternNetworkChunk;
+export declare function decodeNetworkPatterns(value: unknown, options?: PatternChunkOptions): NetworkDayChunk;

package/domain/network-patterns.js

@@ -0,0 +1,73 @@
+export const NETWORK_PATTERN_FORMAT = 'network-patterns-v1';
+/** Deduplicate relative schedules on disk; identities and absolute calls survive decoding. */
+export function encodeNetworkPatterns(chunk, options = {}) {
+    const patterns = [], indexes = new Map();
+    const journeys = chunk.trains.map(({ id, start, ...train }) => {
+        const pattern = { ...train, end: train.end - start,
+            stops: train.stops.map(([stop, arrival, departure]) => [stop, arrival - start, departure - start]),
+        };
+        const key = JSON.stringify(pattern);
+        let index = indexes.get(key);
+        if (index === undefined) {
+            index = patterns.length;
+            indexes.set(key, index);
+            patterns.push(pattern);
+        }
+        return [id, start, index];
+    });
+    const result = { format: options.format ?? NETWORK_PATTERN_FORMAT, windowStart: chunk.windowStart,
+        windowEnd: chunk.windowEnd, patterns, journeys };
+    validateNetworkPatterns(result, options);
+    return result;
+}
+export function validateNetworkPatterns(value, options = {}) {
+    const chunk = value;
+    if (!chunk || chunk.format !== (options.format ?? NETWORK_PATTERN_FORMAT) ||
+        !Number.isFinite(chunk.windowStart) || !Number.isFinite(chunk.windowEnd) || chunk.windowEnd <= chunk.windowStart ||
+        !Array.isArray(chunk.patterns) || !Array.isArray(chunk.journeys))
+        throw new Error('Invalid network pattern chunk');
+    for (const pattern of chunk.patterns) {
+        if (!pattern || !Number.isFinite(pattern.end) || pattern.end < 0 ||
+            typeof pattern.route !== 'string' || typeof pattern.headsign !== 'string' || typeof pattern.shortName !== 'string' ||
+            typeof pattern.category !== 'string' || (options.categories && !options.categories.includes(pattern.category)) ||
+            !Array.isArray(pattern.stops) || pattern.stops.length < 2)
+            throw new Error('Invalid network pattern');
+        let previous = -Infinity;
+        for (const stop of pattern.stops) {
+            if (!Array.isArray(stop) || stop.length !== 3)
+                throw new Error('Invalid pattern stop');
+            const [index, arrival, departure] = stop;
+            if (!Number.isSafeInteger(index) || index < 0 || !Number.isFinite(arrival) || !Number.isFinite(departure) ||
+                departure < arrival || arrival < previous)
+                throw new Error('Invalid pattern stop timing');
+            previous = departure;
+        }
+        if (pattern.end < previous)
+            throw new Error('Pattern ends before its final call');
+        if (pattern.pathSegments && (!Array.isArray(pattern.pathSegments) || pattern.pathSegments.length !== pattern.stops.length - 1 ||
+            pattern.pathSegments.some((index) => index !== null && (!Number.isSafeInteger(index) || index < 0))))
+            throw new Error('Invalid pattern paths');
+    }
+    const ids = new Set();
+    for (const journey of chunk.journeys) {
+        if (!Array.isArray(journey) || journey.length !== 3)
+            throw new Error('Invalid pattern journey');
+        const [id, start, index] = journey;
+        if (typeof id !== 'string' || !id || ids.has(id) || !Number.isFinite(start) || !Number.isSafeInteger(index) || index < 0 ||
+            !chunk.patterns[index] || !Number.isFinite(start + chunk.patterns[index].end) ||
+            chunk.patterns[index].stops.some((stop) => !Number.isFinite(start + stop[1]) || !Number.isFinite(start + stop[2])))
+            throw new Error('Invalid pattern journey identity or time');
+        ids.add(id);
+    }
+}
+export function decodeNetworkPatterns(value, options = {}) {
+    validateNetworkPatterns(value, options);
+    return { windowStart: value.windowStart, windowEnd: value.windowEnd,
+        trains: value.journeys.map(([id, start, index]) => {
+            const pattern = value.patterns[index];
+            return { ...pattern, id, start, end: start + pattern.end,
+                stops: pattern.stops.map(([stop, arrival, departure]) => [stop, start + arrival, start + departure]),
+            };
+        }),
+    };
+}

package/domain/network.js

@@ -69,7 +69,7 @@ export function buildStationIndex(snapshot) {
         routes: [...record.routes.values()].sort((first, second) => first.name.localeCompare(second.name, 'de-CH')),
     }));
 }
-export function positionForTrain(train, time) {
+function linearPositionForTrain(train, time) {
     if (train.realtime?.status === 'cancelled' ||
         time < train.start ||
         time > train.end ||
@@ -98,6 +98,42 @@ export function positionForTrain(train, time) {
     const last = train.stops.at(-1);
     return { fromStop: last[0], toStop: last[0], progress: 0 };
 }
+// Timetables are immutable. A replacement stop array (including realtime edits)
+// gets its own validation; old schedules can be garbage collected.
+const chronologicalSchedules = new WeakMap();
+export function positionForTrain(train, time) {
+    if (train.realtime?.status === 'cancelled' || time < train.start || time > train.end || train.stops.length < 2)
+        return;
+    const stops = train.stops;
+    let chronological = chronologicalSchedules.get(stops);
+    if (chronological === undefined) {
+        chronological = stops.every((stop, index) => Number.isFinite(stop[1]) && Number.isFinite(stop[2]) &&
+            stop[2] >= stop[1] && (index === 0 || stop[1] >= stops[index - 1][2]));
+        chronologicalSchedules.set(stops, chronological);
+    }
+    // Preserve sequential semantics for unordered observations and non-finite clocks.
+    if (!chronological || !Number.isFinite(time))
+        return linearPositionForTrain(train, time);
+    let lower = 0;
+    let upper = stops.length;
+    while (lower < upper) {
+        const middle = (lower + upper) >>> 1;
+        if (stops[middle][2] < time)
+            lower = middle + 1;
+        else
+            upper = middle;
+    }
+    const next = stops[Math.min(lower, stops.length - 1)];
+    if (lower === 0 || lower === stops.length || time > next[1]) {
+        return { fromStop: next[0], toStop: next[0], progress: 0 };
+    }
+    const previous = stops[lower - 1];
+    return {
+        fromStop: previous[0], toStop: next[0],
+        progress: Math.min(1, Math.max(0, (time - previous[2]) / Math.max(1, next[1] - previous[2]))),
+        segmentIndex: lower - 1,
+    };
+}
 export function formatServiceTime(totalSeconds) {
     const normalized = ((Math.round(totalSeconds) % 86400) + 86400) % 86400;
     const hours = Math.floor(normalized / 3600);

package/domain/published-day.d.ts

@@ -0,0 +1,132 @@
+/** A published day of the national layer, as compiled by the recording host: the sea (one file of 0.1° cells per
+ * five-minute slice), the shoal (one file per slice from cell to member vehicles), and the fish (one gzipped pack
+ * per operator per day, split into parts by sample budget), with an index from operator and vehicle to part and a
+ * manifest of every file. Everything is static; opening one vehicle fetches one pack. Readers supply the transport
+ * and, where the platform lacks DecompressionStream, the inflater; nothing here touches the network itself.
+ */
+export declare const SLICE_SECONDS = 300, CELL_DEGREES = 0.1;
+export interface PublishedDayManifest {
+    readonly date: string;
+    readonly compiledAt: string;
+    readonly hours: {
+        readonly present: readonly string[];
+        readonly missing: readonly string[];
+    };
+    readonly stats: {
+        readonly samples: number;
+        readonly vehicles: number;
+        readonly operators: number;
+        readonly slices: number;
+        readonly excludedRejected: number;
+        readonly excludedOutsideDay: number;
+    };
+    readonly slices: number;
+    readonly files: number;
+    readonly bytes: number;
+    readonly list: readonly {
+        readonly path: string;
+        readonly bytes: number;
+    }[];
+}
+/** One cell of a slice: centre-less floor coordinates, samples (which sum across cells) and distinct vehicles (which do not). */
+export type SliceCell = readonly [lon: number, lat: number, samples: number, vehicles: number];
+export interface SliceFile {
+    readonly slice: string;
+    readonly cells: readonly SliceCell[];
+}
+/** Members of each cell as operator index into the day index and vehicle reference. */
+export type Member = readonly [operatorIndex: number, vehicleRef: string];
+export interface MembersFile {
+    readonly slice: string;
+    readonly cells: Readonly<Record<string, readonly Member[]>>;
+}
+export interface PackPart {
+    readonly file: string;
+    readonly bytes: number;
+    readonly vehicles: number;
+    readonly samples: number;
+    readonly refs?: readonly string[];
+}
+export interface OperatorEntry {
+    readonly ref: string;
+    readonly vehicles: number;
+    readonly samples: number;
+    readonly parts: readonly PackPart[];
+}
+export interface DayIndex {
+    readonly date: string;
+    readonly operators: readonly OperatorEntry[];
+}
+export type TrackPoint = readonly [epochSeconds: number, lon: number, lat: number];
+export type JourneyRun = readonly [epochSeconds: number, lineRef: string | null, journeyRef: string | null];
+export interface VehicleDay {
+    readonly track: readonly TrackPoint[];
+    readonly journeys: readonly JourneyRun[];
+}
+export interface Pack {
+    readonly date: string;
+    readonly operator: string;
+    readonly part: number;
+    readonly parts: number;
+    readonly vehicles: Readonly<Record<string, VehicleDay>>;
+}
+export interface DayTransport {
+    /** Text of a file under the day's base, by its relative path. */
+    readonly text: (path: string) => Promise<string>;
+    /** Bytes of a file under the day's base. */
+    readonly bytes: (path: string) => Promise<Uint8Array>;
+    /** Gunzip; defaults to the platform's DecompressionStream. */
+    readonly inflate?: (bytes: Uint8Array) => Promise<Uint8Array>;
+}
+/** The slice file name for an instant: HH-MM of the five-minute slice containing it, UTC. */
+export declare function sliceNameAt(instant: string | number): string;
+/** The ISO start of a named slice on a date. */
+export declare function sliceStart(date: string, name: string): string;
+/** The cell a position falls in, by the compiler's own rule: floor of the coordinate over the cell size, in double
+ * arithmetic, printed to one decimal. The rule is reproduced exactly rather than rounded, so a position near a
+ * cell edge lands where the compiler put it. */
+export declare function cellOf(lon: number, lat: number): readonly [number, number];
+export declare function cellKey(cellLon: number, cellLat: number): string;
+/** The pack part holding a vehicle: the only part, or the part whose reference list names it. */
+export declare function partFor(index: DayIndex, operatorRef: string, vehicleRef: string): PackPart | null;
+/** Problems with a compiled day's manifest, empty when consistent: all 24 hours of the date accounted for once, one
+ * slice and one members file per slice, and the file list agreeing with the stated file and byte totals (the manifest
+ * itself is the one unlisted file). A trimmed fixture, whose statistics describe the whole day, fails by design. */
+export declare function checkDayManifest(manifest: PublishedDayManifest): string[];
+/** Problems reconciling a slice with its members, empty when they agree: the sea and the shoal must count the same
+ * vehicles. Each cell's distinct-vehicle count equals its distinct members, no member repeats, and neither file names
+ * a cell the other lacks. Samples are not checked here; members carry identities, not sample counts. */
+export declare function reconcileSlice(slice: SliceFile, members: MembersFile): string[];
+/** Position along a track at an instant: linear between the samples around it, null outside the track or across a
+ * gap longer than the tolerance, so a vehicle that stopped reporting does not glide. */
+export declare function positionAt(track: readonly TrackPoint[], epochSeconds: number, maxGapSeconds?: number): readonly [lon: number, lat: number] | null;
+/** The line and journey a vehicle was on at an instant, from its runs. */
+export declare function journeyAt(journeys: readonly JourneyRun[], epochSeconds: number): JourneyRun | null;
+/** Minimal shapes of the platform pieces used, so the module compiles without DOM typings. */
+interface ByteSource {
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+interface ResponseLike extends ByteSource {
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+}
+export type FetchLike = (url: string) => Promise<ResponseLike>;
+export declare function inflateGzip(bytes: Uint8Array): Promise<Uint8Array>;
+/** Packs are stored gzipped, but a server that declares the encoding hands the browser the decoded bytes; either form is accepted by its first two bytes. */
+export declare function inflateIfGzipped(bytes: Uint8Array, inflate: (bytes: Uint8Array) => Promise<Uint8Array>): Promise<Uint8Array>;
+export interface PublishedDay {
+    readonly manifest: PublishedDayManifest;
+    readonly index: DayIndex;
+    readonly slice: (name: string) => Promise<SliceFile>;
+    readonly members: (name: string) => Promise<MembersFile>;
+    readonly pack: (operatorRef: string, vehicleRef: string) => Promise<Pack>;
+    readonly vehicle: (operatorRef: string, vehicleRef: string) => Promise<VehicleDay | null>;
+    /** Slice names present, from the manifest's file list, in order. */
+    readonly sliceNames: readonly string[];
+}
+/** Open a published day: manifest and index up front, everything else on demand and cached per file. */
+export declare function openPublishedDay(transport: DayTransport): Promise<PublishedDay>;
+/** A transport over fetch for a day served under a base URL. */
+export declare function fetchTransport(base: string, fetchImpl?: FetchLike | undefined): DayTransport;
+export {};

package/domain/published-day.js

@@ -0,0 +1,162 @@
+/** A published day of the national layer, as compiled by the recording host: the sea (one file of 0.1° cells per
+ * five-minute slice), the shoal (one file per slice from cell to member vehicles), and the fish (one gzipped pack
+ * per operator per day, split into parts by sample budget), with an index from operator and vehicle to part and a
+ * manifest of every file. Everything is static; opening one vehicle fetches one pack. Readers supply the transport
+ * and, where the platform lacks DecompressionStream, the inflater; nothing here touches the network itself.
+ */
+export const SLICE_SECONDS = 300, CELL_DEGREES = 0.1;
+/** The slice file name for an instant: HH-MM of the five-minute slice containing it, UTC. */
+export function sliceNameAt(instant) {
+    const t = typeof instant === 'number' ? instant : Date.parse(instant);
+    if (!Number.isFinite(t))
+        throw new Error('Invalid instant');
+    const s = Math.floor(t / 1000 / SLICE_SECONDS) * SLICE_SECONDS, d = new Date(s * 1000);
+    return `${String(d.getUTCHours()).padStart(2, '0')}-${String(d.getUTCMinutes()).padStart(2, '0')}`;
+}
+/** The ISO start of a named slice on a date. */
+export function sliceStart(date, name) { return `${date}T${name.replace('-', ':')}:00Z`; }
+/** The cell a position falls in, by the compiler's own rule: floor of the coordinate over the cell size, in double
+ * arithmetic, printed to one decimal. The rule is reproduced exactly rather than rounded, so a position near a
+ * cell edge lands where the compiler put it. */
+export function cellOf(lon, lat) {
+    return [Number((Math.floor(lon / CELL_DEGREES) * CELL_DEGREES).toFixed(1)), Number((Math.floor(lat / CELL_DEGREES) * CELL_DEGREES).toFixed(1))];
+}
+export function cellKey(cellLon, cellLat) { return `${cellLon.toFixed(1)},${cellLat.toFixed(1)}`; }
+/** The pack part holding a vehicle: the only part, or the part whose reference list names it. */
+export function partFor(index, operatorRef, vehicleRef) {
+    const op = index.operators.find(o => o.ref === operatorRef);
+    if (!op)
+        return null;
+    if (op.parts.length === 1)
+        return op.parts[0];
+    return op.parts.find(p => p.refs?.includes(vehicleRef)) ?? null;
+}
+/** Problems with a compiled day's manifest, empty when consistent: all 24 hours of the date accounted for once, one
+ * slice and one members file per slice, and the file list agreeing with the stated file and byte totals (the manifest
+ * itself is the one unlisted file). A trimmed fixture, whose statistics describe the whole day, fails by design. */
+export function checkDayManifest(manifest) {
+    const problems = [], hours = [...manifest.hours.present, ...manifest.hours.missing], distinct = new Set(hours).size;
+    if (hours.length !== 24 || distinct !== 24)
+        problems.push(`Hours present and missing account for ${distinct} distinct of 24, listed ${hours.length} times`);
+    if (hours.some(h => !h.startsWith(`${manifest.date}T`)))
+        problems.push('An hour lies outside the manifest date');
+    const count = (prefix) => manifest.list.filter(f => f.path.startsWith(prefix)).length;
+    if (manifest.stats.slices !== manifest.slices)
+        problems.push(`Statistics count ${manifest.stats.slices} slices; the manifest ${manifest.slices}`);
+    if (count('slices/') !== manifest.slices)
+        problems.push(`${count('slices/')} slice files listed for ${manifest.slices} slices`);
+    if (count('members/') !== manifest.slices)
+        problems.push(`${count('members/')} members files listed for ${manifest.slices} slices`);
+    if (manifest.list.length + 1 !== manifest.files)
+        problems.push(`${manifest.list.length} listed files and the manifest disagree with ${manifest.files} files`);
+    const bytes = manifest.list.reduce((a, f) => a + f.bytes, 0);
+    if (bytes !== manifest.bytes)
+        problems.push(`Listed files hold ${bytes} bytes; the manifest states ${manifest.bytes}`);
+    return problems;
+}
+/** Problems reconciling a slice with its members, empty when they agree: the sea and the shoal must count the same
+ * vehicles. Each cell's distinct-vehicle count equals its distinct members, no member repeats, and neither file names
+ * a cell the other lacks. Samples are not checked here; members carry identities, not sample counts. */
+export function reconcileSlice(slice, members) {
+    if (slice.slice !== members.slice)
+        return [`Slice ${slice.slice} paired with members of ${members.slice}`];
+    const problems = [], seen = new Set();
+    for (const [lon, lat, , vehicles] of slice.cells) {
+        const key = cellKey(lon, lat), refs = members.cells[key];
+        seen.add(key);
+        if (!refs) {
+            problems.push(`Cell ${key} counts ${vehicles} vehicles and has no members`);
+            continue;
+        }
+        const unique = new Set(refs.map(member => JSON.stringify(member))).size;
+        if (unique !== refs.length)
+            problems.push(`Cell ${key} repeats a member`);
+        if (unique !== vehicles)
+            problems.push(`Cell ${key} counts ${vehicles} vehicles but lists ${unique} members`);
+    }
+    for (const key of Object.keys(members.cells))
+        if (!seen.has(key))
+            problems.push(`Members name cell ${key}, absent from the slice`);
+    return problems;
+}
+/** Position along a track at an instant: linear between the samples around it, null outside the track or across a
+ * gap longer than the tolerance, so a vehicle that stopped reporting does not glide. */
+export function positionAt(track, epochSeconds, maxGapSeconds = 180) {
+    if (!track.length || epochSeconds < track[0][0] || epochSeconds > track[track.length - 1][0])
+        return null;
+    let lo = 0, hi = track.length - 1;
+    while (hi - lo > 1) {
+        const mid = (lo + hi) >> 1;
+        if (track[mid][0] <= epochSeconds)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const a = track[lo], b = track[hi];
+    if (a[0] === epochSeconds || lo === hi)
+        return [a[1], a[2]];
+    if (b[0] === epochSeconds)
+        return [b[1], b[2]];
+    if (b[0] - a[0] > maxGapSeconds)
+        return null;
+    const f = (epochSeconds - a[0]) / (b[0] - a[0]);
+    return [a[1] + (b[1] - a[1]) * f, a[2] + (b[2] - a[2]) * f];
+}
+/** The line and journey a vehicle was on at an instant, from its runs. */
+export function journeyAt(journeys, epochSeconds) {
+    let found = null;
+    for (const run of journeys) {
+        if (run[0] <= epochSeconds)
+            found = run;
+        else
+            break;
+    }
+    return found;
+}
+const platform = globalThis;
+export async function inflateGzip(bytes) {
+    if (!platform.DecompressionStream || !platform.Blob || !platform.Response)
+        throw new Error('No DecompressionStream on this platform; supply an inflater');
+    const stream = new platform.Blob([bytes]).stream().pipeThrough(new platform.DecompressionStream('gzip'));
+    return new Uint8Array(await new platform.Response(stream).arrayBuffer());
+}
+/** Packs are stored gzipped, but a server that declares the encoding hands the browser the decoded bytes; either form is accepted by its first two bytes. */
+export async function inflateIfGzipped(bytes, inflate) {
+    return bytes.length >= 2 && bytes[0] === 0x1f && bytes[1] === 0x8b ? inflate(bytes) : bytes;
+}
+function decodeText(bytes) {
+    if (!platform.TextDecoder)
+        throw new Error('No TextDecoder on this platform');
+    return new platform.TextDecoder().decode(bytes);
+}
+/** Open a published day: manifest and index up front, everything else on demand and cached per file. */
+export async function openPublishedDay(transport) {
+    const manifest = JSON.parse(await transport.text('manifest.json'));
+    const index = JSON.parse(await transport.text('index.json'));
+    if (manifest.date !== index.date)
+        throw new Error('Manifest and index disagree on the date');
+    const cache = new Map();
+    const cached = (path, load) => { let p = cache.get(path); if (!p) {
+        p = load();
+        cache.set(path, p);
+    } return p; };
+    const inflate = transport.inflate ?? inflateGzip;
+    const sliceNames = manifest.list.filter(f => f.path.startsWith('slices/')).map(f => f.path.slice(7, -5)).sort();
+    const pack = (operatorRef, vehicleRef) => { const part = partFor(index, operatorRef, vehicleRef); if (!part)
+        return Promise.reject(new Error(`No pack for ${operatorRef} ${vehicleRef}`)); return cached(part.file, async () => JSON.parse(decodeText(await inflateIfGzipped(await transport.bytes(part.file), inflate)))); };
+    return { manifest, index, sliceNames,
+        slice: name => cached(`slices/${name}.json`, async () => JSON.parse(await transport.text(`slices/${name}.json`))),
+        members: name => cached(`members/${name}.json`, async () => JSON.parse(await transport.text(`members/${name}.json`))),
+        pack,
+        vehicle: async (operatorRef, vehicleRef) => { if (!partFor(index, operatorRef, vehicleRef))
+            return null; return (await pack(operatorRef, vehicleRef)).vehicles[vehicleRef] ?? null; } };
+}
+/** A transport over fetch for a day served under a base URL. */
+export function fetchTransport(base, fetchImpl = platform.fetch) {
+    if (!fetchImpl)
+        throw new Error('No fetch on this platform; supply one');
+    const url = (path) => `${base.replace(/\/$/, '')}/${path}`;
+    const get = async (path) => { const r = await fetchImpl(url(path)); if (!r.ok)
+        throw new Error(`${path} returned HTTP ${r.status}`); return r; };
+    return { text: async (path) => (await get(path)).text(), bytes: async (path) => new Uint8Array(await (await get(path)).arrayBuffer()) };
+}