@motionstudies/core 0.1.0-alpha.12 → 0.1.0-alpha.14

package/README.md

@@ -25,6 +25,14 @@ Build release candidates with `npm run build:packages`. Distribution manifests a
 
 Source workspace manifests always stay private. `npm run check:release` builds public candidates, tests their packed consumer and records the tested tarball hashes; `npm run release:dry-run` inspects the publication without writing to npm. The manual main-branch `release.yml` workflow publishes those same tarballs with public access and provenance. See [release instructions](https://github.com/emmettl/motionstudies/blob/main/docs/RELEASING.md) for bootstrap-token and trusted-publisher setup. All four shared packages are MIT-licensed; each distribution includes `LICENSE`.
 
+## Timetable patterns, station calls and observation windows
+
+`@motionstudies/core/domain/network-patterns` provides a transport-neutral repeated-schedule codec. `@motionstudies/web/use-pattern-network-day` lazily decodes current/adjacent chunks after verifying byte length and SHA-256; it exposes retry and drops old-source state when the manifest URL changes. Supply stable options and a stable asset resolver. Format/category options support existing edition wire contracts.
+
+`@motionstudies/core/domain/station-calls` supplies station calls, independent source status, namespaced source combination and upcoming-call filtering. Source IDs, repeated visits and acquired windows survive combination. Consumers supply interchange IDs and passenger restrictions; matching display names do not collapse services.
+
+`@motionstudies/data/observation-windows` compiles bounded acquired records into hashed windows with explicit time semantics, conflict policy and acquisition-gap reporting. It preserves supplied record IDs, values and source references. It uses elapsed UTC seconds, including 23/25-hour study days, and performs no acquisition or inference. See [contracts, limits and parity evidence](../docs/ALLCHANGE-FOUNDATIONS.md).
+
 ## Now and browser location
 
 `useNowClock` from `@motionstudies/web/use-now-clock` follows the wall clock on each animation frame, so returning from a suspended tab catches up immediately. Call `start()` from a Now button, set the consumer's playback rate to 1, and render its `time` while `active`. With `NationalNetworkScene`, pass `isPlaying={false}` while this external clock owns time. Call `stop()` before pausing, seeking or changing speed, and retain the last clock time for ordinary playback. Clear moving vehicle selections on entry to keep the camera still; panning and zooming remain available.
@@ -217,3 +225,7 @@ The renderer now shares active GPU upload ranges, paused frame reuse, label and
 Edition chunk scripts can call `runNetworkChunkCli()` from `@motionstudies/data/network-chunk-cli`. It accepts the existing `--input`, `--manifest`, `--opening`, `--chunk-hours`, `--opening-start`, `--opening-end`, and `--focus` arguments. Source acquisition, provenance, output paths and command invocation remain edition-owned.
 
 For timetable-backed vehicle selections, `NetworkVehicleHeroCard` from `@motionstudies/web/components/NetworkVehicleHeroCard` accepts `snapshot`, `train`, playback `time`, a required source `note` and the vehicle card's presentation/state/label options. Import `vehicle-hero-card.css`. It resolves the selected train ID against the current snapshot, retaining destination identity but showing no stale calls when that ID is absent. Calls stay in journey order, use stable journey/call IDs and follow backward seeking. During dwell the heading becomes `atStopLabel` (default “At stop”) and the time is the departure; otherwise it is the upcoming arrival. Times are formatted with `formatServiceTime` by default, without normalizing after midnight or adding delay twice. Use `showTimes={false}` for frequency-modelled journeys, and explain the model in `note`. The core `vehicleCalls` helper is also exported from `@motionstudies/core/domain/vehicle-calls` for custom adapters. Selection callback IDs refer to calls, not station indexes.
+
+### Railway preparation
+
+`@motionstudies/data/rail-wtt`, `rail-journeys`, `rail-public-calls`, `rail-routing` and `rail-geometry` expose typed offline railway preparation. XLSX reading, dated source-column audits, UID/date joins, public-call anchors and connected OSM paths preserve source evidence. Editions supply regional identities, calendar exceptions and clipping policy. Node 24+ and `unzip` are required; no Python runtime is shipped. See `docs/SHARED-RAIL-READERS.md` in the source repository for calendar limits and parity evidence.

package/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/station-calls.d.ts

@@ -0,0 +1,48 @@
+import type { NetworkSnapshot, NetworkTrain } from './network.ts';
+export type StationCallDirection = 'arrival' | 'departure';
+export interface StationCall {
+    readonly id: string;
+    readonly train: NetworkTrain;
+    /** Call occurrence within this train, not a global station index. */
+    readonly index: number;
+    readonly arrival: number;
+    readonly departure: number;
+    readonly origin: string;
+    readonly destination: string;
+    readonly allowsArrival: boolean;
+    readonly allowsDeparture: boolean;
+    readonly movementAvailable?: boolean;
+    readonly source?: string;
+    readonly windowStart?: number;
+    readonly windowEnd?: number;
+}
+export interface StationCallSelection {
+    readonly name: string;
+    /** When supplied, source IDs are authoritative; never fall back to a name match. */
+    readonly stopIds?: readonly string[];
+}
+export interface StationCallPolicy {
+    readonly includeTrain?: (train: NetworkTrain) => boolean;
+    readonly allows?: (train: NetworkTrain, callIndex: number, direction: StationCallDirection) => boolean;
+    readonly origin?: (train: NetworkTrain, snapshot: NetworkSnapshot) => string | undefined;
+    readonly destination?: (train: NetworkTrain, snapshot: NetworkSnapshot) => string | undefined;
+}
+/** Retain repeated visits and source-local indexes; passenger restrictions belong to the adapter. */
+export declare function stationCalls(snapshot: NetworkSnapshot, selection: StationCallSelection, policy?: StationCallPolicy): readonly StationCall[];
+export interface StationCallSource {
+    readonly id: string;
+    readonly selection: StationCallSelection;
+    readonly snapshot?: NetworkSnapshot;
+    readonly movements?: NetworkSnapshot;
+    readonly windowStart: number;
+    readonly windowEnd: number;
+    readonly policy?: StationCallPolicy;
+    readonly loading?: boolean;
+    readonly error?: boolean;
+}
+export type StationSourceStatus = 'loading' | 'error' | 'unavailable' | 'date-mismatch' | 'partial' | 'ready';
+export declare function stationSourceStatus(source: StationCallSource, serviceDate: string, requestedStart: number, requestedEnd: number): StationSourceStatus;
+/** Sources remain independently dated and retryable. Equal names/times never merge services. */
+export declare function combinedStationCalls(serviceDate: string, sources: readonly StationCallSource[]): readonly StationCall[];
+/** Clip to both requested and source windows. Never wrap to an unacquired day. */
+export declare function upcomingStationCalls(calls: readonly StationCall[], direction: StationCallDirection, time: number, windowStart: number, windowEnd: number, route?: string, maxRows?: number): readonly StationCall[];

package/domain/station-calls.js

@@ -0,0 +1,73 @@
+/** Retain repeated visits and source-local indexes; passenger restrictions belong to the adapter. */
+export function stationCalls(snapshot, selection, policy = {}) {
+    const stops = new Set(snapshot.stops.flatMap((stop, index) => (selection.stopIds ? Boolean(stop[4] && selection.stopIds.includes(stop[4])) : stop[2] === selection.name) ? [index] : []));
+    const calls = [], ids = new Map();
+    for (const train of snapshot.trains) {
+        if (policy.includeTrain && !policy.includeTrain(train))
+            continue;
+        const prior = ids.get(train.id);
+        if (prior) {
+            if (prior === train || JSON.stringify(prior) === JSON.stringify(train))
+                continue;
+            throw new Error('Ambiguous duplicate journey identity in station source');
+        }
+        ids.set(train.id, train);
+        train.stops.forEach(([stop, arrival, departure], index) => {
+            if (!stops.has(stop) || !Number.isFinite(arrival) || !Number.isFinite(departure) || departure < arrival)
+                return;
+            const allowsArrival = index > 0 && (policy.allows?.(train, index, 'arrival') ?? true);
+            const allowsDeparture = index < train.stops.length - 1 && (policy.allows?.(train, index, 'departure') ?? true);
+            if (!allowsArrival && !allowsDeparture)
+                return;
+            calls.push({ id: `${train.id}:call:${index}`, train, index, arrival, departure,
+                origin: policy.origin?.(train, snapshot) ?? snapshot.stops[train.stops[0][0]]?.[2] ?? '',
+                destination: policy.destination?.(train, snapshot) ?? (train.headsign || snapshot.stops[train.stops.at(-1)[0]]?.[2] || ''),
+                allowsArrival, allowsDeparture, });
+        });
+    }
+    return calls;
+}
+export function stationSourceStatus(source, serviceDate, requestedStart, requestedEnd) {
+    if (source.error)
+        return 'error';
+    if (source.loading)
+        return 'loading';
+    if (!source.snapshot || ![source.windowStart, source.windowEnd, requestedStart, requestedEnd].every(Number.isFinite) ||
+        source.windowEnd <= source.windowStart || requestedEnd < requestedStart)
+        return 'unavailable';
+    if (source.snapshot.metadata.serviceDate !== serviceDate)
+        return 'date-mismatch';
+    return source.windowStart > requestedStart || source.windowEnd < requestedEnd ? 'partial' : 'ready';
+}
+/** Sources remain independently dated and retryable. Equal names/times never merge services. */
+export function combinedStationCalls(serviceDate, sources) {
+    const result = [], ids = new Set();
+    for (const source of sources) {
+        if (!source.id || ids.has(source.id))
+            throw new Error('Station sources require distinct identities');
+        ids.add(source.id);
+        if (!source.snapshot || source.error || source.loading || source.snapshot.metadata.serviceDate !== serviceDate ||
+            !Number.isFinite(source.windowStart) || !Number.isFinite(source.windowEnd) || source.windowEnd <= source.windowStart)
+            continue;
+        const movementIds = source.movements?.metadata.serviceDate === serviceDate
+            ? new Set(source.movements.trains.map(train => train.id)) : undefined;
+        for (const call of stationCalls(source.snapshot, source.selection, source.policy)) {
+            result.push({ ...call, id: `${encodeURIComponent(source.id)}:${call.id}`, source: source.id,
+                movementAvailable: source.movements ? (movementIds?.has(call.train.id) ?? false) : undefined,
+                windowStart: source.windowStart, windowEnd: source.windowEnd,
+            });
+        }
+    }
+    return result;
+}
+/** Clip to both requested and source windows. Never wrap to an unacquired day. */
+export function upcomingStationCalls(calls, direction, time, windowStart, windowEnd, route = '', maxRows = 4) {
+    if (![time, windowStart, windowEnd].every(Number.isFinite) || time < windowStart || time >= windowEnd || !Number.isSafeInteger(maxRows) || maxRows < 1)
+        return [];
+    const end = Math.min(windowEnd, time + 3600);
+    return calls.filter(call => (direction === 'arrival' ? call.allowsArrival : call.allowsDeparture)
+        && call[direction] >= Math.max(windowStart, call.windowStart ?? windowStart)
+        && call[direction] < Math.min(windowEnd, call.windowEnd ?? windowEnd)
+        && (!route || call.train.route === route) && call[direction] >= time && call[direction] < end)
+        .sort((a, b) => a[direction] - b[direction] || a.id.localeCompare(b.id)).slice(0, maxRows);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/core",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.14",
   "private": false,
   "type": "module",
   "description": "Transport contracts and motion primitives for Motion Studies.",
@@ -105,6 +105,16 @@
       "import": "./domain/network-day.js",
       "default": "./domain/network-day.js"
     },
+    "./domain/network-patterns": {
+      "types": "./domain/network-patterns.d.ts",
+      "import": "./domain/network-patterns.js",
+      "default": "./domain/network-patterns.js"
+    },
+    "./domain/station-calls": {
+      "types": "./domain/station-calls.d.ts",
+      "import": "./domain/station-calls.js",
+      "default": "./domain/station-calls.js"
+    },
     "./domain/network-layers": {
       "types": "./domain/network-layers.d.ts",
       "import": "./domain/network-layers.js",