Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 77 additions & 0 deletions docs/integrations/worldgraph-managed-projection.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Managed WorldGraph projection contract

`GET /api/v1/worldgraph/engine` projects the configured managed room into a local
Cartesian layout. It does not read the engine graph writer or report perception,
measured occupancy, calibrated height, geographic registration or live RF links.
The endpoint is read-only and requires the same read authority as `/snapshot`.

## Wire identity and compatibility

The response has exactly `protocol_version`, `stream_epoch`, `seq`, `projection`.
`protocol_version` is3. `projection.schema` is
`ruview.worldgraph.managed-engine-projection.v1`. This is a new managed projection,
not an upstream WorldGraph schema-v2 snapshot. Do not remove that identity and
feed its contents into an engine-snapshot parser.

Existing `/api/v1/worldgraph/snapshot` retains protocol2 and its managed-topology
schema and fields. Its cursor is shared with this projection: repeated reads of
unchanged content through either route do not advance the sequence; source room
or privacy changes advance it once. Restarts use a new random epoch. These are
publication cursors, not measurement timestamps or proof of fresh sensor data.

Current mobile clients continue to request `/snapshot`; their strict legacy
engine/envelope parsers must reject protocol3. A future projection-aware consumer
must be separately implemented and qualified. This server PR does not switch a
mobile URL, activate a new layer or qualify a packaged helper.

## Projection fields

| Field | Meaning |
|---|---|
| `schema` | Explicit managed-projection schema above |
| `provenance` | `operator_entered`; no measurement authority is implied |
| `status` | `configured`, `not_configured` or `privacy_denied` |
| `coordinate_frame` | `managed_room_local`; no geographic origin is known |
| `axis_convention` | `x_right_y_up_metres` |
| `registration` | Always null: geographic origin, scale and heading are unknown |
| `next_id`, `next_edge_id` | Bounded local identifier allocators, not evidence |
| `nodes`, `edges` | Allowlisted room/sensor placement records and membership |

The node/edge field names resemble the engine layout for future adaptation, but
nullable fields intentionally differ from its mandatory numeric values:

- A room has rectangular `bounds_enu` and `floor:null`; a configured room does
not establish its floor number.
- A sensor position retains `east_m=x_m`, `north_m=room_length_m-y_m` and
`up_m:null`. The source origin is the room's top-left and y points down; the
projection origin is its bottom-left and y points up. `east_m`/`north_m` are
local axis names here, not measured global east/north. Valid planar zero
coordinates remain zero; unknown height is not converted to ground level.
- `located_in` edges retain `since_unix_ms:null`: the source keeps no timestamp
for the relationship. Sequence numbers do not supply one.

No generic engine `schema_version:2`, identity geographic registration, invented
floor0, height0 or Unix epoch0 is emitted. This prevents an unaware strict parser
from accepting configured layout as ordinary engine evidence. Projection-aware
consumers must preserve nulls and provenance through display, storage and export;
no inference authority follows from successful parsing.

When not configured or privacy-denied, nodes/edges are empty and both next IDs
are1. Privacy-denied responses reveal no room name, dimensions, sensor identifiers,
raw source records, binding digest, installation ID, tracks or semantic history.
The status distinguishes withheld geometry from an empty configured graph.

## Transport and failure behavior

Responses are `private, no-store`. GET/HEAD do not publish a room, change its
revision/binding, select a learner, write a baseline or start a sensor. POST and
other writes are unsupported. Missing read authorization is rejected. If the
store is unavailable, the endpoint returns501; invalid internal projection input
or poisoned locks return500; sequence exhaustion on a changed publication
returns503. Projection validation happens before cursor mutation so a failed
projection cannot make the next valid read appear newer than its source change.

The repository fixture `managed-worldgraph-engine-projection-v1.json` is the
configured example. Tests cover unknowns, valid planar zeros/bounds, privacy,
not-configured, cursor stability/failure, route authorization and legacy snapshot
compatibility. Physical registration or sensing accuracy is outside this contract.
Original file line number Diff line number Diff line change
Expand Up @@ -260,6 +260,7 @@ fn policy(method: &axum::http::Method, path: &str) -> Option<bool> {
| "/api/v1/room-learner/selection"
| "/api/v1/room-learner/progress"
| "/api/v1/worldgraph/snapshot"
| "/api/v1/worldgraph/engine"
| "/api/v1/calibration/status"
| "/api/v1/pose/calibration/status"
| "/ws/sensing"
Expand Down Expand Up @@ -389,6 +390,9 @@ mod tests {
assert_eq!(policy(&Method::GET, "/api/v1/room-learner/selection"), Some(false));
assert_eq!(policy(&Method::GET, "/api/v1/worldgraph/snapshot"), Some(false));
assert_eq!(policy(&Method::POST, "/api/v1/worldgraph/snapshot"), None);
assert_eq!(policy(&Method::GET, "/api/v1/worldgraph/engine"), Some(false));
assert_eq!(policy(&Method::POST, "/api/v1/worldgraph/engine"), None);
assert_eq!(policy(&Method::HEAD, "/api/v1/worldgraph/engine"), Some(false));
assert_eq!(policy(&Method::HEAD, "/api/v1/room-learner/selection"), Some(false));
assert_eq!(policy(&Method::GET, "/api/v1/room-learner/status"), None);
assert_eq!(policy(&Method::GET, "/api/v1/room-learner/progress"), Some(false));
Expand Down
6 changes: 6 additions & 0 deletions v2/crates/wifi-densepose-sensing-server/src/companion_room.rs
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,12 @@ impl SharedRoomStore {
self.worldgraph_cursor.lock().map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?.project(&room, privacy_denied)
}

/// Same locking order as `worldgraph_snapshot`; shares its cursor.
pub fn worldgraph_engine_snapshot(&self, privacy_denied: bool) -> Result<Value, StatusCode> {
let room = self.current.lock().map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
self.worldgraph_cursor.lock().map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?.project_engine(&room, privacy_denied)
}

pub fn snapshot(&self) -> Option<Envelope> { self.current.lock().ok().map(|v| v.clone()) }
pub fn matches_binding(&self, binding: &str, node_ids: &[u8]) -> bool {
let Ok(e) = self.current.lock() else {
Expand Down
1 change: 1 addition & 0 deletions v2/crates/wifi-densepose-sensing-server/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -16921,6 +16921,7 @@ async fn main() {
// Per-node health endpoint
.route("/api/v1/nodes", get(nodes_endpoint))
.route("/api/v1/worldgraph/snapshot", get(managed_worldgraph::snapshot))
.route("/api/v1/worldgraph/engine", get(managed_worldgraph::engine_snapshot))
// ADR-110 iter 29 — per-node mesh sync state for HTTP clients.
.route("/api/v1/nodes/:id/sync", get(node_sync_endpoint))
.route("/api/v1/mesh", get(mesh_endpoint))
Expand Down
Loading
Loading