Migrate XrTime to monotonic time in devicetracker API

[nvddr]

Summary by CodeRabbit

• Documentation

  • Added mandatory agent guidance files documenting contribution requirements and API contracts across the tracker subsystem and core modules.

• Refactor

  • Refactored time handling throughout tracker implementations to use monotonic nanosecond timestamps instead of OpenXR-specific time values.
  • Removed internal time converter state from session management, simplifying timing propagation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8f1ba70e-1a8f-433c-93f8-0c2b40fbc9c6

📥 Commits

Reviewing files that changed from the base of the PR and between 1904d17 and 01a35c9.

📒 Files selected for processing (25)

• AGENTS.md
• src/core/AGENTS.md
• src/core/deviceio_base/AGENTS.md
• src/core/deviceio_base/cpp/CMakeLists.txt
• src/core/deviceio_base/cpp/inc/deviceio_base/tracker.hpp
• src/core/deviceio_session/AGENTS.md
• src/core/deviceio_session/cpp/CMakeLists.txt
• src/core/deviceio_session/cpp/deviceio_session.cpp
• src/core/deviceio_session/cpp/inc/deviceio_session/deviceio_session.hpp
• src/core/deviceio_trackers/AGENTS.md
• src/core/live_trackers/AGENTS.md
• src/core/live_trackers/cpp/CMakeLists.txt
• src/core/live_trackers/cpp/live_controller_tracker_impl.cpp
• src/core/live_trackers/cpp/live_controller_tracker_impl.hpp
• src/core/live_trackers/cpp/live_frame_metadata_tracker_oak_impl.cpp
• src/core/live_trackers/cpp/live_frame_metadata_tracker_oak_impl.hpp
• src/core/live_trackers/cpp/live_full_body_tracker_pico_impl.cpp
• src/core/live_trackers/cpp/live_full_body_tracker_pico_impl.hpp
• src/core/live_trackers/cpp/live_generic_3axis_pedal_tracker_impl.cpp
• src/core/live_trackers/cpp/live_generic_3axis_pedal_tracker_impl.hpp
• src/core/live_trackers/cpp/live_hand_tracker_impl.cpp
• src/core/live_trackers/cpp/live_hand_tracker_impl.hpp
• src/core/live_trackers/cpp/live_head_tracker_impl.cpp
• src/core/live_trackers/cpp/live_head_tracker_impl.hpp
• src/core/oxr/cpp/inc/oxr/oxr_session.hpp

💤 Files with no reviewable changes (2)

• src/core/deviceio_base/cpp/CMakeLists.txt
• src/core/deviceio_session/cpp/inc/deviceio_session/deviceio_session.hpp

---

📝 Walkthrough

Walkthrough

This PR refactors the tracker timing abstraction to decouple from OpenXR-specific time representation. The ITrackerImpl::update() method signature changes from accepting XrTime to accepting int64_t monotonic_time_ns. The DeviceIOSession class removes its XrTimeConverter member and instead calls os_monotonic_now_ns() once per update frame, passing this unified timestamp to all tracker implementations. Live tracker implementations internally convert the monotonic time to XrTime for OpenXR operations as needed. Additional documentation files (AGENTS.md) specify preflight requirements and architectural constraints across multiple package levels.

Sequence Diagram(s)

sequenceDiagram
    participant App as Application
    participant Session as DeviceIOSession
    participant Tracker as ITrackerImpl
    participant OXR as OpenXR Layer

    rect rgba(200, 150, 100, 0.5)
    Note over App,OXR: Before (XrTime flow)
    App->>Session: update()
    Session->>Session: time_converter_.os_monotonic_now()
    Session->>Session: XrTime current_time
    Session->>Tracker: update(current_time)
    Tracker->>OXR: xrLocateSpace(current_time)
    end

    rect rgba(100, 150, 200, 0.5)
    Note over App,OXR: After (int64_t monotonic ns flow)
    App->>Session: update()
    Session->>Session: os_monotonic_now_ns()
    Session->>Session: int64_t monotonic_ns
    Session->>Tracker: update(monotonic_ns)
    Tracker->>Tracker: convert_monotonic_ns_to_xrtime()
    Tracker->>OXR: xrLocateSpace(xr_time)
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~35 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 3.70% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main objective of the changeset: migrating the devicetracker API from XrTime to monotonic nanosecond timestamps.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch devdeepr/updateMonotonicTsV2

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR migrates the tracker implementation update loop from OpenXR XrTime to a runtime-agnostic monotonic nanosecond timestamp, keeping OpenXR-specific time conversion inside live tracker implementations. It also formalizes hand-joint indexing in the schema to match OpenXR’s XrHandJointEXT, and removes unintended OpenXR dependencies from higher-level/public tracker APIs.

Changes:

