ruvnet--RuView/docs/adr/ADR-306-canonical-spatial-ontology.md

ADR-306: Canonical spatial ontology — one Site→…→Event model for every surface

• Status: Accepted — initial implementation planned (ADR-300 phase 1)
• Date: 2026-08-11
• Deciders: ruv
• Tags: ontology, worldgraph, schema, mqtt, matter, rufield, phase-1

Context

This ADR is a child of ADR-300 and owns primitive #6, canonical spatial ontology. In the ADR-300 DAG it is a spine root alongside ADR-305 (authenticated identity) and feeds every downstream primitive that must speak about where and what: ADR-301 (calibration), ADR-307 (tracking, consumes Track/Person), ADR-319 (witness chain), and every external surface named in the ADR-300 consequences (MQTT, REST, WebSocket, RuField, Matter, agents).

RuView currently expresses "where something is" in several overlapping, per-surface schemas: the MQTT/Home-Assistant mapper has its own node/room shapes (ADR-297 just introduced NodeInference/RoomInference to disambiguate node vs. room state); the worldgraph crate models a spatial graph; RuField carries SemanticProvenance; Matter/HomeKit has its own area model. The same physical fact — "a person is in the kitchen" — is re-encoded differently on each surface, and the review called for "one canonical NodeInference/RoomInference contract" (ADR-297 consequences). Without a single semantic model, every new surface multiplies the translation matrix and each translation is a place where provenance and evidence level (ADR-282) can be silently dropped.

Substantial scaffolding already exists and must be reused/extended, not rebuilt. v2/crates/worldgraph/wifi-densepose-worldgraph already defines:

• WorldNode variants including Room { area_id, name, bounds_enu, floor }, Zone { parent_room, … }, Wall { rf_attenuation_db }, and Doorway.
• WorldEdge variants including Observes { quality, last_seen_unix_ms }, LocatedIn { since_unix_ms }, AdjacentTo { via_doorway }, and Supports.
• WorldGraph, WorldGraphSnapshot, WorldId, SemanticProvenance, PersonPosition, and a HomeCore area_id linkage join key (ADR-127).

The worldgraph crate is therefore the natural home for the canonical model. What is missing is (a) the full Site → Building → Floor → Space → Zone containment spine above Room, (b) first-class Sensor, Object, Observation, Track, and Event node types, (c) one canonical serialization that every surface consumes, and (d) a documented migration path from the existing per-surface schemas.

Options considered

1. Leave each surface with its own schema; add adapters pairwise. Rejected: O(surfaces²) translations, and provenance/evidence loss at each hop.
2. Invent a new top-level ontology crate. Rejected: worldgraph already models rooms, zones, walls, doorways, observation edges, and HomeCore linkage; a parallel crate would fork the world model.
3. Extend worldgraph into the canonical ontology and make every surface a projection of it. Chosen.

Decision

Adopt one canonical spatial ontology, hosted in the worldgraph crate, that every RuView surface reads from and writes to.

1. The containment spine and entity types

Define the full node taxonomy as an extension of the existing WorldNode:

Site ▸ Building ▸ Floor ▸ Space ▸ Zone
                                   └─▸ { Sensor, Person, Object,
                                         Observation, Track, Event }

• Site, Building, Floor, Space are new containment WorldNode variants above the existing Room (mapped to Space, keeping its area_id and bounds_enu) and Zone. Wall/Doorway remain as topological elements. Containment reuses the existing LocatedIn/AdjacentTo edge vocabulary; a new PartOf edge expresses the pure hierarchy (Zone PartOf Space PartOf Floor …).
• Sensor is the entity ADR-305 authenticates (DeviceId as its stable identity) and ADR-320 (HAL, phase 2) describes the hardware of. Person, Object, Observation, Track, and Event are first-class nodes. Observes/LocatedIn edges already carry quality and dwell timestamps.
• Track and Person are defined here as the ontology contract that ADR-307 (persistent tracking) produces and updates. Observation is what an authenticated frame (ADR-305) becomes after calibration (ADR-301), and Event is the governed output that ADR-318 certifies and ADR-319 witnesses.

2. Canonical serialization

• A single, versioned serialization (serde-based, stable field names) is the one wire/at-rest representation. Every surface — MQTT/Home-Assistant, REST, WebSocket, RuField observations, Matter/HomeKit, agent queries — is a projection of this model, not an independent schema. NodeInference and RoomInference (ADR-297) become projections of Sensor→Observes and the Space-level fused inference respectively, so ADR-297's node/room separation is preserved by construction rather than re-encoded per surface.
• Every node and edge carries SemanticProvenance and exactly one EvidenceLevel (L0–L5, ADR-282 policy): the evidence ladder travels with the fact across every projection, so no surface can silently upgrade or drop it.

3. Migration path

• Each existing per-surface schema gets a documented, tested bidirectional mapping to/from the canonical model, plus a migration accessor for consumers reading the old shape (mirroring ADR-297's migration accessor). Surfaces are cut over one at a time; a surface is "canonical" once its projection is the only encoder it uses. Until cutover, the mapping layer is authoritative and round-trip-tested so no fact is lost in translation.
• The worldgraph HomeCore area_id linkage (ADR-127) remains the join key between the ontology's Space and external area registries.

Consequences

• The translation matrix collapses from O(surfaces²) to O(surfaces): each surface implements one projection. New surfaces (ROS 2, OpenUSD, OPC UA per ADR-282's roadmap) plug in as additional projections.
• Provenance and evidence level are carried uniformly; a fact cannot cross a surface boundary and lose its lineage or its L-level.
• A schema change reaching every surface; managed by the versioned serialization and per-surface migration accessors. Single-node deployments keep working (one Sensor, one Space).
• The ontology is a representation, not an inference engine: it says nothing about how a Track or Event is produced — that is owned by ADR-307, ADR-301, ADR-302, and the model layer. This ADR does not itself make any accuracy claim to grade.
• Extending worldgraph grows one crate's surface rather than forking a second world model; the geo/worldmodel sub-crates continue to build on the same node vocabulary.

Validation

• Unit tests (cargo test -p wifi-densepose-worldgraph): containment-spine construction and invariants (a Zone is PartOf exactly one Space, a Space on exactly one Floor, etc.); round-trip serialization of every node and edge type; every node/edge carries exactly one EvidenceLevel.
• Migration tests: each per-surface schema maps to the canonical model and back with no loss of provenance or evidence level; NodeInference/RoomInference (ADR-297) project and re-project identically.
• Contract test: a single canonical Event renders correctly through the MQTT, REST, and WebSocket projections from one source of truth.
• No accuracy numbers are claimed; this ADR delivers the shared representation the rest of the phase-1 spine writes into.