@motionstudies/core 0.1.0-alpha.27 → 0.1.0-alpha.29

package/README.md

@@ -194,6 +194,14 @@ Consumers supply remaining `stops` in journey order and update them with playbac
 
 The required `note` explains provenance. Optional `status`, `statusTone`, `clockLabel`, localized `labels`, `loading`, `error` and `onRetry` follow the consumer's data; the component never manufactures an on-time status. Loading and errors hide the calling points. Stop selection is controlled through stable call IDs and does not alter playback or clear when a call leaves the list. All supplied calls are shown, with wrapping names and container-based compact layouts. The lab exercises advance/rewind, unknown destinations/times, localization, disruption, recovery and narrow widths. Edition adoption requires its own package upgrade and data adapter.
 
+## Feed observability
+
+`@motionstudies/data/feed-observability` validates versioned feed registries, operational events and health reports. `@motionstudies/data/recorder-observability` projects a recorder status snapshot into that shared contract, rechecking freshness against the observer's clock and omitting private paths, PIDs and raw errors. Both are pure functions with no acquisition, storage or notification side effects. The source repository's `docs/FEED-OBSERVABILITY.md` describes the read-only CLI, example registry, states and evidence limits. Registry daily schedules remain declarative; explicit dated evidence plans and incident history are available through the Node adapters below.
+
+`@motionstudies/data/recorder-evidence` reads explicit dated local journal/close-out and release targets, verifies their hashes and identities, and assesses missing expected outputs against deadlines. `@motionstudies/data/feed-incidents` persists debounced incident transitions with replay protection, atomic checksummed state, bounded retention and fail-closed capacity limits. These two modules require Node. See `docs/FEED-INCIDENTS.md` for CLI opt-in flags and operational limits; neither module installs a scheduler or sends notifications.
+
+`@motionstudies/data/release` checks versioned release handoffs in Node or a browser: safe file descriptors (`{ path, sha256, bytes }`), every descriptor in a manifest whatever its layout, kind and schema, and fetched bytes through Web Crypto. `@motionstudies/data/release-files` opens a release directory in Node, optionally pinned to its manifest digest, reads only described files without escaping the directory, and verifies a whole release within a byte budget. Format meaning stays with each format's reader. See the source repository's `docs/RELEASE-CONTRACT.md`.
+
 ## Optional live airport feed
 
 `AirportBoard` from `@motionstudies/web/components/AirportBoard` adds Study/Now controls around an existing `AirportHeroCard` configuration. Pass `studyCard` with the usual card props and `live={{ baseUrl, edition, airport }}` for the shared service. Import `airport-hero-card.css`. `labels` localizes the wrapper's control and availability messages. The lower-level `useAirportFeed` hook and core `domain/live-airport` contract are also public exports.

package/domain/published-day.d.ts

@@ -26,6 +26,7 @@ export interface PublishedDayManifest {
     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). */

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[];

package/domain/route-field.js

@@ -0,0 +1,47 @@
+/** Quiet at the baseline, growing as the ratio falls; a bin below `ring` earns a marker. Mock rule of 18 September 2026. */
+export const PEAK_SPEED_EMPHASIS = { baseline: 1, floor: 0.4, ring: 0.6, glowFrom: 0.15 };
+export function routeFieldValue(bin, minimumSupport) {
+    if (!bin || bin.value === null || !Number.isFinite(bin.value) || bin.value < 0)
+        return null;
+    return Number.isFinite(bin.support) && bin.support >= minimumSupport ? bin.value : null;
+}
+/** Null for an unsupported bin; draw it dashed, not as fine. */
+export function routeFieldEmphasis(value, rule = PEAK_SPEED_EMPHASIS) {
+    if (value === null || !Number.isFinite(value))
+        return null;
+    const span = rule.baseline - rule.floor;
+    const slow = span > 0 ? Math.min(1, Math.max(0, (rule.baseline - value) / span)) : 0;
+    return { width: 1 + 1.6 * slow, glow: slow > rule.glowFrom ? slow : 0, ring: value < rule.ring };
+}
+const EARTH_METRES_PER_DEGREE = 111_320;
+/** Cumulative metres along a longitude/latitude path on a local equirectangular plane; enough for bins of tens of metres. */
+export function pathChainage(path) {
+    const out = [0];
+    if (path.length === 0)
+        return [];
+    for (let i = 1; i < path.length; i++) {
+        const [lon0, lat0] = path[i - 1], [lon1, lat1] = path[i];
+        const scale = Math.cos(((lat0 + lat1) / 2) * Math.PI / 180);
+        out.push(out[i - 1] + Math.hypot((lon1 - lon0) * EARTH_METRES_PER_DEGREE * scale, (lat1 - lat0) * EARTH_METRES_PER_DEGREE));
+    }
+    return out;
+}
+/** Point at `metres` along the path; clamped to its ends. Returns null for an empty path. */
+export function pointAlongPath(path, chainage, metres) {
+    if (path.length === 0 || chainage.length !== path.length)
+        return null;
+    if (path.length === 1 || metres <= 0)
+        return path[0];
+    const end = chainage[chainage.length - 1];
+    if (metres >= end)
+        return path[path.length - 1];
+    let hi = 1;
+    while (chainage[hi] < metres)
+        hi++;
+    const lo = hi - 1, span = chainage[hi] - chainage[lo], f = span > 0 ? (metres - chainage[lo]) / span : 0;
+    return [path[lo][0] + (path[hi][0] - path[lo][0]) * f, path[lo][1] + (path[hi][1] - path[lo][1]) * f];
+}
+/** Bins whose extent overlaps [from,to) metres, in path order. */
+export function routeFieldBinsBetween(field, from, to) {
+    return field.bins.filter(bin => bin.to > from && bin.from < to);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/core",
-  "version": "0.1.0-alpha.27",
+  "version": "0.1.0-alpha.29",
   "private": false,
   "type": "module",
   "description": "Transport contracts and motion primitives for Motion Studies.",
@@ -205,6 +205,16 @@
       "import": "./domain/field-paths.js",
       "default": "./domain/field-paths.js"
     },
+    "./domain/route-field": {
+      "types": "./domain/route-field.d.ts",
+      "import": "./domain/route-field.js",
+      "default": "./domain/route-field.js"
+    },
+    "./domain/route-events": {
+      "types": "./domain/route-events.d.ts",
+      "import": "./domain/route-events.js",
+      "default": "./domain/route-events.js"
+    },
     "./domain/daylight": {
       "types": "./domain/daylight.d.ts",
       "import": "./domain/daylight.js",