@motionstudies/core 0.1.0-alpha.23 → 0.1.0-alpha.24

package/air-continents.d.ts

@@ -0,0 +1,63 @@
+/** Geographic continents from the airport reference; EU is not European Union membership. */
+export declare const AIR_CONTINENTS: {
+    readonly AF: 'Africa';
+    readonly AN: 'Antarctica';
+    readonly AS: 'Asia';
+    readonly EU: 'Europe';
+    readonly NA: 'North America';
+    readonly OC: 'Oceania';
+    readonly SA: 'South America';
+};
+export type AirContinent = keyof typeof AIR_CONTINENTS;
+export type AirContinentSource = 'ourairports' | 'override';
+export type AirContinentStatus = 'known' | 'unknown-endpoint' | 'unknown-continent';
+export interface AirContinentLabel {
+    readonly continent: AirContinent | null;
+    readonly status: AirContinentStatus;
+}
+export declare function isAirContinent(value: unknown): value is AirContinent;
+/** Older releases and unobserved endpoints remain explicitly unknown. */
+export declare function classifyAirEndpoint(endpoint?: {
+    readonly continent?: unknown;
+} | null): AirContinentLabel;
+/** Pass the canonical track index, never overlapping playback chunks. Counts are track segments, not flights. */
+export declare function summarizeAirContinents(tracks: Iterable<{
+    readonly origin?: {
+        readonly continent?: unknown;
+    };
+    readonly destination?: {
+        readonly continent?: unknown;
+    };
+}>): {
+    trackSegments: number;
+    origin: {
+        known: number;
+        unknownEndpoint: number;
+        unknownContinent: number;
+        continents: {
+            AF: number;
+            AN: number;
+            AS: number;
+            EU: number;
+            NA: number;
+            OC: number;
+            SA: number;
+        };
+        knownFraction: number | null;
+    };
+    destination: {
+        known: number;
+        unknownEndpoint: number;
+        unknownContinent: number;
+        continents: {
+            AF: number;
+            AN: number;
+            AS: number;
+            EU: number;
+            NA: number;
+            OC: number;
+            SA: number;
+        };
+        knownFraction: number | null;
+    };
+};

package/air-continents.js

@@ -0,0 +1,43 @@
+/** Geographic continents from the airport reference; EU is not European Union membership. */
+export const AIR_CONTINENTS = {
+    AF: 'Africa', AN: 'Antarctica', AS: 'Asia', EU: 'Europe',
+    NA: 'North America', OC: 'Oceania', SA: 'South America',
+};
+export function isAirContinent(value) {
+    return typeof value === 'string' && Object.hasOwn(AIR_CONTINENTS, value);
+}
+/** Older releases and unobserved endpoints remain explicitly unknown. */
+export function classifyAirEndpoint(endpoint) {
+    if (!endpoint)
+        return { continent: null, status: 'unknown-endpoint' };
+    if (!isAirContinent(endpoint.continent))
+        return { continent: null, status: 'unknown-continent' };
+    return { continent: endpoint.continent, status: 'known' };
+}
+/** Pass the canonical track index, never overlapping playback chunks. Counts are track segments, not flights. */
+export function summarizeAirContinents(tracks) {
+    const empty = () => ({
+        known: 0, unknownEndpoint: 0, unknownContinent: 0,
+        continents: { AF: 0, AN: 0, AS: 0, EU: 0, NA: 0, OC: 0, SA: 0 },
+    });
+    const counts = { origin: empty(), destination: empty() };
+    let trackSegments = 0;
+    for (const track of tracks) {
+        trackSegments++;
+        for (const side of ['origin', 'destination']) {
+            const label = classifyAirEndpoint(track[side]), count = counts[side];
+            if (label.continent) {
+                count.known++;
+                count.continents[label.continent]++;
+            }
+            else if (label.status === 'unknown-endpoint')
+                count.unknownEndpoint++;
+            else
+                count.unknownContinent++;
+        }
+    }
+    const coverage = (side) => ({
+        ...counts[side], knownFraction: trackSegments ? counts[side].known / trackSegments : null,
+    });
+    return { trackSegments, origin: coverage('origin'), destination: coverage('destination') };
+}

package/domain/air.d.ts

@@ -1,3 +1,4 @@
+import type { AirContinent, AirContinentSource } from '../air-continents.ts';
 export type AirSample = readonly [
     time: number,
     longitude: number,
@@ -13,6 +14,9 @@ export interface AirEndpoint {
     /** Study-local seconds at the observed approach/departure boundary; not a scheduled time. */
     readonly time: number;
     readonly evidence: 'observed-endpoint';
+    /** Airport geography, separate from the inferred route evidence. Absent in older releases. */
+    readonly continent?: AirContinent;
+    readonly continentSource?: AirContinentSource;
 }
 export interface AirTrack {
     readonly id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/core",
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.24",
   "private": false,
   "type": "module",
   "description": "Transport contracts and motion primitives for Motion Studies.",
@@ -20,6 +20,11 @@
     "tag": "next"
   },
   "exports": {
+    "./air-continents": {
+      "types": "./air-continents.d.ts",
+      "import": "./air-continents.js",
+      "default": "./air-continents.js"
+    },
     "./air-search": {
       "types": "./air-search.d.ts",
       "import": "./air-search.js",