• Update ITrackerImpl::update to accept int64_t monotonic_time_ns, and update DeviceIOSession + all live tracker impls to use a single monotonic clock read per frame with per-impl conversion to XrTime.
• Add HandJoint enum to the FlatBuffers schema + Python bindings, and update C++/Python schema tests to reference NUM_JOINTS rather than hard-coded 26.
• Enforce layering: deviceio_base / deviceio_trackers no longer include/link OpenXR; OpenXR dependencies live in deviceio_session / live_trackers / tests.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/core/schema/python/schema_init.py	Exports HandJoint through the Python schema package.
src/core/schema/python/hand_bindings.h	Adds pybind11 binding for HandJoint; updates bounds checking to use HandJoint_NUM_JOINTS.
src/core/schema/fbs/hand.fbs	Introduces HandJoint enum aligned with OpenXR joint ordinals; documents fixed-size semantics.
src/core/schema_tests/python/test_hand.py	Updates tests to use HandJoint.NUM_JOINTS and adds enum sentinel assertions.
src/core/schema_tests/cpp/test_hand.cpp	Adds OpenXR parity static_asserts and replaces hard-coded 26 with HandJoint_NUM_JOINTS.
src/core/schema_tests/cpp/CMakeLists.txt	Links OpenXR headers for parity checks in schema tests.
src/core/oxr/cpp/inc/oxr/oxr_session.hpp	Switches OpenXR handle deleter types to PFN_* to tolerate XR_NO_PROTOTYPES include order.
src/core/live_trackers/cpp/live_head_tracker_impl.hpp	Changes update signature to monotonic ns and stores last_update_time_ as int64_t.
src/core/live_trackers/cpp/live_head_tracker_impl.cpp	Converts monotonic ns → XrTime once per frame; writes MCAP timestamps with monotonic + xr_time.
src/core/live_trackers/cpp/live_hand_tracker_impl.hpp	Changes update signature/storage to monotonic ns; keeps helper using XrTime.
src/core/live_trackers/cpp/live_hand_tracker_impl.cpp	Converts monotonic ns → XrTime once; uses xr_time for OpenXR + MCAP.
src/core/live_trackers/cpp/live_generic_3axis_pedal_tracker_impl.hpp	Updates update signature to monotonic ns.
src/core/live_trackers/cpp/live_generic_3axis_pedal_tracker_impl.cpp	Renames unused update parameter to monotonic ns.
src/core/live_trackers/cpp/live_full_body_tracker_pico_impl.hpp	Updates update signature/storage to monotonic ns.
src/core/live_trackers/cpp/live_full_body_tracker_pico_impl.cpp	Converts monotonic ns → XrTime only after null-handle early return; uses xr_time for MCAP.
src/core/live_trackers/cpp/live_frame_metadata_tracker_oak_impl.hpp	Updates update signature to monotonic ns.
src/core/live_trackers/cpp/live_frame_metadata_tracker_oak_impl.cpp	Renames unused update parameter to monotonic ns.
src/core/live_trackers/cpp/live_controller_tracker_impl.hpp	Updates update signature/storage to monotonic ns.
src/core/live_trackers/cpp/live_controller_tracker_impl.cpp	Uses per-frame xr_time for xrLocateSpace and MCAP timestamps.
src/core/live_trackers/cpp/CMakeLists.txt	Ensures live_trackers links oxr::oxr_utils publicly (headers/types).
src/core/live_trackers/AGENTS.md	Adds package-specific rules for time conversion, MCAP timestamps, includes, and CMake linkage.
src/core/deviceio_trackers/python/tracker_bindings.cpp	Removes OpenXR include; sources joint constants from schema HandJoint_* instead of OpenXR.
src/core/deviceio_trackers/cpp/inc/deviceio_trackers/hand_tracker.hpp	Removes OpenXR-derived debug API (get_joint_name) from public tracker API.
src/core/deviceio_trackers/cpp/hand_tracker.cpp	Removes get_joint_name implementation and OpenXR-based joint name table.
src/core/deviceio_trackers/cpp/CMakeLists.txt	Drops OpenXR extension linking from deviceio_trackers to keep it OpenXR-free.
src/core/deviceio_trackers/AGENTS.md	Documents “no OpenXR dependency” boundary for deviceio_trackers.
src/core/deviceio_session/cpp/inc/deviceio_session/deviceio_session.hpp	Removes session-owned XrTimeConverter and OpenXR time include.
src/core/deviceio_session/cpp/deviceio_session.cpp	Uses os_monotonic_now_ns() and passes monotonic ns to impls.
src/core/deviceio_session/cpp/CMakeLists.txt	Propagates oxr::oxr_utils + extension headers to consumers of deviceio_session public headers.
src/core/deviceio_session/AGENTS.md	Documents the new update-loop contract and include requirements.
src/core/deviceio_base/cpp/inc/deviceio_base/tracker.hpp	Makes ITrackerImpl::update monotonic ns and removes OpenXR dependency from base interface.
src/core/deviceio_base/cpp/CMakeLists.txt	Removes OpenXR/oxr link dependencies from the INTERFACE base library.
src/core/deviceio_base/AGENTS.md	Documents runtime-agnostic API boundary for deviceio_base.
src/core/AGENTS.md	Adds src/core AGENTS index and preflight reminder.
AGENTS.md	Adds repo-wide agent preflight, pre-commit, and learning-loop requirements.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[nvddr]

Related to #359

Fixes #322