@faclon-labs/app-sdk 0.1.0 → 0.2.0

package/vendor/map-provider-uns/provider.js

@@ -0,0 +1,561 @@
+/**
+ * The UNS as a Map Engine data source (requirement §26–28, §52). UNS ONLY: nodes come from the workspace tree,
+ * live values from `/timeseries/latest`, history from `/timeseries/range` — always by UNS node id. Legacy device /
+ * sensor identifiers in metadata (deviceId, sensorId, latitudeSensor, …) are deprecated and never used.
+ *
+ * Spatiality is a capability (§9), declared on the node as `metadata.spatial`:
+ *   - `SpatialGeometry` → an area: `spatial.geometry` (GeoJSON, EPSG:4326)
+ *   - `SpatialPoint`    → a point: `spatial.geometry` or `spatial.latitude/longitude`
+ *   - `MovingSpatial`   → a point whose position comes from the node's child tags whose `metadata.spatialRole` is
+ *                          `latitude` / `longitude` (heading, speed, altitude roles enrich it)
+ *   - `SpatialTrack`    → history; served through getTracks() from the moving nodes' position tags
+ * Every other child tag becomes a live property named by its `metadata.semantic` (else its name).
+ *
+ * The visual plane (docs 28/29) from what the UNS states, never guessed: provenance (workspace, node path, times,
+ * version and marking from metadata, a time per property), confidence and an accuracy radius from tags with those
+ * spatialRoles, a validity window from metadata, links from `metadata.links` and the spatial parent/child tree, and
+ * an event journal from each node's tag history.
+ */
+import { MapEngineError, describeProperties, matchesQuery, rankByRelation, spatial } from '../map-engine/index.js';
+/** A UNS datum as an engine altitude reference (ADR-028); unknown datums give none — never guessed. */
+export function referenceOf(datum) {
+    const d = (datum ?? '').trim().toUpperCase();
+    if (d === 'MSL' || d === 'AMSL')
+        return 'msl';
+    if (d === 'AGL')
+        return 'agl';
+    if (d === 'HAE' || d === 'WGS84' || d === 'ELLIPSOID' || d === 'WGS-84')
+        return 'ellipsoid';
+    return undefined;
+}
+/** Metadata that identifies legacy wiring or is internal — never shown as an object property. */
+const HIDDEN_META = new Set([
+    'spatial', 'telemetryBinding', 'deviceId', 'deviceType', 'sensorId', 'legacyDevID', 'legacyDevTypeID', 'legacySensorID', 'legacySensorCount',
+    'commissioning', 'source', 'simulated', 'classChain', 'isDevice', 'timeOperators', 'clusterOperators', 'example', 'dataBindings', 'm', 'c', 'enabled',
+]);
+const POSITION_ROLES = new Set(['latitude', 'longitude']);
+/** Tags read into the object's own fields, not its properties. */
+const QUALITY_ROLES = new Set(['confidence', 'accuracy']);
+const CHUNK = 100;
+/** "AirPlatform" → "Air Platform", "RFStation" → "RF Station". */
+const camelWords = (s) => s.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2').replace(/([a-z\d])([A-Z])/g, '$1 $2');
+/** "AirPlatform" → "Air platforms", "RFStation" → "RF stations" (acronyms keep their capitals). */
+export const pluralLabel = (cls) => {
+    const words = camelWords(cls)
+        .split(' ')
+        .map((w, i) => (w.length > 1 && w === w.toUpperCase() ? w : i === 0 ? w : w.toLowerCase()))
+        .join(' ');
+    const plural = /(s|x|ch|sh)$/.test(words) ? `${words}es` : /[^aeiou]y$/.test(words) ? `${words.slice(0, -1)}ies` : `${words}s`;
+    return plural.charAt(0).toUpperCase() + plural.slice(1).replace(/^(\w+)/, (w) => (w === w.toUpperCase() ? w : w.toLowerCase()));
+};
+function toGeometry(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    try {
+        return spatial.fromGeoJSON(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Builds the spatial index of a workspace from its full node rows. Exported for tests. */
+export function indexSpatialNodes(rows) {
+    const byParent = new Map();
+    for (const r of rows)
+        if (r.parentId)
+            byParent.set(r.parentId, [...(byParent.get(r.parentId) ?? []), r]);
+    const tagsUnder = (id, depth = 0) => (byParent.get(id) ?? []).flatMap((c) => (c.type === 'Tag' ? [c] : depth < 1 && !c.metadata.spatial ? tagsUnder(c.id, depth + 1) : []));
+    const out = [];
+    for (const n of rows) {
+        const s = n.metadata.spatial;
+        if (!s || typeof s !== 'object' || n.type === 'Tag' || n.type === 'Class' || n.type === 'Capability')
+            continue;
+        const capability = String(s.capability ?? '');
+        if (capability === 'SpatialTrack')
+            continue; // history, served by getTracks
+        const tags = tagsUnder(n.id).map((t) => {
+            const m = t.metadata;
+            const key = typeof m.semantic === 'string' && m.semantic ? m.semantic : t.name;
+            return {
+                id: t.id,
+                key,
+                path: t.path,
+                ...(typeof m.unit === 'string' && m.unit && m.unit !== 'code' ? { unit: m.unit } : {}),
+                ...(typeof m.spatialRole === 'string' ? { role: m.spatialRole } : {}),
+                ...(Array.isArray(m.enumValues) ? { enumValues: m.enumValues.map(String) } : {}),
+                ...(typeof m.valueType === 'string' ? { valueType: m.valueType } : {}),
+                ...(typeof m.datum === 'string' ? { datum: m.datum } : {}),
+            };
+        });
+        const latTag = tags.find((t) => t.role === 'latitude');
+        const lngTag = tags.find((t) => t.role === 'longitude');
+        const altTag = tags.find((t) => t.role === 'altitude');
+        const altitudeReference = referenceOf(altTag?.datum);
+        let geometry = toGeometry(s.geometry);
+        if (!geometry && typeof s.latitude === 'number' && typeof s.longitude === 'number')
+            geometry = { type: 'Point', coordinates: { latitude: s.latitude, longitude: s.longitude } };
+        const moving = capability === 'MovingSpatial' && latTag !== undefined && lngTag !== undefined;
+        if (!moving && !geometry)
+            continue; // declares space but says nowhere: not drawable
+        const kind = moving ? 'moving' : geometry && geometry.type !== 'Point' && geometry.type !== 'MultiPoint' ? 'area' : s.mobility === 'fixed' ? 'fixed' : 'point';
+        const props = { label: n.name };
+        for (const [k, v] of Object.entries(n.metadata)) {
+            if (HIDDEN_META.has(k) || v === null || v === undefined)
+                continue;
+            if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+                props[k === 'id' ? 'code' : k] = v;
+        }
+        const ts = n.metadata.timestamp ?? n.metadata.lastSeen;
+        out.push({
+            node: n,
+            ontologyType: typeof n.metadata.ontologyClass === 'string' && n.metadata.ontologyClass ? n.metadata.ontologyClass : n.type,
+            kind,
+            ...(geometry && !moving ? { geometry } : {}),
+            tags,
+            ...(latTag ? { latTag } : {}),
+            ...(lngTag ? { lngTag } : {}),
+            ...(altTag && altitudeReference ? { altTag, altitudeReference } : {}),
+            props,
+            ...(typeof ts === 'string' && Number.isFinite(Date.parse(ts)) ? { timestamp: new Date(Date.parse(ts)).toISOString() } : {}),
+        });
+    }
+    return out;
+}
+/** An enum tag's numeric code as its name, when the tag declares the names. */
+function tagValue(tag, v) {
+    if (tag.enumValues && Number.isInteger(v) && v >= 0 && v < tag.enumValues.length)
+        return tag.enumValues[v];
+    if (tag.valueType === 'datetime' && v > 1e11)
+        return new Date(v).toISOString();
+    return v;
+}
+const isoOf = (v) => (typeof v === 'string' && Number.isFinite(Date.parse(v)) ? new Date(Date.parse(v)).toISOString() : undefined);
+export class UnsSpatialProvider {
+    opts;
+    capabilities = { supportsSpatialQuery: true, supportsHistoricalQuery: true, supportsRealtime: true, supportsWrite: false };
+    nodes = null;
+    nodesAt = 0;
+    latestCache = new Map();
+    /** A read in flight, shared by every caller that needs any of its tags (the UNS answers in seconds). */
+    latestInFlight = null;
+    subs = new Set();
+    timer = null;
+    now;
+    constructor(opts) {
+        this.opts = opts;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /**
+     * Who is looking (doc 28 G13): the token goes with every UNS call and everything cached is read again, since
+     * another user may see other nodes and values. A refused read (HTTP 403) reaches the map as a denied layer.
+     */
+    setAuth(auth) {
+        this.opts.client.setToken?.(auth?.token ?? null);
+        this.nodes = null;
+        this.latestCache.clear();
+    }
+    /** The spatial nodes of the workspace (cached; re-read after discoveryTtlMs). */
+    discover(signal) {
+        if (!this.nodes || this.now() - this.nodesAt > (this.opts.discoveryTtlMs ?? 300_000)) {
+            this.nodesAt = this.now();
+            this.nodes = this.readTree(signal).catch((e) => {
+                this.nodes = null;
+                throw e;
+            });
+        }
+        return this.nodes;
+    }
+    async readTree(signal) {
+        const { client, workspace } = this.opts;
+        const roots = await client.children(workspace, undefined, signal);
+        const rows = (await Promise.all(roots.map((r) => client.subtree(workspace, r.id, signal)))).flat();
+        return indexSpatialNodes(rows);
+    }
+    /**
+     * Latest values for tags. The UNS answers a batch in seconds, so a cold read fetches EVERY live tag of the
+     * workspace at once (in parallel chunks) and every layer's query is served from that one round; a read already
+     * in flight is shared rather than repeated.
+     */
+    async latest(tagIds) {
+        const ttl = this.opts.latestTtlMs ?? 2500;
+        const fresh = (id) => {
+            const c = this.latestCache.get(id);
+            return c !== undefined && ttl > 0 && this.now() - c.at < ttl;
+        };
+        const all = this.nodes ? this.liveTagIds(await this.nodes.catch(() => [])) : [];
+        // Wait for a round already running; its answers are stamped when they arrive, so they count as fresh here.
+        while (this.latestInFlight && tagIds.some((id) => !fresh(id)))
+            await this.latestInFlight.catch(() => { });
+        // No await from here until the round is registered, so callers arriving together share it.
+        if (tagIds.some((id) => !fresh(id))) {
+            const need = [...new Set([...tagIds, ...all])].filter((id) => !fresh(id));
+            const round = (async () => {
+                const chunks = [];
+                for (let i = 0; i < need.length; i += CHUNK)
+                    chunks.push(need.slice(i, i + CHUNK));
+                const answers = await Promise.all(chunks.map((c) => this.opts.client.latest(this.opts.workspace, c)));
+                const at = this.now();
+                for (const v of answers.flat())
+                    this.latestCache.set(v.nodeId, { at, value: v });
+            })();
+            this.latestInFlight = round;
+            try {
+                await round;
+            }
+            finally {
+                if (this.latestInFlight === round)
+                    this.latestInFlight = null;
+            }
+        }
+        return new Map(tagIds.flatMap((id) => (this.latestCache.has(id) ? [[id, this.latestCache.get(id).value]] : [])));
+    }
+    /** One spatial node as a SpatialObject, with its live values. Null when a moving node has no position yet. */
+    toObject(n, values) {
+        const props = { ...n.props, ontologyClass: n.ontologyType };
+        let newest = n.timestamp ? Date.parse(n.timestamp) : 0;
+        const perProperty = {};
+        let confidence;
+        let accuracy;
+        for (const t of n.tags) {
+            if (POSITION_ROLES.has(t.role ?? ''))
+                continue;
+            const v = values.get(t.id);
+            if (!(v?.ok && typeof v.value === 'number'))
+                continue;
+            if (v.time && v.time > newest)
+                newest = v.time;
+            // Quality tags feed the object's own fields: confidence as 0…1 (a percentage is scaled), accuracy in metres.
+            if (t.role === 'confidence')
+                confidence = v.value > 1 ? v.value / 100 : v.value;
+            else if (t.role === 'accuracy')
+                accuracy = v.value;
+            if (QUALITY_ROLES.has(t.role ?? ''))
+                continue;
+            props[t.key] = tagValue(t, v.value);
+            perProperty[t.key] = { ...(t.path ? { source: t.path } : {}), ...(v.time ? { observedAt: new Date(v.time).toISOString() } : {}) };
+        }
+        let geometry = n.geometry;
+        if (n.kind === 'moving') {
+            const la = values.get(n.latTag.id);
+            const lo = values.get(n.lngTag.id);
+            if (!la?.ok || !lo?.ok || typeof la.value !== 'number' || typeof lo.value !== 'number')
+                return null;
+            const position = { latitude: la.value, longitude: lo.value };
+            // Height only with a stated reference (ADR-028).
+            const al = n.altTag ? values.get(n.altTag.id) : undefined;
+            if (al?.ok && typeof al.value === 'number' && Number.isFinite(al.value))
+                position.altitude = al.value;
+            if (!spatial.validatePosition(position).valid)
+                return null;
+            geometry = { type: 'Point', coordinates: position };
+            newest = Math.max(newest, la.time ?? 0, lo.time ?? 0);
+        }
+        if (!geometry)
+            return null;
+        const m = n.node.metadata;
+        const provenance = {
+            source: `UNS ${this.opts.workspaceName ?? this.opts.workspace}: ${n.node.path}`,
+            ...(newest > 0 ? { observedAt: new Date(newest).toISOString() } : {}),
+            ...(typeof m.version === 'string' || typeof m.version === 'number' ? { version: m.version } : {}),
+            ...(typeof m.classification === 'string' ? { classification: m.classification } : {}),
+            ...(Object.keys(perProperty).length ? { properties: perProperty } : {}),
+        };
+        const validFrom = isoOf(m.validFrom);
+        const validUntil = isoOf(m.validUntil ?? m.expiresAt);
+        const radius = accuracy ?? (typeof m.spatial?.accuracyMeters === 'number' ? (m.spatial.accuracyMeters) : undefined);
+        return {
+            objectId: n.node.id,
+            geometry,
+            properties: props,
+            ...(newest > 0 ? { observedAt: new Date(newest).toISOString() } : {}),
+            ...(validFrom ? { validFrom } : {}),
+            ...(validUntil ? { validUntil } : {}),
+            ...(confidence !== undefined && Number.isFinite(confidence) ? { confidence: Math.max(0, Math.min(1, confidence)) } : {}),
+            ...(radius !== undefined && radius > 0 ? { uncertainty: { radiusMeters: radius } } : {}),
+            provenance,
+        };
+    }
+    liveTagIds(nodes) {
+        return nodes.flatMap((n) => n.tags.map((t) => t.id));
+    }
+    select(nodes, q) {
+        return nodes.filter((n) => (!q.ontologyType || n.ontologyType === q.ontologyType) && (!q.objectIds || q.objectIds.includes(n.node.id)));
+    }
+    async query(query, signal) {
+        // A superseded request stops even when the answer is cached (engine provider contract).
+        signal?.throwIfAborted();
+        const nodes = this.select(await this.discover(signal), query);
+        const values = await this.latest(this.liveTagIds(nodes));
+        signal?.throwIfAborted();
+        const objects = nodes.map((n) => this.toObject(n, values)).filter((o) => o !== null && matchesQuery(o, query));
+        return rankByRelation(objects, query);
+    }
+    async getCurrentState(objectIds, signal) {
+        return this.query({ objectIds }, signal);
+    }
+    // ---------------------------------------------------------------- realtime (polled; the UNS exposes no stream yet)
+    subscribe(query, onPatch, onError) {
+        const sub = { query: structuredClone(query), onPatch, onError, last: new Map() };
+        this.subs.add(sub);
+        // Seed with what the subscriber has: the snapshot it just loaded.
+        void this.query(query).then((objs) => objs.forEach((o) => sub.last.set(o.objectId, JSON.stringify(o))), () => { });
+        if (!this.timer) {
+            const every = this.opts.setInterval ?? ((fn, ms) => setInterval(fn, ms));
+            this.timer = every(() => void this.poll(), this.opts.pollMs ?? 3000);
+        }
+        return () => {
+            this.subs.delete(sub);
+            if (!this.subs.size && this.timer) {
+                (this.opts.clearInterval ?? ((h) => clearInterval(h)))(this.timer);
+                this.timer = null;
+            }
+        };
+    }
+    /** One polling round for every subscriber. Exposed for tests. */
+    async poll() {
+        if (!this.subs.size)
+            return;
+        let nodes;
+        try {
+            nodes = await this.discover();
+        }
+        catch (e) {
+            for (const s of this.subs)
+                s.onError?.(e);
+            return;
+        }
+        const wanted = nodes.filter((n) => [...this.subs].some((s) => this.select([n], s.query).length));
+        let values;
+        try {
+            values = await this.latest(this.liveTagIds(wanted));
+        }
+        catch (e) {
+            for (const s of this.subs)
+                s.onError?.(e);
+            return;
+        }
+        for (const s of [...this.subs]) {
+            const upserted = [];
+            const removed = [];
+            const seen = new Set();
+            for (const n of this.select(wanted, s.query)) {
+                const o = this.toObject(n, values);
+                if (!o || !matchesQuery(o, s.query))
+                    continue;
+                seen.add(o.objectId);
+                const key = JSON.stringify(o);
+                if (s.last.get(o.objectId) !== key) {
+                    s.last.set(o.objectId, key);
+                    upserted.push(o);
+                }
+            }
+            for (const id of [...s.last.keys()]) {
+                if (seen.has(id))
+                    continue;
+                s.last.delete(id);
+                removed.push(id);
+            }
+            if (upserted.length || removed.length)
+                s.onPatch({ ...(upserted.length ? { upserted } : {}), ...(removed.length ? { removed } : {}) });
+        }
+    }
+    // ---------------------------------------------------------------- history
+    async getTracks(query, range, signal) {
+        signal?.throwIfAborted();
+        const from = Date.parse(range.start);
+        const to = Date.parse(range.end);
+        const moving = this.select(await this.discover(signal), query).filter((n) => n.kind === 'moving');
+        const read = (id) => (id ? this.opts.client.range(this.opts.workspace, id, from, to, signal) : Promise.resolve({ nodeId: '', points: [] }));
+        const tracks = [];
+        // A few nodes at a time: each is two to four range reads.
+        for (let i = 0; i < moving.length; i += 4) {
+            const batch = await Promise.all(moving.slice(i, i + 4).map(async (n) => {
+                const heading = n.tags.find((t) => t.role === 'heading');
+                const speed = n.tags.find((t) => t.role === 'speed');
+                const [la, lo, hd, sp, al] = await Promise.all([read(n.latTag.id), read(n.lngTag.id), read(heading?.id), read(speed?.id), read(n.altTag?.id)]);
+                const lng = new Map(lo.points.map((p) => [p.time, p.value]));
+                const alt = new Map(al.points.map((p) => [p.time, p.value]));
+                const hdg = new Map(hd.points.map((p) => [p.time, p.value]));
+                const spd = new Map(sp.points.map((p) => [p.time, p.value]));
+                const points = [];
+                for (const p of la.points) {
+                    const longitude = lng.get(p.time);
+                    if (longitude === undefined)
+                        continue;
+                    if (!spatial.validatePosition({ latitude: p.value, longitude }).valid)
+                        continue;
+                    points.push({ timestamp: new Date(p.time).toISOString(), latitude: p.value, longitude, ...(alt.has(p.time) ? { altitude: alt.get(p.time) } : {}), ...(hdg.has(p.time) ? { heading: hdg.get(p.time) } : {}), ...(spd.has(p.time) ? { speed: spd.get(p.time) } : {}) });
+                }
+                return points.length ? { objectId: n.node.id, points, properties: { ...n.props, ontologyClass: n.ontologyType } } : null;
+            }));
+            tracks.push(...batch.filter((t) => t !== null));
+        }
+        return tracks;
+    }
+    // ---------------------------------------------------------------- journal (doc 29 §7)
+    /**
+     * The event journal from the UNS's own history: each node's property tags over the range, merged by time into
+     * a snapshot at the range start and one entry per change. Positions are left to tracks; areas and fixed points
+     * without tags have no history (they are static). A node created inside the range (metadata.createdAt) is not
+     * there before it.
+     */
+    async getJournal(query, range, signal) {
+        signal?.throwIfAborted();
+        const from = Date.parse(range.start);
+        const to = Date.parse(range.end);
+        const nodes = this.select(await this.discover(signal), query).filter((n) => n.tags.some((t) => !POSITION_ROLES.has(t.role ?? '')));
+        const values = await this.latest(this.liveTagIds(nodes));
+        const out = [];
+        for (let i = 0; i < nodes.length; i += 4) {
+            const parts = await Promise.all(nodes.slice(i, i + 4).map(async (n) => {
+                const tags = n.tags.filter((t) => !POSITION_ROLES.has(t.role ?? ''));
+                const ranges = await Promise.all(tags.map((t) => this.opts.client.range(this.opts.workspace, t.id, from, to, signal)));
+                const now = this.toObject(n, values);
+                if (!now)
+                    return [];
+                // State at each time a tag changed; values carry forward. Start from the first value each tag had.
+                const times = [...new Set(ranges.flatMap((r) => r.points.map((p) => p.time)))].sort((a, b) => a - b);
+                const current = {};
+                tags.forEach((t, k) => {
+                    const first = ranges[k].points[0];
+                    if (first)
+                        current[t.key] = tagValue(t, first.value);
+                });
+                const created = isoOf(n.node.metadata.createdAt);
+                const entries = [];
+                const state = (at) => ({ ...now, properties: { ...now.properties, ...current }, observedAt: new Date(at).toISOString() });
+                if (!created || Date.parse(created) <= from)
+                    entries.push({ at: range.start, objectId: n.node.id, kind: 'snapshot', object: state(from) });
+                else
+                    entries.push({ at: created, objectId: n.node.id, kind: 'created', object: state(Date.parse(created)) });
+                let last = JSON.stringify(current);
+                for (const time of times.slice(0, 2000)) {
+                    tags.forEach((t, k) => {
+                        const p = ranges[k].points.find((x) => x.time === time);
+                        if (p)
+                            current[t.key] = tagValue(t, p.value);
+                    });
+                    const key = JSON.stringify(current);
+                    if (key === last)
+                        continue;
+                    const before = JSON.parse(last);
+                    const changes = {};
+                    for (const k of Object.keys(current))
+                        if (JSON.stringify(before[k]) !== JSON.stringify(current[k]))
+                            changes[k] = [before[k], current[k]];
+                    last = key;
+                    entries.push({ at: new Date(time).toISOString(), objectId: n.node.id, kind: 'updated', object: state(time), changes, source: 'UNS history' });
+                }
+                return entries;
+            }));
+            out.push(...parts.flat());
+        }
+        return out;
+    }
+    // ---------------------------------------------------------------- links (doc 28 G4)
+    /**
+     * Links the UNS states: `metadata.links` (or `relations`) entries `{ to, type }` naming another node by id or path,
+     * and the tree itself — a spatial node under another spatial node is `part-of` it.
+     */
+    async getLinks(objectIds, types, signal) {
+        signal?.throwIfAborted();
+        const nodes = await this.discover(signal);
+        const byId = new Map(nodes.map((n) => [n.node.id, n]));
+        const byPath = new Map(nodes.map((n) => [n.node.path, n]));
+        const wanted = new Set(objectIds);
+        const out = [];
+        const add = (from, to, type) => {
+            if (!to || to === from || (!wanted.has(from.node.id) && !wanted.has(to.node.id)))
+                return;
+            if (types && !types.includes(type))
+                return;
+            out.push({ id: `${from.node.id}->${to.node.id}:${type}`, fromId: from.node.id, toId: to.node.id, type });
+        };
+        for (const n of nodes) {
+            const declared = (n.node.metadata.links ?? n.node.metadata.relations);
+            if (Array.isArray(declared)) {
+                for (const l of declared) {
+                    const ref = typeof l?.to === 'string' ? l.to : undefined;
+                    if (ref)
+                        add(n, byId.get(ref) ?? byPath.get(ref), typeof l.type === 'string' ? l.type : 'related');
+                }
+            }
+            // The nearest spatial ancestor (UNS paths nest).
+            const parts = n.node.path.split('/');
+            for (let k = parts.length - 1; k > 0; k--) {
+                const up = byPath.get(parts.slice(0, k).join('/'));
+                if (up) {
+                    add(n, up, 'part-of');
+                    break;
+                }
+            }
+        }
+        return out;
+    }
+    // ---------------------------------------------------------------- catalog + ontology
+    async listDatasets(signal) {
+        signal?.throwIfAborted();
+        const nodes = await this.discover(signal);
+        const values = await this.latest(this.liveTagIds(nodes));
+        const groups = new Map();
+        for (const n of nodes)
+            groups.set(n.ontologyType, [...(groups.get(n.ontologyType) ?? []), n]);
+        return [...groups.entries()]
+            .map(([ontologyType, list]) => {
+            const objects = list.map((n) => this.toObject(n, values)).filter((o) => o !== null);
+            const kinds = new Set(objects.map((o) => o.geometry.type));
+            const area = list.every((n) => n.kind === 'area');
+            const units = {};
+            for (const n of list)
+                for (const t of n.tags)
+                    if (t.unit && !POSITION_ROLES.has(t.role ?? ''))
+                        units[t.key] = t.unit;
+            const lastDataAt = Math.max(0, ...objects.map((o) => (o.observedAt ? Date.parse(o.observedAt) : 0)));
+            const bounds = spatial.unionBounds(objects.map((o) => spatial.bounds(o.geometry)));
+            // One reference for the whole class, or none (mixed references must not be drawn as one).
+            const refs = new Set(list.filter((n) => n.altTag).map((n) => n.altitudeReference));
+            const altitude = refs.size === 1 ? [...refs][0] : undefined;
+            const info = {
+                ontologyType,
+                label: pluralLabel(ontologyType),
+                source: `UNS · ${this.opts.workspaceName ?? this.opts.workspace}`,
+                geometryType: kinds.size === 1 ? [...kinds][0] : 'Mixed',
+                geometryFamily: area ? 'area' : 'point',
+                count: list.length,
+                properties: describeProperties(objects),
+                hasHistory: list.some((n) => n.kind === 'moving'),
+                live: list.some((n) => n.tags.length > 0),
+                ...(Object.keys(units).length ? { units } : {}),
+                ...(lastDataAt > 0 ? { lastDataAt } : {}),
+                ...(bounds ? { bounds } : {}),
+                ...(altitude ? { altitude: { reference: altitude } } : {}),
+            };
+            return info;
+        })
+            .sort((a, b) => a.ontologyType.localeCompare(b.ontologyType));
+    }
+    /** Ontology binding from the declared capabilities (§9, §12): what each class is drawn as. */
+    ontology = {
+        resolve: async (ontologyType, signal) => {
+            const list = (await this.discover(signal)).filter((n) => n.ontologyType === ontologyType);
+            if (!list.length)
+                return { ontologyType, missing: 'spatial', reason: 'no node of this class declares a spatial capability in the UNS' };
+            const area = list.every((n) => n.kind === 'area');
+            return {
+                ontologyType,
+                geometryProperty: 'metadata.spatial',
+                geometryType: area ? 'Polygon' : 'Point',
+                capabilities: { ...this.capabilities, supportsHistoricalQuery: list.some((n) => n.kind === 'moving') },
+            };
+        },
+    };
+    /** Stops polling. */
+    dispose() {
+        this.subs.clear();
+        if (this.timer)
+            (this.opts.clearInterval ?? ((h) => clearInterval(h)))(this.timer);
+        this.timer = null;
+    }
+}
+/** Thrown shape for callers that want a typed failure. */
+export const unsError = (message, cause) => new MapEngineError('PROVIDER_ERROR', message, undefined, { cause });