@motionstudies/core 0.1.0-alpha.3 → 0.1.0-alpha.30

package/domain/power-day.d.ts

@@ -0,0 +1,84 @@
+/** Dated electricity evidence. All times are elapsed UTC seconds from startUtc.
+ * Settlement is interval energy (MWh); plans and national aggregates are power (MW).
+ * Geography, population selection and placement policy belong to the consuming work.
+ */
+export interface PowerSource {
+    sha256: string;
+    url: string;
+    retrievedAt: string;
+    publisher: string;
+}
+export interface PowerPlacement {
+    method: 'site' | 'connection' | 'curated' | 'aggregate' | 'interconnector' | 'unplaced';
+    latitude?: number;
+    longitude?: number;
+    note?: string | null;
+    source?: string | null;
+    score?: number;
+    matched?: Record<string, unknown>;
+}
+export interface PowerUnit {
+    id: string;
+    name: string;
+    fuelType: string | null;
+    capacityMw: number | null;
+    settledMwh: (number | null)[];
+    runs: (string | null)[];
+    /** [start, end, start MW, end MW]; half-open intervals, no extrapolation. */
+    plan: [number, number, number, number][];
+    placement?: PowerPlacement;
+    evidence?: {
+        path: string;
+        sha256: string;
+        bytes: number;
+    };
+}
+export interface PowerDay {
+    kind: 'power-day';
+    schemaVersion: 1;
+    date: string;
+    timezone: string;
+    startUtc: string;
+    endUtc: string;
+    periodSeconds: 1800;
+    quantityUnit: 'MWh';
+    powerUnit: 'MW';
+    scope: string;
+    population: string;
+    units: PowerUnit[];
+    demandMw: (number | null)[];
+    fuelMix: {
+        time: number;
+        byFuel: Record<string, number | null>;
+    }[];
+    settlementSources: string[];
+    planSources: string[];
+    sources: PowerSource[];
+    attribution: {
+        statement: string;
+        licence: string;
+    }[];
+}
+/** Validate untrusted JSON at both publication and browser boundaries. Does not fetch. */
+export declare function readPowerDay(value: unknown): PowerDay;
+export declare function powerPeriod(day: PowerDay, seconds: number): number | null;
+/** Return null for a gap or ambiguous overlapping declarations, never infer a plan. */
+export declare function plannedPower(unit: PowerUnit, seconds: number): number | null;
+export declare function unitPower(day: PowerDay, unit: PowerUnit, seconds: number): {
+    period: number | null;
+    settledMwh: number | null;
+    averageMw: number | null;
+    plannedMw: number | null;
+    run: string | null;
+};
+/** Membership is supplied by the work; report missing contributors alongside partial sums. */
+export declare function sumPower(day: PowerDay, units: readonly PowerUnit[], seconds: number): {
+    averageMw: number | null;
+    available: number;
+    missing: number;
+};
+/** Last national sample, valid for at most five minutes and never outside this day. */
+export declare function fuelMixAt(day: PowerDay, seconds: number): {
+    time: number;
+    byFuel: Record<string, number | null>;
+} | null;

package/domain/power-day.js

