@faclon-labs/app-sdk 0.1.0 → 0.2.0

package/vendor/map-engine/testing/contracts.js

@@ -0,0 +1,328 @@
+/**
+ * Contract suites (doc §66): the rules every provider, renderer and spatial index must keep, written once and run
+ * against each implementation. They are plain checks — no test framework — so any runner can use them:
+ *
+ *   for (const c of providerContract({ create, sample })) it(c.name, c.run);
+ *
+ * A failing check throws a ContractViolation that names the rule.
+ */
+import { isAbortError } from '../core/errors.js';
+import { hasCatalog } from '../data/contracts.js';
+import { geometryBounds, validateGeometry, validatePosition } from '../spatial/geometry.js';
+import { intersectsBounds } from '../spatial/operations.js';
+export class ContractViolation extends Error {
+    name = 'ContractViolation';
+}
+function must(condition, message) {
+    if (!condition)
+        throw new ContractViolation(message);
+}
+const check = (name, run) => ({ name, run: async () => run() });
+const isRealtime = (p) => typeof p.subscribe === 'function';
+const isTrack = (p) => typeof p.getTracks === 'function';
+function validObjects(list, where) {
+    must(Array.isArray(list), `${where} must resolve to an array`);
+    const ids = new Set();
+    for (const o of list) {
+        must(o && typeof o.objectId === 'string' && o.objectId !== '', `${where}: every object needs a non-empty string objectId`);
+        must(!ids.has(o.objectId), `${where}: objectId ${o.objectId} appears twice`);
+        ids.add(o.objectId);
+        const g = validateGeometry(o.geometry);
+        must(g.valid, `${where}: object ${o.objectId} has invalid geometry (${g.valid ? '' : g.reason})`);
+        must(o.observedAt === undefined || Number.isFinite(Date.parse(o.observedAt)), `${where}: object ${o.objectId} observedAt is not an ISO time`);
+    }
+    return list;
+}
+/**
+ * The SpatialDataProvider contract (doc §26, ADR-005). Providers may return MORE than a query asks for (the runtime
+ * re-checks every object), but never less: a matching object must not be left out.
+ */
+export function providerContract(o) {
+    const { sample } = o;
+    const scope = sample.ontologyType ? { ontologyType: sample.ontologyType } : { objectIds: [sample.objectId] };
+    const find = async (p, q) => validObjects(await p.query(q), 'query()').find((x) => x.objectId === sample.objectId);
+    const checks = [
+        check('provider: query returns valid objects with unique ids, including the sample', async () => {
+            must(await find(o.create(), scope), `query(${JSON.stringify(scope)}) left out the sample ${sample.objectId}`);
+        }),
+        check('provider: never leaves out a matching object when every filter is set', async () => {
+            const p = o.create();
+            const first = await find(p, scope);
+            must(first, 'sample not found');
+            const b = geometryBounds(first.geometry);
+            const pad = 0.01;
+            const q = {
+                ...scope,
+                objectIds: [sample.objectId],
+                bounds: { west: b.west - pad, south: b.south - pad, east: b.east + pad, north: b.north + pad },
+                zoom: 12,
+                ...(sample.property ? { where: [{ property: sample.property.name, op: 'eq', value: sample.property.value }], filter: { [sample.property.name]: sample.property.value } } : {}),
+            };
+            must(await find(p, q), `query(${JSON.stringify(q)}) left out the sample it matches`);
+        }),
+        check('provider: honours bounds when it claims spatial query support', async () => {
+            const p = o.create();
+            if (!p.capabilities.supportsSpatialQuery || !o.outside)
+                return;
+            must(!(await find(p, { ...scope, bounds: o.outside })), 'supportsSpatialQuery is true but an object outside the bounds was returned');
+        }),
+        check('provider: rejects an aborted query with an AbortError', async () => {
+            const p = o.create();
+            await p.query(scope); // warm caches: an aborted call must reject even when it could answer from memory
+            const c = new AbortController();
+            c.abort();
+            let error = null;
+            try {
+                await p.query(scope, c.signal);
+            }
+            catch (e) {
+                error = e;
+            }
+            must(error !== null, 'query() resolved although its signal was already aborted');
+            must(isAbortError(error), `an aborted query must reject with an AbortError, got ${String(error)}`);
+        }),
+        check('provider: leaves the caller’s query unchanged', async () => {
+            const q = { ...scope, where: [{ property: 'x', op: 'exists' }], bounds: { west: -180, south: -85, east: 180, north: 85 } };
+            const before = JSON.stringify(q);
+            await o.create().query(q);
+            must(JSON.stringify(q) === before, 'query() changed the query object it was given');
+        }),
+        check('provider: returns copies (changing a result does not change the next one)', async () => {
+            const p = o.create();
+            const a = await find(p, scope);
+            must(a, 'sample not found');
+            // Change it in place, as a careless caller would: properties and geometry.
+            if (a.properties)
+                a.properties.__contract = 'mutated';
+            if (a.geometry.type === 'Point')
+                a.geometry.coordinates.latitude = -89;
+            const b = await find(p, scope);
+            must(b, 'sample not found the second time');
+            must(b.properties?.__contract === undefined, 'a later query returned properties changed by the caller');
+            must(b.geometry.type !== 'Point' || b.geometry.coordinates.latitude !== -89, 'a later query returned a geometry changed by the caller');
+        }),
+        check('provider: getCurrentState returns known ids and skips unknown ones', async () => {
+            const list = validObjects(await o.create().getCurrentState([sample.objectId, '__contract_unknown__']), 'getCurrentState()');
+            must(list.some((x) => x.objectId === sample.objectId), 'getCurrentState left out a known id');
+            must(!list.some((x) => x.objectId === '__contract_unknown__'), 'getCurrentState returned an id that does not exist');
+        }),
+    ];
+    const probe = o.create();
+    if (isRealtime(probe)) {
+        checks.push(check('realtime: subscribe returns an unsubscribe that can be called twice', () => {
+            const p = o.create();
+            const off = p.subscribe(scope, () => { });
+            must(typeof off === 'function', 'subscribe must return a function');
+            off();
+            off();
+        }));
+    }
+    if (isTrack(probe) && o.history) {
+        const range = o.history;
+        checks.push(check('history: tracks have time-ordered, valid points inside the range', async () => {
+            const tracks = await o.create().getTracks({ ...scope, geometryType: 'Point' }, range);
+            must(Array.isArray(tracks), 'getTracks must resolve to an array');
+            const ids = new Set();
+            const start = Date.parse(range.start);
+            const end = Date.parse(range.end);
+            for (const t of tracks) {
+                must(!ids.has(t.objectId), `track ${t.objectId} appears twice`);
+                ids.add(t.objectId);
+                let last = -Infinity;
+                for (const pt of t.points) {
+                    const ms = Date.parse(pt.timestamp);
+                    must(Number.isFinite(ms), `track ${t.objectId}: timestamp ${pt.timestamp} is not an ISO time`);
+                    must(ms >= last, `track ${t.objectId}: points are not in time order`);
+                    must(ms >= start && ms <= end, `track ${t.objectId}: point ${pt.timestamp} is outside the range`);
+                    must(validatePosition(pt).valid, `track ${t.objectId}: point ${pt.timestamp} has an invalid position`);
+                    last = ms;
+                }
+            }
+            must(tracks.some((t) => t.objectId === sample.objectId && t.points.length > 0), `no history for the sample ${sample.objectId} in the range`);
+        }));
+    }
+    if (hasCatalog(probe)) {
+        checks.push(check('catalog: datasets describe type, geometry family, count and properties', async () => {
+            const list = await o.create().listDatasets();
+            must(Array.isArray(list), 'listDatasets must resolve to an array');
+            for (const d of list) {
+                must(typeof d.ontologyType === 'string' && d.ontologyType !== '', 'every dataset needs an ontologyType');
+                must(['point', 'line', 'area', 'mixed'].includes(d.geometryFamily), `dataset ${String(d.ontologyType)}: geometryFamily must be point, line, area or mixed`);
+                must(typeof d.count === 'number' && d.count >= 0, `dataset ${String(d.ontologyType)}: count must be a number >= 0`);
+                must(Array.isArray(d.properties), `dataset ${String(d.ontologyType)}: properties must be an array`);
+            }
+            if (sample.ontologyType)
+                must(list.some((d) => d.ontologyType === sample.ontologyType), `the sample's type ${sample.ontologyType} is not listed`);
+        }));
+    }
+    return checks;
+}
+const VIEWPORT = { center: { latitude: 19.08, longitude: 72.88 }, zoom: 11 };
+const LAYERS = [
+    { id: 'c-pts', source: { ontologyType: 'P' }, visible: true, zIndex: 3, visualization: { type: 'marker' } },
+    { id: 'c-lines', source: { ontologyType: 'L' }, visible: true, zIndex: 2, visualization: { type: 'line' } },
+    { id: 'c-areas', source: { ontologyType: 'A' }, visible: true, zIndex: 1, visualization: { type: 'polygon' } },
+];
+const sceneObject = (layerId, object) => ({ key: `${layerId}:${object.objectId}`, layerId, object, selected: false, hovered: false });
+const P1 = sceneObject('c-pts', { objectId: 'p1', geometry: { type: 'Point', coordinates: { latitude: 19.08, longitude: 72.88 } }, properties: { status: 'ok' } });
+const L1 = sceneObject('c-lines', { objectId: 'l1', geometry: { type: 'LineString', coordinates: [{ latitude: 19.07, longitude: 72.87 }, { latitude: 19.09, longitude: 72.89 }] } });
+const A1 = sceneObject('c-areas', {
+    objectId: 'a1',
+    geometry: { type: 'Polygon', coordinates: [[{ latitude: 19.06, longitude: 72.86 }, { latitude: 19.06, longitude: 72.9 }, { latitude: 19.1, longitude: 72.9 }, { latitude: 19.06, longitude: 72.86 }]] },
+});
+const SCENE = { viewport: VIEWPORT, layers: LAYERS, objects: [P1, L1, A1] };
+/** Bounds a promise in time, so a renderer that hangs fails the check instead of the run. */
+async function within(ms, p, what) {
+    let timer;
+    try {
+        return await Promise.race([p, new Promise((_, reject) => (timer = setTimeout(() => reject(new ContractViolation(`${what} did not settle within ${ms} ms`)), ms)))]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The Renderer contract (doc §22, §65): bidirectional, incremental, and fully released by destroy(). */
+export function rendererContract(o) {
+    const start = async () => {
+        const r = o.create();
+        await within(5000, r.initialize(o.container(), { basemap: { kind: 'none' }, viewport: VIEWPORT }), 'initialize()');
+        return r;
+    };
+    return [
+        check('renderer: initialize resolves and the size is a real size', async () => {
+            const r = await start();
+            const s = r.getSize();
+            must(Number.isFinite(s.width) && Number.isFinite(s.height) && s.width >= 0 && s.height >= 0, 'getSize() must return finite, non-negative numbers');
+            r.destroy();
+        }),
+        check('renderer: draws a full scene, then patches (add, update, remove, layer change)', async () => {
+            const r = await start();
+            r.render(SCENE);
+            r.update({ updated: [{ ...P1, object: { ...P1.object, geometry: { type: 'Point', coordinates: { latitude: 19.081, longitude: 72.881 } } }, selected: true }] });
+            r.update({ added: [sceneObject('c-pts', { objectId: 'p2', geometry: { type: 'Point', coordinates: { latitude: 19.07, longitude: 72.87 } } })] });
+            r.update({ removed: ['c-lines:l1'] });
+            r.update({ layers: LAYERS.map((l) => (l.id === 'c-pts' ? { ...l, visible: false } : l)) });
+            r.update({ layers: LAYERS.filter((l) => l.id !== 'c-areas'), removed: ['c-areas:a1'] });
+            r.setViewport({ ...VIEWPORT, zoom: 12 });
+            r.resize();
+            r.destroy();
+        }),
+        check('renderer: capabilities, when declared, are yes/no flags it can stand behind', async () => {
+            const r = o.create();
+            const caps = r.capabilities ?? {};
+            for (const [k, v] of Object.entries(caps))
+                must(typeof v === 'boolean', `capabilities.${k} must be true or false`);
+            if (caps.elevation)
+                must(typeof r.sampleElevation === 'function', 'capabilities.elevation needs sampleElevation()');
+            if (caps.globe)
+                must(typeof r.setProjection === 'function', 'capabilities.globe needs setProjection()');
+            if (caps.terrain)
+                must(typeof r.setTerrain === 'function', 'capabilities.terrain needs setTerrain()');
+            if (caps.tiles3d)
+                must(typeof r.setTilesets === 'function', 'capabilities.tiles3d needs setTilesets()');
+            r.destroy();
+        }),
+        check('renderer: every listener returns an unsubscribe that can be called twice', async () => {
+            const r = await start();
+            for (const off of [r.onViewportChange(() => { }), r.onPick(() => { }), r.onMapClick(() => { }), r.onHover(() => { }), r.onError(() => { }), ...(r.onCameraMove ? [r.onCameraMove(() => { })] : [])]) {
+                must(typeof off === 'function', 'listener registration must return a function');
+                off();
+                off();
+            }
+            r.destroy();
+        }),
+        check('renderer: destroy is idempotent and later calls are harmless', async () => {
+            const r = await start();
+            r.render(SCENE);
+            r.destroy();
+            r.destroy();
+            r.update({ removed: ['c-pts:p1'] });
+            r.render(SCENE);
+            r.setViewport(VIEWPORT);
+            r.resize();
+            r.project?.(VIEWPORT.center); // null is fine; throwing is not
+        }),
+        check('renderer: can be initialized again after destroy (unmount, then mount)', async () => {
+            const r = await start();
+            r.render(SCENE);
+            r.destroy();
+            await within(5000, r.initialize(o.container(), { basemap: { kind: 'none' }, viewport: VIEWPORT }), 'second initialize()');
+            r.render(SCENE);
+            r.destroy();
+        }),
+        check('renderer: destroy during initialize settles it promptly', async () => {
+            const r = o.create();
+            const pending = r.initialize(o.container(), { basemap: { kind: 'none' }, viewport: VIEWPORT });
+            r.destroy();
+            await within(2000, pending.then(() => undefined, () => undefined), 'an initialize() cancelled by destroy()');
+        }),
+        check('renderer: setBasemap (when offered) keeps working, and the scene can be drawn again', async () => {
+            const r = await start();
+            if (!r.setBasemap)
+                return r.destroy();
+            r.render(SCENE);
+            await within(5000, r.setBasemap({ kind: 'none', background: '#FFFFFF' }), 'setBasemap()');
+            r.render(SCENE);
+            r.destroy();
+        }),
+    ];
+}
+// ---------------------------------------------------------------- spatial indexes
+/** The SpatialIndex contract (doc §11): any index (RBush today, others later) answers like a full scan. */
+export function spatialIndexContract(create) {
+    // A deterministic 20 × 20 grid of points plus some lines and areas (doc §69: no random coordinates).
+    const objects = [];
+    for (let i = 0; i < 20; i++)
+        for (let j = 0; j < 20; j++)
+            objects.push({ objectId: `p-${i}-${j}`, geometry: { type: 'Point', coordinates: { latitude: 10 + i * 0.1, longitude: 20 + j * 0.1 } } });
+    for (let k = 0; k < 10; k++) {
+        const a = 10 + k * 0.2;
+        objects.push({ objectId: `l-${k}`, geometry: { type: 'LineString', coordinates: [{ latitude: a, longitude: 20 }, { latitude: a + 0.3, longitude: 21.5 }] } });
+        objects.push({ objectId: `a-${k}`, geometry: { type: 'Circle', center: { latitude: a, longitude: 20.5 + k * 0.1 }, radiusMeters: 5000 } });
+    }
+    const boxes = [
+        { west: 20.25, south: 10.25, east: 20.75, north: 10.75 },
+        { west: 19, south: 9, east: 19.5, north: 9.5 },
+        { west: 20, south: 10, east: 22, north: 12 },
+        { west: 20.95, south: 11.05, east: 21.05, north: 11.15 },
+    ];
+    const ids = (list) => list.map((x) => x.objectId).sort();
+    const filled = () => {
+        const index = create();
+        for (const x of objects)
+            index.insert(x);
+        return index;
+    };
+    return [
+        check('index: search finds exactly what a full scan finds', () => {
+            const index = filled();
+            must(index.size === objects.length, `size is ${index.size}, expected ${objects.length}`);
+            for (const b of boxes) {
+                const want = ids(objects.filter((x) => intersectsBounds(x.geometry, b)));
+                const got = ids(index.search(b));
+                // An index returns candidates: it may add bounding-box neighbours, but never miss a match.
+                must(want.every((id) => got.includes(id)), `search(${JSON.stringify(b)}) missed ${want.filter((id) => !got.includes(id)).join(', ')}`);
+                for (const id of got)
+                    must(objects.find((x) => x.objectId === id), `search returned unknown ${id}`);
+            }
+        }),
+        check('index: insert with an existing id replaces it', () => {
+            const index = filled();
+            index.insert({ objectId: 'p-0-0', geometry: { type: 'Point', coordinates: { latitude: -40, longitude: -40 } } });
+            must(index.size === objects.length, 'replacing an object changed the size');
+            must(!ids(index.search(boxes[2])).includes('p-0-0'), 'the old position is still indexed');
+            must(ids(index.search({ west: -41, south: -41, east: -39, north: -39 })).includes('p-0-0'), 'the new position is not indexed');
+            must(index.get('p-0-0').geometry.coordinates.latitude === -40, 'get() returns the old object');
+        }),
+        check('index: remove, get, all and clear', () => {
+            const index = filled();
+            index.remove('p-1-1');
+            index.remove('__missing__');
+            must(index.get('p-1-1') === undefined && index.size === objects.length - 1, 'remove() did not remove');
+            must(!ids(index.search(boxes[2])).includes('p-1-1'), 'a removed object is still found by search');
+            must(index.all().length === objects.length - 1, 'all() does not match size');
+            index.clear();
+            must(index.size === 0 && index.all().length === 0 && index.search(boxes[2]).length === 0, 'clear() left objects behind');
+        }),
+    ];
+}

package/vendor/map-engine/testing/fixtures-monitoring.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Deterministic DSS-shaped fixtures (doc §68–69, Milestone 4): platforms, sensors and their coverage, observations,
+ * fused entities, zones, events and tracks. Fictional coordinates and names; no randomness, so a failure reproduces.
+ * Domain names live ONLY here and in applications — never in engine code.
+ */
+import type { GeometryType, Position, TrackPoint } from '../core/types.js';
+import type { MockRecord, MockSpatialProvider } from './mock-provider.js';
+/** Every fixture timestamp is relative to this instant. */
+export declare const DSS_EPOCH = "2026-10-01T08:00:00Z";
+/** The types and the geometry each declares (what an ontology would say). */
+export declare const DSS_ONTOLOGY: Record<string, GeometryType>;
+/**
+ * Track paths, as functions of minutes from the epoch (0…60). Deterministic, smooth, and crossing the zones so
+ * geofencing and replay have something to show.
+ */
+export declare const DSS_TRACKS: Record<string, (minute: number) => Position>;
+/** All DSS fixture records, typed for the mock provider. */
+export declare const DSS_RECORDS: MockRecord[];
+/** Track points every minute from the epoch to +60 min, for every tracked object. */
+export declare function dssTrackPoints(id: string): TrackPoint[];
+/** Seeds the tracks into a mock provider (replay, trails, history-based geofence events). */
+export declare function seedDssHistory(provider: MockSpatialProvider): void;

package/vendor/map-engine/testing/fixtures-monitoring.js

@@ -0,0 +1,103 @@
+const p = (latitude, longitude) => ({ latitude, longitude });
+const ring = (pts) => [...pts, pts[0]].map(([la, lo]) => p(la, lo));
+/** Every fixture timestamp is relative to this instant. */
+export const DSS_EPOCH = '2026-10-01T08:00:00Z';
+const T0 = Date.parse(DSS_EPOCH);
+const at = (minutes) => new Date(T0 + minutes * 60_000).toISOString();
+/** The types and the geometry each declares (what an ontology would say). */
+export const DSS_ONTOLOGY = {
+    Platform: 'Point',
+    Sensor: 'Point',
+    SensorCoverage: 'Circle',
+    Observation: 'Point',
+    FusedEntity: 'Point',
+    Zone: 'Polygon',
+    Event: 'Point',
+};
+/**
+ * Track paths, as functions of minutes from the epoch (0…60). Deterministic, smooth, and crossing the zones so
+ * geofencing and replay have something to show.
+ */
+export const DSS_TRACKS = {
+    'platform-001': (m) => p(19.08 + 0.02 * Math.sin(m / 9), 72.87 + 0.025 * Math.cos(m / 9)), // air patrol orbit
+    'platform-002': (m) => p(19.13 - 0.0012 * m, 72.95 - 0.0015 * m), // air transit, north-east to south-west
+    'platform-003': (m) => p(19.03 + 0.0009 * m, 72.84 + 0.0011 * m), // ground patrol along the road
+    'fused-entity-001': (m) => p(19.15 - 0.0012 * m, 72.9 + 0.0002 * m), // unknown contact heading into the restricted zone
+};
+const heading = (id, m) => {
+    const a = DSS_TRACKS[id](m);
+    const b = DSS_TRACKS[id](m + 1);
+    return Math.round(((Math.atan2(b.longitude - a.longitude, b.latitude - a.latitude) * 180) / Math.PI + 360) % 360);
+};
+const point = (id, pos, properties, observedAt = DSS_EPOCH) => ({
+    objectId: id,
+    geometry: { type: 'Point', coordinates: pos },
+    properties,
+    observedAt,
+});
+const PLATFORMS = [
+    point('platform-001', DSS_TRACKS['platform-001'](60), { label: 'Falcon One', domain: 'air', role: 'surveillance', status: 'on-mission', fuel: 64, altitude: 1800, speed: 160, heading: heading('platform-001', 60) }, at(60)),
+    point('platform-002', DSS_TRACKS['platform-002'](60), { label: 'Falcon Two', domain: 'air', role: 'transport', status: 'on-mission', fuel: 22, altitude: 3200, speed: 240, heading: heading('platform-002', 60) }, at(60)),
+    point('platform-003', DSS_TRACKS['platform-003'](60), { label: 'Ranger 3', domain: 'ground', role: 'patrol', status: 'on-mission', fuel: 81, altitude: 0, speed: 38, heading: heading('platform-003', 60) }, at(60)),
+    point('platform-004', p(19.045, 72.905), { label: 'Ranger 4', domain: 'ground', role: 'patrol', status: 'standby', fuel: 100, altitude: 0, speed: 0, heading: 0 }),
+];
+const SENSORS = [
+    { object: point('sensor-001', p(19.06, 72.86), { label: 'Radar North', kind: 'radar', status: 'online', rangeMeters: 9000 }), rangeMeters: 9000 },
+    { object: point('sensor-002', p(19.11, 72.93), { label: 'EO Tower 2', kind: 'electro-optical', status: 'online', rangeMeters: 5000 }), rangeMeters: 5000 },
+    { object: point('sensor-003', p(19.02, 72.92), { label: 'Acoustic 3', kind: 'acoustic', status: 'degraded', rangeMeters: 3000 }), rangeMeters: 3000 },
+];
+const COVERAGE = SENSORS.map(({ object, rangeMeters }) => ({
+    objectId: `${object.objectId}-coverage`,
+    geometry: { type: 'Circle', center: object.geometry.coordinates, radiusMeters: rangeMeters },
+    properties: { label: `${object.properties.label} coverage`, sensorId: object.objectId, kind: object.properties.kind, status: object.properties.status },
+}));
+const CLASSES = ['vehicle', 'person', 'aircraft', 'unknown'];
+/** A fixed, irregular-looking spread (golden-angle spiral around the sensors' area); deterministic, no randomness. */
+const scatter = (i) => {
+    const a = i * 2.39996;
+    const r = 0.012 + 0.0045 * i;
+    return p(19.075 + r * Math.sin(a), 72.895 + r * 1.15 * Math.cos(a));
+};
+/** Twelve observations, each tied to a sensor, with a fixed confidence. */
+const OBSERVATIONS = Array.from({ length: 12 }, (_, i) => point(`observation-${String(i + 1).padStart(3, '0')}`, scatter(i), { label: `OBS-${i + 1}`, sensorId: SENSORS[i % 3].object.objectId, classification: CLASSES[i % 4], confidence: 50 + ((i * 7) % 50) }, at(30 + i * 2)));
+const FUSED = [
+    point('fused-entity-001', DSS_TRACKS['fused-entity-001'](60), { label: 'Contact Alpha', classification: 'unknown', threat: 'high', confidence: 78, sources: 3, heading: heading('fused-entity-001', 60) }, at(60)),
+    point('fused-entity-002', p(19.07, 72.94), { label: 'Contact Bravo', classification: 'vehicle', threat: 'medium', confidence: 64, sources: 2, heading: 270 }, at(55)),
+    point('fused-entity-003', p(19.01, 72.87), { label: 'Contact Charlie', classification: 'person', threat: 'low', confidence: 52, sources: 1, heading: 0 }, at(50)),
+];
+const ZONES = [
+    { objectId: 'zone-001', geometry: { type: 'Polygon', coordinates: [ring([[19.1, 72.86], [19.1, 72.92], [19.06, 72.92], [19.06, 72.86]])] }, properties: { label: 'Restricted Area A', kind: 'restricted', level: 'high' } },
+    {
+        objectId: 'zone-002',
+        geometry: { type: 'MultiPolygon', coordinates: [[ring([[19.03, 72.82], [19.03, 72.85], [19.01, 72.85], [19.01, 72.82]])], [ring([[19.13, 72.95], [19.13, 72.98], [19.11, 72.98], [19.11, 72.95]])]] },
+        properties: { label: 'Patrol Areas', kind: 'patrol', level: 'medium' },
+    },
+    { objectId: 'zone-003', geometry: { type: 'Polygon', coordinates: [ring([[19.05, 72.95], [19.05, 72.99], [19.02, 72.99], [19.02, 72.95]])] }, properties: { label: 'Safe Zone', kind: 'safe', level: 'low' } },
+];
+const EVENTS = [
+    point('event-001', p(19.09, 72.88), { label: 'Zone breach', type: 'zone-breach', severity: 'critical', relatedId: 'fused-entity-001' }, at(52)),
+    point('event-002', p(19.02, 72.92), { label: 'Sensor degraded', type: 'sensor-fault', severity: 'warning', relatedId: 'sensor-003' }, at(41)),
+    point('event-003', p(19.07, 72.94), { label: 'New contact', type: 'detection', severity: 'info', relatedId: 'fused-entity-002' }, at(55)),
+];
+/** All DSS fixture records, typed for the mock provider. */
+export const DSS_RECORDS = [
+    ...PLATFORMS.map((object) => ({ object, ontologyType: 'Platform' })),
+    ...SENSORS.map(({ object }) => ({ object, ontologyType: 'Sensor' })),
+    ...COVERAGE.map((object) => ({ object, ontologyType: 'SensorCoverage' })),
+    ...OBSERVATIONS.map((object) => ({ object, ontologyType: 'Observation' })),
+    ...FUSED.map((object) => ({ object, ontologyType: 'FusedEntity' })),
+    ...ZONES.map((object) => ({ object, ontologyType: 'Zone' })),
+    ...EVENTS.map((object) => ({ object, ontologyType: 'Event' })),
+];
+/** Track points every minute from the epoch to +60 min, for every tracked object. */
+export function dssTrackPoints(id) {
+    const path = DSS_TRACKS[id];
+    if (!path)
+        return [];
+    return Array.from({ length: 61 }, (_, m) => ({ timestamp: at(m), ...path(m) }));
+}
+/** Seeds the tracks into a mock provider (replay, trails, history-based geofence events). */
+export function seedDssHistory(provider) {
+    for (const id of Object.keys(DSS_TRACKS))
+        provider.seedHistory(id, dssTrackPoints(id));
+}

package/vendor/map-engine/testing/fixtures.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Reference fixtures from doc 21 (first demo). Domain names live ONLY here and in apps — never in engine code.
+ * Fictional coordinates; WGS84.
+ */
+import type { GeometryType, MapConfig, MapLayer, Position, SpatialObject } from '../core/types.js';
+import type { MockRecord } from './mock-provider.js';
+export declare const ZONE_ALPHA_RING: Position[];
+export declare const UAV_12: SpatialObject;
+export declare const UAV_14: SpatialObject;
+export declare const VEHICLE_21: SpatialObject;
+export declare const ZONE_ALPHA: SpatialObject;
+export declare const ROAD_7: SpatialObject;
+export declare const FIXTURE_RECORDS: MockRecord[];
+export declare const FIXTURE_LAYERS: MapLayer[];
+/** A viewport that shows every fixture at an 800×600 container. */
+export declare const FIXTURE_CONFIG: MapConfig;
+/** Spatial capabilities of the fixture ontology types. */
+export declare const FIXTURE_ONTOLOGY: Record<string, GeometryType>;

package/vendor/map-engine/testing/fixtures.js

@@ -0,0 +1,28 @@
+const p = (latitude, longitude) => ({ latitude, longitude });
+export const ZONE_ALPHA_RING = [p(19.1, 72.85), p(19.1, 72.9), p(19.06, 72.9), p(19.06, 72.85), p(19.1, 72.85)];
+export const UAV_12 = { objectId: 'UAV-12', geometry: { type: 'Point', coordinates: p(19.08, 72.87) }, properties: { status: 'active', label: 'UAV-12' }, observedAt: '2026-10-01T08:00:00Z' };
+export const UAV_14 = { objectId: 'UAV-14', geometry: { type: 'Point', coordinates: p(19.12, 72.93) }, properties: { status: 'standby', label: 'UAV-14' }, observedAt: '2026-10-01T08:00:00Z' };
+export const VEHICLE_21 = { objectId: 'Vehicle-21', geometry: { type: 'Point', coordinates: p(19.05, 72.88) }, properties: { status: 'active', label: 'Vehicle-21' }, observedAt: '2026-10-01T08:00:00Z' };
+export const ZONE_ALPHA = { objectId: 'Zone-Alpha', geometry: { type: 'Polygon', coordinates: [ZONE_ALPHA_RING] }, properties: { label: 'Zone Alpha' } };
+export const ROAD_7 = { objectId: 'Road-7', geometry: { type: 'LineString', coordinates: [p(19.04, 72.84), p(19.07, 72.87), p(19.11, 72.92)] }, properties: { label: 'Road 7' } };
+export const FIXTURE_RECORDS = [
+    { object: UAV_12, ontologyType: 'UAV' },
+    { object: UAV_14, ontologyType: 'UAV' },
+    { object: VEHICLE_21, ontologyType: 'Vehicle' },
+    { object: ZONE_ALPHA, ontologyType: 'Zone' },
+    { object: ROAD_7, ontologyType: 'Road' },
+];
+export const FIXTURE_LAYERS = [
+    { id: 'zones', source: { ontologyType: 'Zone' }, visible: true, zIndex: 1, visualization: { type: 'polygon' }, interaction: { selectable: true, hoverable: true } },
+    { id: 'roads', source: { ontologyType: 'Road' }, visible: true, zIndex: 2, visualization: { type: 'line' } },
+    { id: 'vehicles', source: { ontologyType: 'Vehicle' }, visible: true, zIndex: 3, visualization: { type: 'marker' }, interaction: { selectable: true, hoverable: true } },
+    { id: 'uavs', source: { ontologyType: 'UAV' }, visible: true, zIndex: 4, visualization: { type: 'marker', style: [{ property: 'status', equals: 'active', style: { color: '#4CC3FF' } }, { style: { color: '#8C939C' } }] }, interaction: { selectable: true, hoverable: true } },
+];
+/** A viewport that shows every fixture at an 800×600 container. */
+export const FIXTURE_CONFIG = {
+    viewport: { center: p(19.08, 72.885), zoom: 11 },
+    basemap: { kind: 'none', background: '#0B100E' },
+    layers: FIXTURE_LAYERS,
+};
+/** Spatial capabilities of the fixture ontology types. */
+export const FIXTURE_ONTOLOGY = { UAV: 'Point', Vehicle: 'Point', Zone: 'Polygon', Road: 'LineString' };

package/vendor/map-engine/testing/index.d.ts

@@ -0,0 +1,7 @@
+export { MockSpatialProvider, type MockProviderOptions, type MockRecord } from './mock-provider.js';
+export { TestRenderer } from './test-renderer.js';
+export { MemoryAnnotationStore } from './annotation-store.js';
+export { MockOntologyResolver } from './mock-ontology.js';
+export * from './fixtures.js';
+export * from './fixtures-monitoring.js';
+export { providerContract, rendererContract, spatialIndexContract, ContractViolation, type ContractCheck, type ProviderContractOptions, type RendererContractOptions } from './contracts.js';

package/vendor/map-engine/testing/index.js

@@ -0,0 +1,7 @@
+export { MockSpatialProvider } from './mock-provider.js';
+export { TestRenderer } from './test-renderer.js';
+export { MemoryAnnotationStore } from './annotation-store.js';
+export { MockOntologyResolver } from './mock-ontology.js';
+export * from './fixtures.js';
+export * from './fixtures-monitoring.js';
+export { providerContract, rendererContract, spatialIndexContract, ContractViolation } from './contracts.js';

package/vendor/map-engine/testing/mock-ontology.d.ts

@@ -0,0 +1,13 @@
+import type { GeometryType } from '../core/types.js';
+import type { MissingCapability, OntologySpatialResolver, SpatialBinding } from '../data/contracts.js';
+/**
+ * A stand-in for the Ontology (UNS) side: which types have a spatial capability, and of what geometry.
+ * Types not listed have none, so the engine must report them instead of guessing coordinates (doc 20).
+ */
+export declare class MockOntologyResolver implements OntologySpatialResolver {
+    private readonly types;
+    /** Every type asked for, for asserting the engine caches lookups. */
+    readonly lookups: string[];
+    constructor(types: Record<string, GeometryType>);
+    resolve(ontologyType: string): Promise<SpatialBinding | MissingCapability>;
+}

package/vendor/map-engine/testing/mock-ontology.js

@@ -0,0 +1,24 @@
+/**
+ * A stand-in for the Ontology (UNS) side: which types have a spatial capability, and of what geometry.
+ * Types not listed have none, so the engine must report them instead of guessing coordinates (doc 20).
+ */
+export class MockOntologyResolver {
+    types;
+    /** Every type asked for, for asserting the engine caches lookups. */
+    lookups = [];
+    constructor(types) {
+        this.types = types;
+    }
+    async resolve(ontologyType) {
+        this.lookups.push(ontologyType);
+        const geometryType = this.types[ontologyType];
+        if (!geometryType)
+            return { ontologyType, missing: 'spatial', reason: 'no spatial capability is declared for this type' };
+        return {
+            ontologyType,
+            geometryProperty: geometryType === 'Polygon' ? 'boundary' : geometryType === 'LineString' ? 'route' : 'location',
+            geometryType,
+            capabilities: { supportsSpatialQuery: true, supportsHistoricalQuery: false, supportsRealtime: true, supportsWrite: false },
+        };
+    }
+}