@@ -0,0 +1,104 @@
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+const nullable = (v) => v === null || finite(v);
+const hash = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+const nonempty = (v) => typeof v === 'string' && v.length > 0;
+const utc = (v) => typeof v === 'string' && /Z$/.test(v) && Number.isFinite(Date.parse(v));
+function requireValue(ok, message) { if (!ok)
+    throw new Error(`Invalid power day: ${message}`); }
+/** Validate untrusted JSON at both publication and browser boundaries. Does not fetch. */
+export function readPowerDay(value) {
+    requireValue(object(value), 'expected object');
+    const d = value;
+    requireValue(d.kind === 'power-day' && d.schemaVersion === 1, 'schema');
+    requireValue(nonempty(d.timezone) && typeof d.date === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(d.date), 'date/timezone');
+    requireValue(utc(d.startUtc) && utc(d.endUtc), 'UTC bounds');
+    const duration = (Date.parse(d.endUtc) - Date.parse(d.startUtc)) / 1000, periods = duration / 1800;
+    requireValue([46, 48, 50].includes(periods) && d.periodSeconds === 1800, 'civil-day intervals');
+    // A power day is a complete civil day, including both clock-change days.
+    const dateAt = (t) => new Intl.DateTimeFormat('en-CA', { timeZone: d.timezone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(t);
+    const midnight = (t) => new Intl.DateTimeFormat('en-GB', { timeZone: d.timezone, hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23' }).format(t) === '00:00:00';
+    requireValue(dateAt(Date.parse(d.startUtc)) === d.date && midnight(Date.parse(d.startUtc)) && midnight(Date.parse(d.endUtc)) && dateAt(Date.parse(d.endUtc) - 1) === d.date, 'civil date');
+    requireValue(d.quantityUnit === 'MWh' && d.powerUnit === 'MW', 'explicit units');
+    requireValue(nonempty(d.scope) && nonempty(d.population), 'scope/population');
+    requireValue(Array.isArray(d.sources) && d.sources.length > 0, 'sources');
+    const hashes = new Set();
+    for (const s of d.sources) {
+        requireValue(object(s) && hash(s.sha256) && nonempty(s.publisher) && utc(s.retrievedAt) && typeof s.url === 'string' && /^https:\/\//.test(s.url), 'source record');
+        requireValue(!hashes.has(s.sha256), 'duplicate source');
+        hashes.add(s.sha256);
+    }
+    for (const key of ['settlementSources', 'planSources'])
+        requireValue(Array.isArray(d[key]) && d[key].length === periods && d[key].every((h) => typeof h === 'string' && hashes.has(h)), `${key} linkage`);
+    requireValue(Array.isArray(d.attribution) && d.attribution.length > 0 && d.attribution.every(a => object(a) && nonempty(a.statement) && typeof a.licence === 'string' && /^https:\/\//.test(a.licence)), 'attribution');
+    requireValue(Array.isArray(d.demandMw) && d.demandMw.length === periods && d.demandMw.every(nullable), 'demand');
+    requireValue(Array.isArray(d.fuelMix), 'fuel mix');
+    let previous = -Infinity;
+    for (const f of d.fuelMix) {
+        requireValue(object(f) && finite(f.time) && f.time >= 0 && f.time < duration && f.time > previous && object(f.byFuel) && Object.values(f.byFuel).every(nullable), 'fuel mix samples');
+        previous = f.time;
+    }
+    requireValue(Array.isArray(d.units), 'units');
+    const ids = new Set();
+    for (const u of d.units) {
+        requireValue(object(u) && nonempty(u.id) && !ids.has(u.id) && nonempty(u.name), 'unit identity');
+        ids.add(u.id);
+        requireValue((u.fuelType === null || nonempty(u.fuelType)) && nullable(u.capacityMw), 'unit register');
+        requireValue(Array.isArray(u.settledMwh) && u.settledMwh.length === periods && u.settledMwh.every(nullable), 'settlement values');
+        const settledMwh = u.settledMwh;
+        requireValue(Array.isArray(u.runs) && u.runs.length === periods && u.runs.every((r, i) => settledMwh[i] === null ? r === null : ['II', 'SF', 'R1', 'R2', 'R3', 'RF', 'DF'].includes(r)), 'settlement runs');
+        requireValue(Array.isArray(u.plan) && u.plan.every(p => Array.isArray(p) && p.length === 4 && p.every(finite) && p[0] >= 0 && p[1] <= duration && p[1] > p[0]), 'declared segments');
+        if (u.placement !== undefined) {
+            const p = u.placement;
+            requireValue(object(p) && ['site', 'connection', 'curated', 'aggregate', 'interconnector', 'unplaced'].includes(String(p.method)), 'placement method');
+            const located = ['site', 'connection', 'curated'].includes(String(p.method));
+            requireValue(located ? finite(p.latitude) && Math.abs(p.latitude) <= 90 && finite(p.longitude) && Math.abs(p.longitude) <= 180 : p.latitude === undefined && p.longitude === undefined, 'placement coordinates');
+            if (p.method === 'curated')
+                requireValue(nonempty(p.source), 'curated citation');
+        }
+        if (u.evidence !== undefined) {
+            const e = u.evidence;
+            requireValue(object(e) && typeof e.path === 'string' && /^evidence\/[a-f0-9]{64}\.json$/.test(e.path) && hash(e.sha256) && Number.isSafeInteger(e.bytes) && Number(e.bytes) > 0, 'evidence artifact');
+        }
+    }
+    return value;
+}
+export function powerPeriod(day, seconds) {
+    return Number.isFinite(seconds) && seconds >= 0 && seconds < day.demandMw.length * day.periodSeconds ? Math.floor(seconds / day.periodSeconds) : null;
+}
+/** Return null for a gap or ambiguous overlapping declarations, never infer a plan. */
+export function plannedPower(unit, seconds) {
+    const segments = unit.plan.filter(p => seconds >= p[0] && seconds < p[1]);
+    if (segments.length !== 1)
+        return null;
+    const [start, end, a, b] = segments[0];
+    return a + (b - a) * (seconds - start) / (end - start);
+}
+export function unitPower(day, unit, seconds) {
+    const period = powerPeriod(day, seconds), mwh = period === null ? null : unit.settledMwh[period];
+    return { period, settledMwh: mwh, averageMw: mwh === null ? null : mwh * 3600 / day.periodSeconds, plannedMw: period === null ? null : plannedPower(unit, seconds), run: period === null ? null : unit.runs[period] };
+}
+/** Membership is supplied by the work; report missing contributors alongside partial sums. */
+export function sumPower(day, units, seconds) {
+    let averageMw = 0, available = 0;
+    for (const unit of units) {
+        const value = unitPower(day, unit, seconds).averageMw;
+        if (value !== null) {
+            averageMw += value;
+            available++;
+        }
+    }
+    return { averageMw: available ? averageMw : null, available, missing: units.length - available };
+}
+/** Last national sample, valid for at most five minutes and never outside this day. */
+export function fuelMixAt(day, seconds) {
+    if (powerPeriod(day, seconds) === null)
+        return null;
+    let sample;
+    for (let i = day.fuelMix.length - 1; i >= 0; i--)
+        if (day.fuelMix[i].time <= seconds) {
+            sample = day.fuelMix[i];
+            break;
+        }
+    return sample && seconds - sample.time < 300 ? sample : null;
+}

package/domain/published-day.d.ts

@@ -0,0 +1,133 @@
+/** 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;
+        readonly sha256?: string;
+    }[];
+}
+/** 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()) };
+}

package/domain/route-events.d.ts

@@ -0,0 +1,70 @@
+/** Off-route runs are stretches of recorded positions more than a stated distance from a journey's own matched
+ * pattern path. Events cluster runs by place and time within one service day. A persistent place holds runs on
+ * every analysed day across most of the day: a long-running diversion or published geometry that disagrees with
+ * the road, which detection alone cannot tell apart. Explanations are joined from a disruption source and
+ * remain the publisher's statement, not a verified cause.
+ */
+export interface OffRouteRun {
+    readonly line: string;
+    readonly vehicle: string;
+    readonly aimedDeparture: string;
+    readonly patternId: string | null;
+    readonly start: number;
+    readonly end: number;
+    readonly maxOffRouteMetres: number;
+    readonly between: readonly [from: string, to: string];
+    readonly track: readonly (readonly [longitude: number, latitude: number, time: number])[];
+}
+export interface RouteEventExplanation {
+    readonly source: 'siri-sx' | 'street-manager' | 'local-knowledge';
+    readonly reference: string;
+    readonly summary: string;
+    readonly planned: boolean | null;
+    readonly validity: {
+        readonly start: string;
+        readonly end: string | null;
+    };
+    readonly lines: readonly string[];
+}
+export interface RouteEvent {
+    readonly id: string;
+    readonly serviceDate: string;
+    /** Service-day seconds, matching the scene clock. */
+    readonly start: number;
+    readonly end: number;
+    readonly startAt: string;
+    readonly endAt: string;
+    readonly lines: readonly string[];
+    readonly journeys: number;
+    readonly runs: readonly OffRouteRun[];
+    readonly centroid: readonly [longitude: number, latitude: number];
+    readonly maxOffRouteMetres: number;
+    readonly recurs: boolean;
+    readonly explanations: readonly RouteEventExplanation[];
+}
+export interface PersistentPlace {
+    readonly id: string;
+    readonly centroid: readonly [longitude: number, latitude: number];
+    readonly days: readonly string[];
+    readonly lines: readonly string[];
+    readonly runs: number;
+    readonly explanations: readonly RouteEventExplanation[];
+}
+export interface RouteEventPresenceRule {
+    readonly leadSeconds: number;
+    readonly fadeSeconds: number;
+}
+export declare const DEFAULT_EVENT_PRESENCE: RouteEventPresenceRule;
+/** 0 before the lead-in, 1 through the event, fading to 0 after it. Lets a scrubbed day show an event appearing and healing. */
+export declare function eventPresenceAt(event: Pick<RouteEvent, 'start' | 'end'>, time: number, rule?: RouteEventPresenceRule): number;
+export declare function eventsPresentAt<T extends Pick<RouteEvent, 'start' | 'end'>>(events: readonly T[], time: number, rule?: RouteEventPresenceRule): readonly {
+    readonly event: T;
+    readonly presence: number;
+}[];
+/** Width grows with journeys and saturates; single excursions stay thin. */
+export declare function eventEmphasis(event: Pick<RouteEvent, 'journeys'>): {
+    readonly width: number;
+    readonly labelled: boolean;
+};
+/** Explanations whose validity covers the event's window, by ISO instant; an open end counts as still valid. */
+export declare function explanationsCovering(explanations: readonly RouteEventExplanation[], event: Pick<RouteEvent, 'startAt' | 'endAt'>): readonly RouteEventExplanation[];

package/domain/route-events.js

@@ -0,0 +1,38 @@
+export const DEFAULT_EVENT_PRESENCE = { leadSeconds: 600, fadeSeconds: 1800 };
+/** 0 before the lead-in, 1 through the event, fading to 0 after it. Lets a scrubbed day show an event appearing and healing. */
+export function eventPresenceAt(event, time, rule = DEFAULT_EVENT_PRESENCE) {
+    if (!Number.isFinite(time) || event.end < event.start)
+        return 0;
+    if (time < event.start) {
+        const lead = rule.leadSeconds;
+        return lead > 0 && time > event.start - lead ? (time - (event.start - lead)) / lead : 0;
+    }
+    if (time <= event.end)
+        return 1;
+    const fade = rule.fadeSeconds;
+    return fade > 0 && time < event.end + fade ? 1 - (time - event.end) / fade : 0;
+}
+export function eventsPresentAt(events, time, rule = DEFAULT_EVENT_PRESENCE) {
+    const out = [];
+    for (const event of events) {
+        const presence = eventPresenceAt(event, time, rule);
+        if (presence > 0)
+            out.push({ event, presence });
+    }
+    return out.sort((a, b) => b.presence - a.presence || a.event.start - b.event.start);
+}
+/** Width grows with journeys and saturates; single excursions stay thin. */
+export function eventEmphasis(event) {
+    const journeys = Math.max(0, Math.floor(event.journeys));
+    return journeys < 3 ? { width: 0.6, labelled: false } : { width: 1 + 0.18 * Math.min(journeys, 20), labelled: true };
+}
+/** Explanations whose validity covers the event's window, by ISO instant; an open end counts as still valid. */
+export function explanationsCovering(explanations, event) {
+    const start = Date.parse(event.startAt), end = Date.parse(event.endAt);
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        return [];
+    return explanations.filter(x => {
+        const from = Date.parse(x.validity.start), to = x.validity.end === null ? Infinity : Date.parse(x.validity.end);
+        return Number.isFinite(from) && !Number.isNaN(to) && from <= end && to >= start;
+    });
+}

package/domain/route-field.d.ts

@@ -0,0 +1,53 @@
+/** A route field is a per-pattern series of bins along a published road path, each holding a ratio of medians
+ * over many journeys (peak over off-peak speed, observed over scheduled running time). Values describe the
+ * pattern across the stated days and hours, never a single journey, and support counts the sampled intervals
+ * that reached the bin. Bins without enough support stay null rather than borrowing a neighbour.
+ */
+export type RouteFieldMetric = 'peak-over-off-peak-speed' | 'observed-over-scheduled-running-time';
+export interface RouteFieldBin {
+    readonly from: number;
+    readonly to: number;
+    readonly value: number | null;
+    readonly support: number;
+}
+export interface RouteFieldPeriod {
+    readonly days: readonly string[];
+    readonly hours: readonly (readonly [from: number, to: number])[];
+}
+export interface RouteField {
+    readonly id: string;
+    readonly line: string;
+    readonly patternId: string;
+    readonly direction: string;
+    readonly metric: RouteFieldMetric;
+    readonly binMetres: number;
+    readonly minimumSupport: number;
+    readonly compared: {
+        readonly subject: RouteFieldPeriod;
+        readonly baseline: RouteFieldPeriod;
+    };
+    readonly path: readonly (readonly [longitude: number, latitude: number])[];
+    readonly bins: readonly RouteFieldBin[];
+}
+export interface RouteFieldEmphasis {
+    readonly width: number;
+    readonly glow: number;
+    readonly ring: boolean;
+}
+export interface RouteFieldEmphasisRule {
+    readonly baseline: number;
+    readonly floor: number;
+    readonly ring: number;
+    readonly glowFrom: number;
+}
+/** Quiet at the baseline, growing as the ratio falls; a bin below `ring` earns a marker. Mock rule of 18 September 2026. */
+export declare const PEAK_SPEED_EMPHASIS: RouteFieldEmphasisRule;
+export declare function routeFieldValue(bin: RouteFieldBin | undefined, minimumSupport: number): number | null;
+/** Null for an unsupported bin; draw it dashed, not as fine. */
+export declare function routeFieldEmphasis(value: number | null, rule?: RouteFieldEmphasisRule): RouteFieldEmphasis | null;
+/** Cumulative metres along a longitude/latitude path on a local equirectangular plane; enough for bins of tens of metres. */
+export declare function pathChainage(path: readonly (readonly [longitude: number, latitude: number])[]): readonly number[];
+/** Point at `metres` along the path; clamped to its ends. Returns null for an empty path. */
+export declare function pointAlongPath(path: readonly (readonly [longitude: number, latitude: number])[], chainage: readonly number[], metres: number): readonly [longitude: number, latitude: number] | null;
+/** Bins whose extent overlaps [from,to) metres, in path order. */
+export declare function routeFieldBinsBetween(field: RouteField, from: number, to: number): readonly RouteFieldBin[];