diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index c3b708e..ac6ae0f 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -13,7 +13,7 @@ jobs:
strategy:
fail-fast: false
matrix:
- python-version: ["3.10", "3.11"]
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
steps:
- name: Checkout
@@ -29,22 +29,20 @@ jobs:
- name: Install dependencies
run: |
python -m pip install --upgrade pip
- pip install -r requirements.txt
- pip install -e .
+ python -m pip install -r requirements.txt
+ python -m pip install -e .
- - name: Run unit tests
- run: |
- pytest -q
+ - name: Compile Python sources
+ run: python -m compileall -q src scripts examples
- - name: Quickstart smoke (scene → nudge → plan → safety)
- run: |
- python examples/quickstart.py --scene sim/scenes/basic_room.json --verbose
+ - name: Run automated tests
+ run: pytest -q
- - name: Import benchmark catalog smoke
- run: |
- python - <<'PY'
- from ohip_bench.scenarios import make_core_catalog
- catalog = make_core_catalog()
- assert len(catalog) >= 3
- print("benchmark scenarios:", [scenario.scenario_id for scenario in catalog])
- PY
+ - name: Run protocol quickstart
+ run: python examples/quickstart.py --scene sim/scenes/basic_room.json --verbose
+
+ - name: Run perception-to-contact integration demo
+ run: python examples/perception_to_contact_demo.py
+
+ - name: Run adversarial safety-authority benchmark
+ run: python scripts/run_safety_authority_benchmark.py
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5aab8de..98a67f5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,41 +1,43 @@
# Changelog
-All notable changes to this project will be documented in this file.
+All notable changes to IX-HapticSight are documented here.
-The format is based on Keep a Changelog.
-This project follows semantic versioning principles for tagged releases.
-
-## [Unreleased]
+## [0.2.0] - 2026-08-29
### Added
-- Python packaging baseline via `pyproject.toml`.
-- Repository hygiene baseline via `.gitignore`.
-- Changelog for tracking safety, runtime, benchmark, and governance upgrades across the v0.1 to v1.0 buildout.
-
-### Planned
-- Repository authorship and scope cleanup.
-- Runtime package restructuring.
-- ROS 2 lifecycle node scaffolding.
-- Motion execution and safety shield expansion.
-- Tactile, proximity, thermal, and force/torque interfaces.
-- Logging, replay, integrity, and threat-model artifacts.
-- Benchmark harnesses and simulation scenario packs.
-- HIL scaffolding and safety-case traceability artifacts.
+- Executable RGB-D perception pipeline with image ingestion.
+- Two independently trained reference semantic segmenters with committed model parameters, deterministic training script, and held-out synthetic calibration metrics.
+- Perception quorum that fails closed on model disagreement, critical-class disagreement, or low confidence.
+- Vision-derived 3D GREEN/YELLOW/RED hazard projection.
+- Deterministic multimodal safety fusion across vision, force/torque, tactile, proximity, and thermal state.
+- Model-agnostic LLM/VLA safety broker that hashes untrusted physical proposals and returns bounded decision receipts.
+- Independent safety authority that returns explicit `ALLOW`, `MODIFY`, or `DENY` decisions and bounded counterfactual explanations.
+- Dynamic force and speed envelopes that derate authority for uncertainty, YELLOW state, and human proximity.
+- Cycle-level runtime invariant monitor for consent, force, speed, sensor freshness, perception quorum, watchdog timing, and E-stop state.
+- Bounded soft-real-time reference controller with deterministic recovery, zero-effort, retract, safe-hold, and operator-clear semantics.
+- Deterministic contact-world simulation for closed-loop regression testing.
+- ROS 2 bridge for bounded twist commands, `WrenchStamped` force/torque input, normalized tactile-patch input, E-stop input, and safety events.
+- Standard ROS 2 `FollowJointTrajectory` client implementation for physical robot-controller integration when ROS 2 hardware is available.
+- WebXR safety observer with live hazard, force-cap, speed-cap, consent, controller-state, and authority visualization.
+- Executable HIL harness that can only report `PASSED` from declared hardware capability plus measured samples. Missing hardware produces `NOT_RUN_NO_HARDWARE`, never a synthetic pass.
+- SHA-256 chained runtime evidence records and portable evidence-bundle verification.
+- Adversarial safety-authority benchmark covering nominal behavior, over-request derating, RED hazards, consent loss, perception disagreement, high uncertainty, and human-proximity cases.
+- End-to-end perception-to-contact software demonstration.
+- Expanded automated test suite: 183 tests passing at release-candidate build time.
+
+### Corrected
+- Package license metadata now matches the MIT `LICENSE` file.
+- Responsible-use language moved to a separate non-license statement to avoid contradictory license claims.
+- Repository author metadata normalized to Bryce Lovell.
+
+### Evidence limits
+- Reference vision models are trained on deterministic synthetic calibration data, not field robot datasets.
+- The Python controller is timing-instrumented soft real time, not a certified hard-real-time controller.
+- ROS 2 and robot-controller adapters are implemented but not physically validated in this repository build.
+- No HIL pass or real-robot pass is claimed without external measured hardware evidence.
## [0.1.0] - 2026-04-10
### Added
- Initial OHIP schemas and protocol reference implementation.
-- Consent management logic.
-- Contact planning logic.
-- Nudge scheduling logic.
-- Rest-pose generation logic.
-- Safety gate logic.
-- Example quickstart script.
-- Core configuration files for force limits and culture profiles.
-- Basic simulation scene.
-- Unit tests for schemas and scheduler.
-
-### Notes
-- `0.1.0` is the pre-upgrade baseline imported before the 72-commit architecture and runtime expansion campaign.
-- The project at this stage is a reference implementation and documentation-first prototype, not a deployable robotics runtime.
+- Consent management, contact planning, nudge scheduling, rest pose generation, safety gating, simulation scene, configuration, and baseline tests.
diff --git a/LICENSE b/LICENSE
index 8a7a025..db27650 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,62 +1,21 @@
MIT License
-Copyright (c) 2025 Bryce Lovell
+Copyright (c) 2025-2026 Bryce Lovell
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
--------------------------------------------------------------------------------
-Responsible Use Addendum for IX-HapticSight
-
-The Software is intended for humanitarian, assistive, educational, and
-industrial safety applications only.
-
-By using, modifying, or distributing this Software, you agree to the
-following additional conditions:
-
-1. **No Weaponization**
- You may not use the Software, in whole or in part, to design, develop,
- train, deploy, or operate any system intended to cause physical harm
- to humans, animals, or the environment.
-
-2. **No Coercive Use**
- You may not use the Software to engage in coercive control, surveillance
- of individuals without their consent, or any other activity that violates
- internationally recognized human rights.
-
-3. **Safety Compliance**
- Any deployment of this Software in physical systems must implement
- adequate safety measures, including force limits, hazard detection,
- and emergency stop capabilities, as recommended in the project
- documentation.
-
-4. **Ethical Attribution**
- Any public or commercial deployment must credit the original author
- ("Bryce Lovell") and retain this Responsible Use Addendum in all copies
- and derivative works.
-
-Violation of these conditions immediately terminates your rights under this
-License for the offending use, without limiting any other remedies available
-under law.
-
--------------------------------------------------------------------------------
-
-This Responsible Use Addendum is a non-legally binding expression of intent
-and good faith, designed to guide ethical use. However, the prohibitions on
-weaponization and unsafe deployment are intended to be enforceable under
-applicable law when incorporated into contracts, agreements, or terms of use.
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
index a0c279e..7751380 100644
--- a/README.md
+++ b/README.md
@@ -1,332 +1,390 @@
# IX-HapticSight
-**IX-HapticSight** is a safety-first optical-haptic interaction architecture for bounded human-facing robot behavior.
+**IX-HapticSight** is an open, safety-first perception-to-contact authority for robots and XR.
-The repository is built around one narrow idea:
+It is built around one architectural rule:
-> convert perception, consent state, safety state, and bounded contact rules into explicit approach, contact, retreat, and safe-hold behavior that can be inspected, tested, replayed, and benchmarked.
+> Intelligent perception, planning, or an LLM may propose a physical action. A separate deterministic safety authority decides whether that action is allowed, must be reduced, or must be denied.
-This repo is **not** positioned as a broad “emotion-aware robot” claim, a production deployment stack, or a certified collaborative robot package. It is a **measurement-first, audit-friendly reference architecture** with working code, tests, structured logging, replay helpers, interface abstractions, and deterministic benchmark support.
+The repository connects perception-derived state to bounded robot behavior through explicit consent, hazard, force, speed, freshness, uncertainty, watchdog, recovery, and evidence rules.
----
+**License:** MIT. See `RESPONSIBLE_USE.md` for the project's non-license safety and humanitarian-use statement.
-## Current Status
+## v0.2.0 status
-**Current maturity:** strong repository architecture / reference-runtime stage
+Software reference implementation with executable perception, safety authority, controller, ROS 2 integration code, WebXR observability, simulation, HIL evidence collection, replay, benchmarks, and tests.
-What the repo currently includes:
+Current automated suite at the v0.2.0 release-candidate build: **183 tests passing**.
-- deterministic OHIP protocol core
-- backend-agnostic runtime coordination layer
-- explicit runtime session and fault models
-- structured JSONL event logging
-- replay helpers for event streams
-- normalized interface models for:
- - force/torque
- - tactile
- - proximity
- - thermal
- - execution adapters
-- in-memory simulated execution adapter
-- deterministic benchmark runner, scenario catalog, and reporting helpers
-- expanded safety, governance, replay, benchmark, and HIL-prep documentation
-- unit tests and CI workflow
+This repository does **not** claim a physical robot, HIL pass, certified safety system, or production deployment unless measured hardware evidence is explicitly included.
-What it does **not** currently include:
+## What is implemented
-- real hardware integration
-- HIL measured data
-- certified safety evidence
-- production deployment approval
-- medical or therapeutic validation
-- blanket privacy or compliance claims
+### Perception and vision
-That line matters. This repo is strongest when it stays precise.
+- RGB image ingestion with depth input
+- executable semantic segmentation model
+- two independently trained reference model parameter sets
+- deterministic training script
+- held-out synthetic calibration metrics
+- model-confidence and uncertainty output
+- independent perception quorum
+- critical-class disagreement detection
+- vision-derived 3D GREEN / YELLOW / RED hazard voxels
----
+The shipped reference segmentation models are intentionally small and auditable. They are trained on deterministic **synthetic calibration data**. This proves an executable vision path and reproducible model artifact, not production perception accuracy.
-## What the Repository Is Trying to Do
+### Agent / VLA safety broker
-IX-HapticSight is trying to make one difficult boundary explicit:
+`src/ohip_agent/` treats LLM, VLA, or planner output as an **untrusted physical proposal**. The broker hashes the exact proposal, fuses current multimodal safety state, and issues a receipt containing the granted force/speed authority and reasons. Agent output can never increase deterministic limits.
-**when a machine is allowed to approach, touch, withdraw, or stop around a person — and how that decision is made visible and reviewable.**
+### Independent safety authority
-The repo is built around:
+`src/ohip_control/authority.py` provides an explicit authority boundary:
-- bounded interaction semantics
-- consent-aware contact authorization
-- safety-veto authority over convenience behavior
-- explicit retreat and safe-hold semantics
-- replayable event trails
-- scenario-based benchmark evaluation
-- traceable evidence growth toward future HIL work
+- `ALLOW`
+- `MODIFY`
+- `DENY`
----
+The authority evaluates:
-## What the Repository Is Not
+- consent state
+- perception quorum
+- perception uncertainty
+- GREEN / YELLOW / RED safety level
+- human presence and proximity
+- requested force
+- requested speed
+- configured base limits
-This repository is **not**:
+A learned model cannot enlarge the granted envelope.
-- a general social robotics framework
-- a claim of human-emotion understanding
-- a production manipulator stack
-- a guarantee of safe real-world touch
-- a substitute for hardware safety engineering
-- a substitute for regulatory, institutional, or legal review
-- a proof of collaborative-robot certification
-- a finished physical system
+### Deterministic multimodal fusion
-The right way to read this repo is:
+Vision, force/torque, tactile, proximity, and thermal assessments are fused into one inspectable GREEN / YELLOW / RED decision. Required missing modalities fail closed. Excessive measured force, tactile pressure/shear, thermal limits, proximity stops, or perception disagreement can override a visually GREEN scene.
-**bounded concept-stage architecture with real code, real tests, real structured artifacts, and explicit evidence limits.**
+### Dynamic force and speed envelopes
----
+Authority automatically derates or removes motion based on:
-## Repository Structure
+- YELLOW safety state
+- increasing perception uncertainty
+- human proximity
+- RED hazards
-### Protocol core
-`src/ohip/`
+A request for 8 N does not become an 8 N command merely because an AI planner asked for it.
-Stable reference-implementation layer for:
-- schemas
-- consent management
-- contact planning
-- engagement scheduling
-- rest pose generation
-- safety gating
-
-### Runtime layer
-`src/ohip_runtime/`
-
-Backend-agnostic runtime ownership for:
-- interaction session state
-- runtime fault models
-- coordination requests and decisions
-- runtime coordinator
-- session store
-- configuration wiring
-- high-level runtime service
-
-### Interface layer
-`src/ohip_interfaces/`
-
-Normalized sensing and execution contracts for:
-- signal health and freshness
-- force/torque samples
-- tactile frames
-- proximity frames
-- thermal frames
-- execution adapter contracts
-- simulated execution adapter
-
-### Logging and replay
-`src/ohip_logging/`
-
-Structured evidence layer for:
-- event records
-- JSONL event logs
-- event recorder
-- replay helpers
-
-### Benchmark layer
-`src/ohip_bench/`
-
-Deterministic evaluation layer for:
-- benchmark models
-- benchmark runner
-- built-in scenario catalog
-- benchmark reporting
-
-### Supporting assets
-- `configs/` — force and culture profile configuration
-- `docs/` — spec, state machine, safety, governance, replay, benchmark, and HIL-prep docs
-- `examples/` — quickstart reference path
-- `sim/` — simulation scene assets
-- `tests/` — unit and integration-style repository tests
-- `.github/workflows/tests.yml` — CI test workflow
-
----
-
-## Documentation Map
-
-Start here if you want the repo’s architectural story in order:
-
-1. `docs/spec.md`
-2. `docs/state_machine.md`
-3. `docs/index.md`
-4. `ROADMAP.md`
-5. `docs/architecture/runtime_overview.md`
-6. `docs/safety/invariants.md`
-7. `docs/safety/requirements_traceability.md`
-8. `docs/governance/safety_case.md`
-9. `docs/benchmarks/overview.md`
-10. `docs/replay/event_log_schema.md`
-11. `docs/hil/test_rig_architecture.md`
-
-If you only want the high-level direction:
-- `ROADMAP.md`
-- `docs/governance/standards_crosswalk.md`
-- `docs/governance/safety_case.md`
-
----
-
-## Runtime Flow
-
-At the current repository stage, the main runtime story is:
-
-1. create or load an interaction session
-2. submit an explicit interaction request
-3. evaluate consent
-4. evaluate safety
-5. build a bounded planning outcome if allowed
-6. record the full structured decision trail
-7. optionally submit a bounded execution request
-8. record execution status, transitions, faults, retreat, or safe-hold behavior
-9. replay or benchmark the resulting event trail later
-
-That flow is represented across:
-- `src/ohip_runtime/`
-- `src/ohip_logging/`
-- `src/ohip_interfaces/`
-- `src/ohip_bench/`
+### Cycle-level invariant monitoring
+
+Every reference control cycle can independently verify:
----
+- E-stop state
+- consent continuity
+- perception-quorum health
+- commanded force versus granted force
+- measured force versus granted force
+- commanded speed versus granted speed
+- safety-sensor freshness
+- controller watchdog timing
-## Structured Logging and Replay
+Violations drive deterministic stop, latch, retreat, zero-effort, or safe-hold behavior.
-A major part of this upgrade is that important behavior is no longer supposed to disappear into console output.
+### Contact control and recovery
-Current logging/replay support includes:
+The reference controller is executable and timing-instrumented. It supports:
-- structured event records
-- append-friendly JSONL logs
-- request/decision/fault/transition/execution event helpers
-- replay loading and slicing
-- replay filtering by:
- - session
- - request
- - event kind
- - event range
+- approach
+- contact
+- bounded command clamping
+- measured over-force detection
+- consent-loss stop
+- perception-disagreement stop
+- zero-effort recovery
+- retract recovery
+- safe hold
+- operator-clear latch semantics
-This matters because a safety-first interaction repo should be explainable **after the fact**, not only impressive in the moment.
+The Python implementation is **soft real time**. It is not represented as a certified hard-real-time controller.
-Relevant files:
-- `src/ohip_logging/events.py`
-- `src/ohip_logging/jsonl.py`
-- `src/ohip_logging/recorder.py`
-- `src/ohip_logging/replay.py`
+### ROS 2
----
+`src/ohip_ros2/` contains real ROS 2 integration code, loaded only when ROS 2 is available:
-## Benchmarking
+- `geometry_msgs/WrenchStamped` force/torque ingestion
+- normalized tactile-patch ingestion via `std_msgs/Float32MultiArray`
+- bounded `TwistStamped` output
+- E-stop input
+- structured safety-event output
+- standard `control_msgs/FollowJointTrajectory` action client
+- robot-controller trajectory validation
-The repo now includes a deterministic benchmark layer.
+This means the repository contains an executable path into normal ROS 2 robot infrastructure. It does **not** mean a physical robot was run for this release.
-Current benchmark support includes:
+### WebXR
-- explicit scenario definitions
-- explicit expectations
-- structured observations
-- structured benchmark results
-- small built-in scenario catalog
-- reporting helpers for summaries and pass rates
+`examples/webxr/` contains a browser WebXR safety observer that exposes:
-Current built-in scenarios focus on:
-- explicit-consent approval path
-- missing-consent denial path
-- RED-safety denial path
+- live safety-authority decision
+- GREEN / YELLOW / RED hazard markers
+- force cap
+- speed cap
+- consent state
+- controller state
+- veto / derating reason
-Relevant files:
-- `src/ohip_bench/models.py`
-- `src/ohip_bench/runner.py`
-- `src/ohip_bench/scenarios.py`
-- `src/ohip_bench/reporting.py`
+A WebXR-capable browser can request an `immersive-ar` session. Device-specific registration and headset validation remain future measured work.
-And the reviewer-facing docs:
-- `docs/benchmarks/overview.md`
-- `docs/benchmarks/scenario_catalog.md`
-- `docs/benchmarks/metrics.md`
+### HIL evidence harness
----
+`src/ohip_hil/` implements a hardware-in-the-loop evidence harness with a strict rule:
-## HIL Preparation
+**no hardware, no HIL PASS.**
-This repo now includes HIL-prep documentation, but not HIL proof.
+Possible results include:
-Current HIL-prep docs define:
-- recommended test-rig architecture
-- calibration strategy
-- fault-injection strategy
+- `PASSED`
+- `FAILED`
+- `NOT_RUN_NO_HARDWARE`
+- `NOT_RUN_INCOMPLETE`
-These are here so future physical evidence can be:
-- bounded
-- calibrated
-- traceable
-- linked back to repo requirements and claims
+A PASS requires declared hardware capability plus measured samples satisfying the configured force, latency, fault, and sample-count criteria.
-Relevant docs:
-- `docs/hil/test_rig_architecture.md`
-- `docs/hil/calibration.md`
-- `docs/hil/fault_injection.md`
+### Tamper-evident evidence
-This is **evidence preparation**, not evidence completion.
+`src/ohip_evidence/` provides:
+
+- SHA-256 chained runtime records
+- sequence continuity
+- previous-hash continuity
+- portable JSONL evidence records
+- manifest hashing
+- evidence-bundle verification
+- tamper detection
+
+This makes post-run evidence independently checkable instead of relying only on console output.
+
+### Existing OHIP protocol/runtime layers
+
+The repository retains and extends its earlier architecture for:
+
+- consent management
+- contact planning
+- nudge scheduling
+- rest pose generation
+- dual-channel safety gating
+- runtime sessions and fault states
+- normalized force/torque interfaces
+- tactile interfaces
+- proximity interfaces
+- thermal interfaces
+- structured event logging
+- replay
+- deterministic benchmark scenarios
+- simulated execution
+
+## Architecture
+
+```text
+Camera / depth / scene state
+ |
+ v
+ perception model A
+ perception model B
+ |
+ v
+ perception quorum
+ |
+ v
+ vision-derived hazard map
+ |
+ +----------------------+
+ |
+AI / LLM / planner proposal |
+ | |
+ v v
+ +-----------------------------------+
+ | INDEPENDENT SAFETY AUTHORITY |
+ | |
+ | consent |
+ | uncertainty |
+ | model agreement |
+ | hazard state |
+ | force / speed envelopes |
+ | human proximity |
+ +-----------------------------------+
+ |
+ ALLOW / MODIFY / DENY
+ |
+ v
+ bounded reference controller
+ |
+ runtime invariant monitor
+ |
+ +-----+--------------------+
+ | |
+ v v
+ROS 2 / robot adapter recovery authority
+ | zero effort / retract
+ v safe hold / operator
+robot or simulator |
+ ^ |
+ | |
+force / tactile / proximity ------+
+ |
+ v
+ tamper-evident evidence + replay + XR observer
+```
----
+## Quick verification
-## Quick Start
+Run the complete software release verification:
-### 1. Install
```bash
-pip install -r requirements.txt
-pip install -e .
+python scripts/verify_release.py
```
-2. Run tests
+Or install and run the suite directly:
+
```bash
+python -m pip install -e .
pytest -q
```
-3. Run the quickstart smoke path
+Run the existing protocol quickstart:
+
```bash
-python examples/quickstart.py --scene sim/scenes/basic_room.json --verbose
+python examples/quickstart.py
```
-4. Inspect the benchmark catalog
+Run the perception-to-contact integration demo:
+
```bash
-python - <<'PY'
-from ohip_bench.scenarios import make_core_catalog
-catalog = make_core_catalog()
-print([scenario.scenario_id for scenario in catalog])
-PY
+python examples/perception_to_contact_demo.py
```
-Release Gate
+Run the adversarial independent-authority benchmark:
-A release should be checked against:
+```bash
+python scripts/run_safety_authority_benchmark.py
+```
-CHANGELOG.md
-RELEASE_CHECKLIST.md
+Retrain both committed reference segmenters reproducibly:
-That checklist is there to stop the repo from becoming more polished than it is supported.
+```bash
+python scripts/train_reference_segmenter.py
+```
-License
+Run the WebXR observer:
-This repository is released under the license terms in LICENSE
-.
+```bash
+python examples/webxr/run_observer.py
+```
-Do not rely on shorthand descriptions in old summaries. The authoritative licensing terms are the ones in the actual license file.
+Then open `http://127.0.0.1:8765` in a browser. WebXR immersive AR requires compatible browser/device support.
-Author
+## Repository map
-Bryce Lovell
+### Core protocol
+
+`src/ohip/`
+
+Consent, schemas, planning, safety gating, nudge scheduling, and rest pose behavior.
+
+### Perception
+
+`src/ohip_perception/`
+
+RGB-D frames, reference segmentation, two-model quorum, vision pipeline, and hazard projection.
-Final Positioning
+### Agent safety broker
-The strongest way to understand IX-HapticSight is this:
+`src/ohip_agent/`
-It is not trying to prove that robots “understand people.”
-It is trying to make human-facing approach, contact, retreat, and safe-hold behavior more bounded, testable, replayable, and auditable.
+Model-agnostic LLM/VLA proposal ingestion, multimodal safety brokerage, proposal hashing, and decision receipts.
-That is a narrower claim.
-It is also the more credible one.
+### Physical safety authority and control
+`src/ohip_control/`
+
+Independent action authority, dynamic envelopes, runtime invariants, bounded controller, and recovery planner.
+
+### ROS 2 integration
+
+`src/ohip_ros2/`
+
+ROS 2 force/torque ingestion, bounded motion publication, E-stop state, safety events, and joint-trajectory action client.
+
+### Hardware evidence
+
+`src/ohip_hil/`
+
+Measured HIL acceptance harness with explicit no-hardware semantics.
+
+### Evidence
+
+`src/ohip_evidence/`
+
+Tamper-evident evidence chaining and portable bundle verification.
+
+### XR
+
+`src/ohip_xr/` and `examples/webxr/`
+
+Safety-state payloads, local state server, and WebXR observer.
+
+### Simulation
+
+`src/ohip_sim/`
+
+Deterministic contact plant for controller regression tests. Simulation is clearly separated from physical evidence.
+
+### Existing runtime and interfaces
+
+- `src/ohip_runtime/`
+- `src/ohip_interfaces/`
+- `src/ohip_logging/`
+- `src/ohip_bench/`
+
+## Claim matrix
+
+| Capability | Implementation | Evidence in this repo |
+|---|---|---|
+| Safety-first protocol | YES | automated tests |
+| Consent-aware contact | YES | automated tests |
+| Force envelopes | YES | automated tests |
+| Tri-level hazards | YES | automated tests |
+| Vision pipeline | YES | executable RGB-D path |
+| Segmentation model | YES | model files + reproducible training + synthetic held-out metrics |
+| Vision-derived hazard maps | YES | executable projector + tests |
+| Independent model quorum | YES | disagreement tests |
+| Dynamic safety authority | YES | adversarial benchmark + tests |
+| Soft-real-time controller | YES | executable timing-instrumented controller + tests |
+| Recovery architecture | YES | deterministic recovery + tests |
+| ROS 2 bridge | YES | real ROS 2 code; runtime requires ROS 2 environment |
+| ROS 2 robot action client | YES | `FollowJointTrajectory` implementation; physical run not claimed |
+| WebXR observer | YES | actual browser WebXR client; headset validation not claimed |
+| Hardware F/T integration path | YES | ROS 2 `WrenchStamped` adapter; live device measurement not included |
+| Hardware tactile integration path | YES | normalized ROS 2 tactile-patch transport; live device measurement not included |
+| LLM/VLA safety broker | YES | untrusted proposal validation, multimodal fusion, deterministic receipt |
+| HIL harness | YES | executable harness |
+| HIL measured PASS | **NO** | requires physical hardware |
+| Physical robot execution evidence | **NO** | requires physical robot |
+| Certified robot safety | **NO** | requires applicable engineering, standards, and independent validation |
+
+## Why the final three NOs remain NO
+
+IX-HapticSight deliberately refuses to turn software simulation into physical evidence.
+
+A ROS 2 adapter can be complete without a robot being connected. A HIL harness can be complete without fabricated measurements. A controller can be executable without being certified hard real time.
+
+Those distinctions are part of the project, not missing marketing polish.
+
+## Responsible use and safety
+
+The MIT license is in `LICENSE`. `RESPONSIBLE_USE.md` is a separate statement of project intent and does not add contradictory license restrictions.
+
+Physical deployment should use hardware-specific safety engineering, independent emergency-stop mechanisms, calibrated sensing, watchdogs, robot limits, formal risk assessment, and the standards applicable to the actual system and environment.
+
+## Author
+
+Bryce Lovell
diff --git a/RESPONSIBLE_USE.md b/RESPONSIBLE_USE.md
new file mode 100644
index 0000000..4f87949
--- /dev/null
+++ b/RESPONSIBLE_USE.md
@@ -0,0 +1,16 @@
+# Responsible Use Statement
+
+IX-HapticSight is intended for safety-oriented robotics, human-robot interaction, assistive research, education, simulation, and industrial research.
+
+This statement expresses project intent. It is **not an additional software license restriction** and does not alter the MIT License in `LICENSE`.
+
+The project asks users to:
+
+- keep physical safety authority independent from learned or generative models;
+- retain force, speed, thermal, proximity, emergency-stop, and watchdog protections appropriate to the hardware;
+- obtain meaningful authorization or consent before human-facing contact where consent is applicable;
+- avoid weaponization, coercive physical interaction, or non-consensual surveillance applications;
+- preserve provenance and clearly distinguish simulation evidence from HIL or physical-robot evidence;
+- follow applicable robot-safety, workplace, privacy, legal, and institutional requirements.
+
+Physical deployment requires hardware-specific engineering and validation. The repository's software tests do not certify a robot, controller, facility, or use case.
diff --git a/ROADMAP.md b/ROADMAP.md
index 578e40a..021b4cc 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,253 +1,69 @@
# IX-HapticSight Roadmap
-This roadmap defines the planned upgrade path from the current reference implementation toward a stronger, more auditable, and more runtime-oriented safety stack for bounded optical-haptic interaction.
+IX-HapticSight is a safety-first perception-to-contact authority for robots and XR. The project keeps learned perception, planners, and LLMs outside the final physical safety authority.
-It is intentionally conservative.
+## M0: Protocol reference
+**Status: complete**
-The project is not represented as certified, clinically validated, production deployed, or regulator-approved. The roadmap describes engineering intent and repository milestones, not real-world deployment approval.
+Consent, state machine, contact planning, force envelopes, safety gating, retreat semantics, and core schemas.
----
+## M1: Auditable runtime
+**Status: complete**
-## Repository Mission
+Runtime coordination, explicit sessions/faults, normalized force/tactile/proximity/thermal interfaces, structured logging, replay, benchmark support, and simulated execution.
-IX-HapticSight is being developed as a safety-first optical-haptic interaction architecture for bounded human-facing robot behavior.
+## M2: Perception-to-hazard pipeline
+**Status: complete at reference-model level**
-The core project mission is to make these behaviors explicit, testable, and reviewable:
+RGB-D ingestion, executable segmentation, reproducible synthetic calibration training, independent model quorum, uncertainty handling, and vision-derived tri-level hazard voxels.
-- approach
-- pre-contact verification
-- bounded contact
-- retreat
-- safe hold
-- consent-aware interaction gating
-- hazard-aware veto behavior
-- auditable runtime policy evaluation
+**Remaining evidence:** field datasets, calibrated depth hardware, production segmentation models, adverse-lighting evaluation, occlusion benchmarks, and robot-specific camera calibration.
-The long-term direction is not broad social robotics.
-
-The long-term direction is a measurable interaction-governance stack with deterministic safety constraints.
-
----
-
-## Current Baseline
-
-The current repository already contains:
-
-- protocol schemas
-- consent logic
-- nudge scheduling logic
-- rest-pose generation
-- contact planning logic
-- safety gating logic
-- configuration files
-- example usage
-- baseline unit tests
-
-That is enough for a reference implementation, but not enough for a runtime-grade or evidence-backed package.
-
----
-
-## Upgrade Goals
-
-The upgrade campaign is designed to produce a stronger repository in the following areas:
-
-1. **Repository credibility**
- - cleaner project structure
- - clearer scope and non-claims
- - stronger contribution and review rules
- - more disciplined release notes and artifacts
-
-2. **Runtime architecture**
- - package separation by responsibility
- - runtime coordinator structure
- - ROS 2-compatible package layout
- - explicit interfaces and message models
-
-3. **Safety behavior**
- - stronger veto architecture
- - explicit fault handling
- - retreat semantics
- - stale-consent rejection
- - independent policy enforcement paths
-
-4. **Physical sensing interfaces**
- - force-torque input abstraction
- - tactile sensor input abstraction
- - proximity input abstraction
- - thermal input abstraction
- - contact-state fusion hooks
-
-5. **Evidence and replay**
- - structured logs
- - replay tooling
- - deterministic benchmark scenarios
- - simulation scene packs
- - hardware-in-the-loop scaffolding
-
-6. **Governance**
- - threat model artifacts
- - privacy and data handling docs
- - safety invariant traceability
- - standards crosswalk
- - safety-case starter materials
-
----
-
-## Planned Maturity Levels
-
-### M0 — Reference Prototype
-Status: approximately current state
-
-Characteristics:
-- pure Python reference modules
-- documentation-first posture
-- baseline configs and tests
-- no real runtime messaging layer
-- no tactile or hardware abstraction layer
-- no benchmark suite
-- no HIL scaffolding
-
-### M1 — Structured Repository
-Planned outcome:
-- stronger packaging
-- contribution and release hygiene
-- clarified roadmap, non-claims, and project boundaries
-- expanded project documentation
-
-Exit criteria:
-- repository structure is stable
-- upgrade plan is documented
-- contribution rules and release notes exist
-- package metadata is present
-
-### M2 — Modular Runtime Foundation
-Planned outcome:
-- logical package separation
-- runtime coordination interfaces
-- ROS 2 workspace and node scaffolding
-- message and service definitions
-- launch and configuration layering
-
-Exit criteria:
-- runtime module boundaries are explicit
-- state ownership is clearer
-- node lifecycle assumptions are documented
-- configuration loading is centralized
-
-### M3 — Safety-Grade Execution Layer
-Planned outcome:
-- motion execution adapter interfaces
-- collision and zone gating
-- retreat/abort logic
-- watchdog behavior
-- dual-path veto design
-- stronger fault handling tests
-
-Exit criteria:
-- execution boundaries are explicit
-- abort and retreat semantics are testable
-- safety behavior is separated from convenience behavior
-
-### M4 — Physical Signal Integration
-Planned outcome:
-- force-torque interfaces
-- tactile interfaces
-- proximity interfaces
-- thermal interfaces
-- contact-state fusion logic
-- simulated sensor fixtures
-
-Exit criteria:
-- the codebase can represent measured contact-related inputs
-- the planner and safety logic can consume those inputs without hidden assumptions
-
-### M5 — Evidence, Replay, and Benchmarking
-Planned outcome:
-- structured event logs
-- replay tooling
-- benchmark schemas
-- canonical scenarios
-- metrics reports
-- deterministic result packages
-
-Exit criteria:
-- behavior changes can be replayed
-- benchmark outputs are comparable
-- metrics are documented and reproducible
-
-### M6 — HIL and Safety Case Readiness
-Planned outcome:
-- hardware-in-the-loop scaffolding
-- calibration templates
-- fault injection templates
-- standards crosswalk
-- privacy and governance docs
-- safety invariant traceability matrix
-- safety-case starter pack
-
-Exit criteria:
-- the repository supports disciplined evidence collection
-- traceability exists between requirements, tests, and claims
-- governance artifacts exist for future review
-
----
-
-## What This Project Is Not
-
-The repository should not drift into claims it cannot support.
-
-It is not:
-
-- a certified collaborative robot package
-- a medical device
-- a therapy robot
-- a proven emotion-recognition engine
-- a production deployment stack
-- a substitute for hardware safety engineering
-- a substitute for legal, regulatory, or IRB review
-- a claim of socially correct behavior in all settings
-
----
-
-## Evidence Philosophy
-
-The strongest form of this project will rely on:
-
-- explicit requirements
-- deterministic safety behavior
-- replayable logs
-- bounded contact semantics
-- benchmark scenarios
-- hardware-in-the-loop evidence
-- traceable documentation
-
-Preference is always given to measured evidence over narrative claims.
-
----
-
-## Release Philosophy
-
-The planned release direction is:
-
-- v0.1.x: reference implementation baseline
-- v0.2.x: repository restructuring and modularization
-- v0.3.x: runtime and ROS 2 scaffolding
-- v0.4.x: sensing interfaces and execution safety expansion
-- v0.5.x: replay and benchmark package
-- v0.6.x: HIL scaffolding and safety-case preparation
-- v1.0.0: strong repository milestone, still bounded by explicit non-claims unless real evidence justifies more
-
----
-
-## Final Roadmap Rule
-
-Every major upgrade should improve at least one of these:
-
-- safety
-- clarity
-- testability
-- traceability
-- replayability
-- boundedness
-
-If it does not improve one of those, it should be treated as optional, not core.
+## M3: Independent physical safety authority
+**Status: complete at software reference level**
+
+Explicit `ALLOW`, `MODIFY`, and `DENY`; dynamic authority derating; consent enforcement; uncertainty stops; proximity stops; runtime invariant monitoring; force and speed clamping; deterministic recovery.
+
+**Remaining evidence:** hardware safety controller implementation, safety PLC/MCU partitioning, formal timing analysis, certified E-stop chain, and standards-specific validation.
+
+## M4: ROS 2 and controller integration
+**Status: implementation complete, hardware validation pending**
+
+Bounded ROS 2 twist bridge, `WrenchStamped` force/torque ingestion, E-stop state, structured safety side-channel, and `FollowJointTrajectory` action client.
+
+**Remaining evidence:** named robot/controller configuration, MoveIt Servo or equivalent integration, real robot joint limits, collision scene, calibration, and measured command/feedback latency.
+
+## M5: XR observability
+**Status: implementation complete, device validation pending**
+
+WebXR observer with live safety-authority state, hazard markers, consent state, force/speed authority, and controller state.
+
+**Remaining evidence:** headset-specific testing, spatial registration accuracy, user studies, and latency measurements.
+
+## M6: HIL evidence
+**Status: harness complete, measured evidence pending**
+
+The harness rejects synthetic HIL claims. A PASS requires positive hardware capability detection and measured samples meeting declared limits.
+
+**Exit criteria for a real HIL PASS:**
+- robot motion hardware present;
+- live force/torque source present;
+- time-synchronized measurements;
+- declared sample count reached;
+- force and latency limits not exceeded;
+- fault injection and recovery captured;
+- evidence bundle retained.
+
+## M7: Physical robot validation
+**Status: not yet claimed**
+
+Required work includes physical contact trials, diverse-object manipulation, human-proximity validation, measured recovery, controller stress testing, failure injection, sim-to-real comparison, and independent review.
+
+## M8: Production / certification track
+**Status: future**
+
+Hardware-specific safety case, applicable standards work, deployment controls, privacy review, cybersecurity, manufacturing constraints, and external validation.
+
+## Non-negotiable claim rule
+
+Simulation, software tests, ROS 2 adapter availability, and synthetic calibration do not become physical evidence by wording. IX-HapticSight should only claim what an artifact or measurement actually demonstrates.
diff --git a/VALIDATION_REPORT.md b/VALIDATION_REPORT.md
new file mode 100644
index 0000000..e984602
--- /dev/null
+++ b/VALIDATION_REPORT.md
@@ -0,0 +1,89 @@
+# IX-HapticSight v0.2.0 Validation Report
+
+**Validation date:** 2026-08-29
+**Environment:** Windows 11 / Python 3.13.2 local release verification; Linux / Python 3.13.5 artifact-preparation verification.
+**Evidence scope:** software tests, deterministic synthetic calibration, and simulation only unless explicitly stated otherwise.
+
+## Release verification
+
+Command:
+
+`python scripts/verify_release.py`
+
+Observed result:
+
+- Python compile check: PASS
+- automated test suite: **183 passed**
+- protocol quickstart: PASS, `SAFETY_OK: True`
+- perception-to-contact integration demo: PASS
+- tamper-evident evidence chain in integration demo: PASS
+- adversarial safety-authority benchmark: **8 / 8 scenarios passed**
+- overall software release verification: PASS
+
+## Reproducible perception-model evidence
+
+The test suite retrains both committed reference segmenters into a fresh temporary directory and requires the generated model and metrics files to match the committed artifacts byte-for-byte.
+
+Result: PASS.
+
+Evidence class: `SYNTHETIC_CALIBRATION`.
+
+This does not support a claim of production segmentation accuracy. The training data are deterministic synthetic calibration samples.
+
+## Randomized safety property evidence
+
+The suite evaluates 2,000 deterministic randomized authority proposals and verifies that the independent safety authority never grants force or speed above:
+
+- the requested force/speed;
+- the configured base force/speed caps;
+- zero when the disposition is `DENY`.
+
+Result: PASS.
+
+Evidence class: `SOFTWARE_TEST`.
+
+## ROS 2 evidence
+
+Implemented:
+
+- `WrenchStamped` force/torque ingestion;
+- normalized tactile patch ingestion;
+- E-stop input;
+- bounded `TwistStamped` output;
+- structured safety events;
+- `FollowJointTrajectory` action-client implementation.
+
+Validation environment does not contain `rclpy`. The repository explicitly raises `Ros2Unavailable` rather than substituting simulated hardware, and that behavior is tested.
+
+Physical ROS 2 robot validation: **NOT RUN**.
+
+## HIL evidence
+
+The HIL harness is implemented and tested. It refuses to report a PASS when required hardware is absent.
+
+Measured HIL PASS for this release: **NOT_RUN_NO_HARDWARE**.
+
+No synthetic measurement has been promoted to HIL evidence.
+
+## WebXR evidence
+
+Implemented:
+
+- local live safety-state feed;
+- 2D browser fallback;
+- WebXR `immersive-ar` session path;
+- `XRWebGLLayer`;
+- XR animation frame loop;
+- XR-space hazard marker rendering.
+
+Headset/device validation for this release: **NOT RUN**.
+
+## Physical robot evidence
+
+Physical robot execution PASS: **NOT CLAIMED**.
+
+The ROS 2 execution paths are code-complete reference integrations, but a physical manipulator, calibrated sensors, controller, and HIL rig are required before physical performance can be stated.
+
+## Claim boundary
+
+The v0.2.0 repository supports a strong claim of an executable, auditable perception-to-contact safety architecture. It does not support a claim that IX-HapticSight outperforms a deployed industrial robot in manipulation speed, object coverage, success rate, durability, or scale.
diff --git a/configs/culture_profiles.yaml b/configs/culture_profiles.yaml
index 67b3166..7c4c2a0 100644
--- a/configs/culture_profiles.yaml
+++ b/configs/culture_profiles.yaml
@@ -10,7 +10,7 @@
version: v0.1
updated: 2025-08-08
-author: Bryce Wooster
+author: Bryce Lovell
# -------------------------------------------------------------------
# Global defaults used when a field is omitted in a locale profile
diff --git a/configs/force_limits.yaml b/configs/force_limits.yaml
index 4c96dc2..08a26f2 100644
--- a/configs/force_limits.yaml
+++ b/configs/force_limits.yaml
@@ -5,7 +5,7 @@
version: v0.1
updated: 2025-08-08
-author: Bryce Wooster
+author: Bryce Lovell
# -------------------------------
# GLOBAL SAFETY TIMERS & RATES
diff --git a/docs/architecture/package_map.md b/docs/architecture/package_map.md
index 185b3c6..4dba510 100644
--- a/docs/architecture/package_map.md
+++ b/docs/architecture/package_map.md
@@ -1,351 +1,110 @@
# Package Map
-This document defines the planned package responsibilities for the IX-HapticSight upgrade path.
+IX-HapticSight v0.2 separates perception, policy, safety authority, execution, sensing, evidence, and validation so no learned model silently inherits actuator authority.
-It is written to separate stable protocol logic from runtime integration, sensing adapters, replay tooling, and benchmark infrastructure.
+## `src/ohip/`
-Where the current repository already has code, that is noted explicitly.
-Where a package is planned but not yet fully implemented, that is also noted explicitly.
+Protocol core:
+- canonical schemas;
+- consent management;
+- contact planning;
+- nudge scheduling;
+- rest pose generation;
+- legacy dual-channel safety gate.
----
+## `src/ohip_agent/`
-## 1. Current Package Baseline
+Untrusted agent/VLA boundary:
+- physical proposal schema;
+- strict numeric validation;
+- proposal SHA-256;
+- multimodal safety brokerage;
+- bounded decision receipts.
-The present repository has one core Python package:
+## `src/ohip_perception/`
-- `src/ohip/`
+Perception:
+- RGB-D frame normalization;
+- executable reference segmenters;
+- reproducible synthetic calibration training;
+- two-model quorum;
+- uncertainty and critical-disagreement handling;
+- vision-to-hazard projection.
-That package currently contains:
+## `src/ohip_control/`
-- `__init__.py`
-- `schemas.py`
-- `consent_manager.py`
-- `contact_planner.py`
-- `nudge_scheduler.py`
-- `rest_pose.py`
-- `safety_gate.py`
-
-This is a reasonable reference-implementation layout, but it mixes concerns that should eventually be separated for runtime clarity and long-term maintainability.
+Independent physical safety authority:
+- multimodal safety fusion;
+- `ALLOW` / `MODIFY` / `DENY` authority;
+- dynamic force/speed envelopes;
+- runtime invariant monitor;
+- bounded soft-real-time control kernel;
+- deterministic recovery planner.
----
+## `src/ohip_runtime/`
-## 2. Target Package Direction
+Session/runtime coordination:
+- interaction requests;
+- session state;
+- faults;
+- coordination decisions;
+- runtime service and session store.
-The long-term structure should preserve a small, understandable core and add adjacent packages for runtime, interfaces, replay, and benchmarking.
-
-The target direction is:
-
-- `src/ohip/`
-- `src/ohip_runtime/`
-- `src/ohip_interfaces/`
-- `src/ohip_logging/`
-- `src/ohip_bench/`
-- `src/ohip_ros2/`
-
-This does not mean all packages must become large immediately.
-It means responsibilities should stop collapsing into one directory as the repository grows.
-
----
-
-## 3. Planned Responsibility by Package
-
-### `src/ohip/`
-Purpose:
-- stable protocol definitions
-- canonical data models
-- policy structures
-- contact request semantics
-- shared enums and validation helpers
-- deterministic core logic that is runtime-agnostic
-
-Current modules already here:
-- `schemas.py`
-- `consent_manager.py`
-- `contact_planner.py`
-- `nudge_scheduler.py`
-- `rest_pose.py`
-- `safety_gate.py`
-
-Likely long-term contents:
-- `schemas.py`
-- `policy_models.py`
-- `interaction_state.py`
-- `consent_rules.py`
-- `contact_constraints.py`
-- `hazard_models.py`
-
-Rule:
-- this package should stay lightweight and not absorb runtime transport code
-
----
-
-### `src/ohip_runtime/`
-Purpose:
-- runtime orchestration
-- state ownership
-- coordinator logic
-- transition control
-- timeout handling
-- policy and safety evaluation sequencing
-- runtime-level fault handling
-
-Planned examples:
-- runtime coordinator
-- interaction session controller
-- state transition manager
-- fault latch manager
-- watchdog helpers
-
-Rule:
-- this package decides when things happen, not how hardware talks
-
----
-
-### `src/ohip_interfaces/`
-Purpose:
-- device-agnostic input/output interfaces
-- normalized sensor payloads
-- execution adapter contracts
-- runtime backend abstraction
-
-Planned subdomains:
-- force-torque interfaces
-- tactile interfaces
-- proximity interfaces
-- thermal interfaces
-- execution command interfaces
-
-Likely future modules:
-- `force_torque.py`
-- `tactile.py`
-- `proximity.py`
-- `thermal.py`
-- `execution_adapter.py`
-- `signal_health.py`
-
-Rule:
-- raw device-specific transport should not leak into core policy logic
-
----
-
-### `src/ohip_logging/`
-Purpose:
-- structured event logging
-- replay records
-- event serialization
-- audit bundle generation
-- trace export helpers
-
-Planned examples:
-- event schema definitions
-- log writers
-- replay session loaders
-- evidence bundle indexing
-- transition history formatting
-
-Rule:
-- logs must explain behavior without requiring a human to read unrelated console output
-
----
-
-### `src/ohip_bench/`
-Purpose:
-- benchmark scenario definitions
-- metrics collection
-- deterministic test harnesses
-- replayable benchmark execution
-- scenario result packaging
-
-Planned benchmark groups:
-- consent benchmarks
-- hazard benchmarks
-- contact benchmarks
-- retreat and veto benchmarks
-- logging/replay integrity benchmarks
-
-Rule:
-- benchmark logic should be independent from presentation docs and easy to re-run
-
----
-
-### `src/ohip_ros2/`
-Purpose:
-- ROS 2-specific node wrappers
-- ROS 2 message/service bridges
-- parameter handling integration
-- launch files
-- lifecycle integration scaffolding
-
-Planned examples:
-- lifecycle nodes
-- runtime coordinator node
-- consent node
-- safety node
-- contact planning bridge
-- replay publishing tools
-
-Rule:
-- ROS 2 integration should remain an adapter layer, not redefine protocol semantics
-
----
+## `src/ohip_interfaces/`
-## 4. Relationship Between Packages
+Backend-neutral sensing and execution contracts:
+- signal health/freshness;
+- force/torque;
+- tactile;
+- proximity;
+- thermal;
+- execution adapter;
+- simulated execution adapter.
-The dependency direction should be controlled.
+## `src/ohip_ros2/`
-Preferred dependency flow:
+Concrete ROS 2 integration:
+- `WrenchStamped` force/torque conversion;
+- normalized tactile patch transport;
+- E-stop input;
+- bounded `TwistStamped` output;
+- structured safety events;
+- `FollowJointTrajectory` action client.
-- `ohip`
- - has no dependency on ROS 2 packages
-- `ohip_runtime`
- - may depend on `ohip`
-- `ohip_interfaces`
- - may depend on `ohip`
-- `ohip_logging`
- - may depend on `ohip`
-- `ohip_bench`
- - may depend on `ohip`, `ohip_runtime`, and `ohip_logging`
-- `ohip_ros2`
- - may depend on `ohip`, `ohip_runtime`, and `ohip_interfaces`
+ROS 2 is optional at import time. Starting the bridge without ROS 2 installed fails explicitly rather than substituting simulation.
-Avoid the reverse where possible.
+## `src/ohip_sim/`
-In particular:
-- `ohip` should not depend on `ohip_ros2`
-- `ohip` should not depend on device transport libraries
-- `ohip` should not depend on benchmark harness code
+Deterministic software-only contact plant for controller regression. It is simulation evidence only.
-This keeps the protocol core portable and easy to test.
+## `src/ohip_hil/`
----
+Hardware-in-the-loop evidence harness. It cannot report PASS without declared required hardware and measured samples.
-## 5. Current-to-Target Mapping
+## `src/ohip_logging/`
-This section shows where existing modules are likely to remain or move conceptually.
+Structured runtime event logging and replay helpers.
-### `src/ohip/schemas.py`
-Current role:
-- canonical protocol data types
+## `src/ohip_evidence/`
-Likely future role:
-- remains in `ohip`
-- may be split into smaller files over time
+Tamper-evident evidence chain and portable evidence-bundle verifier.
----
+## `src/ohip_bench/`
-### `src/ohip/consent_manager.py`
-Current role:
-- consent evaluation logic
+Deterministic benchmark models, scenarios, reports, and adversarial safety-authority benchmark.
-Likely future role:
-- remains partially in `ohip`
-- runtime-facing orchestration may move to `ohip_runtime`
+## `src/ohip_xr/`
-Split concept:
-- rule evaluation stays in core
-- session/time handling moves to runtime
+XR safety-state payloads and local state server.
----
+## `examples/webxr/`
-### `src/ohip/contact_planner.py`
-Current role:
-- bounded contact decision logic
+Actual browser WebXR observer with XR-space hazard rendering plus desktop fallback.
-Likely future role:
-- core planning constraints remain in `ohip`
-- execution-bound planning orchestration may use `ohip_runtime`
-- hardware command translation belongs in interfaces or ROS 2 integration
+## `models/`
----
+Committed reference segmentation parameters and metrics. The current models are synthetic-calibration baselines, not production perception claims.
-### `src/ohip/nudge_scheduler.py`
-Current role:
-- schedule and timing logic for interaction
+## `tests/`
-Likely future role:
-- policy rules remain in `ohip`
-- runtime timers and callbacks move to `ohip_runtime`
-
----
-
-### `src/ohip/rest_pose.py`
-Current role:
-- rest and posture generation logic
-
-Likely future role:
-- posture target generation can remain in `ohip`
-- runtime delivery of poses belongs elsewhere
-
----
-
-### `src/ohip/safety_gate.py`
-Current role:
-- hazard and force gating logic
-
-Likely future role:
-- core safety decision rules remain in `ohip`
-- runtime watchdog, fault latching, and actuator abort routing live in `ohip_runtime`
-
----
-
-## 6. Why This Separation Matters
-
-The current repository is still small enough that everything in one package is understandable.
-
-That will stop being true once the project gains:
-
-- runtime coordinators
-- sensing adapters
-- message definitions
-- replay tooling
-- benchmark runners
-- ROS 2 nodes
-- HIL scaffolding
-
-Without separation, the result becomes harder to review and easier to break.
-
-With separation:
-- policy stays readable
-- runtime stays replaceable
-- interfaces stay swappable
-- evidence tooling stays organized
-
----
-
-## 7. Review Questions for New Package Work
-
-When adding or moving code, the reviewer should ask:
-
-1. Does this belong in the protocol core or in runtime plumbing?
-2. Does this code depend on a specific backend or transport?
-3. Could this logic be reused without ROS 2?
-4. Is this sensor-specific or policy-generic?
-5. Is this behavior needed at runtime, or only for replay or benchmarking?
-6. Does this change make the dependency graph cleaner or worse?
-
-If the answer is unclear, the default should be to keep the protocol core smaller.
-
----
-
-## 8. Near-Term Package Priorities
-
-The first package-growth priorities should be:
-
-1. preserve and stabilize `ohip`
-2. create `ohip_runtime` for orchestration
-3. create `ohip_interfaces` for sensing and execution boundaries
-4. create `ohip_logging` for structured event and replay artifacts
-5. create `ohip_bench` for benchmark harnesses
-6. add `ohip_ros2` after the previous boundaries are clear
-
-This order reduces confusion and prevents ROS-specific assumptions from leaking into everything else.
-
----
-
-## 9. Final Rule
-
-The package map should help the repository become easier to understand as it grows.
-
-If a package split adds ceremony without clarifying responsibility, it is premature.
-
-If a package split makes safety, runtime ownership, replay, or interface boundaries clearer, it is likely justified.
+Automated regression suite covering protocol, runtime, interfaces, perception, control, multimodal safety, agent brokerage, evidence integrity, ROS 2 contracts, HIL semantics, XR artifacts, and simulation.
diff --git a/docs/architecture/perception_to_contact_authority.md b/docs/architecture/perception_to_contact_authority.md
new file mode 100644
index 0000000..0ea20bd
--- /dev/null
+++ b/docs/architecture/perception_to_contact_authority.md
@@ -0,0 +1,43 @@
+# Perception-to-Contact Safety Authority
+
+The v0.2 architecture separates four forms of authority that are often accidentally mixed together in robot prototypes.
+
+1. **Perception authority:** a model may estimate what is present.
+2. **Task authority:** a planner or LLM may propose what the robot should attempt.
+3. **Safety authority:** deterministic logic independently decides what physical authority may be granted.
+4. **Execution authority:** a controller may execute only inside the granted force, speed, state, and timeout envelope.
+
+No layer is allowed to silently inherit a stronger authority from the layer above it.
+
+## Perception quorum
+
+Two independently trained reference models can inspect the same RGB-D frame. The quorum computes total agreement, critical-class disagreement, mean confidence, and uncertainty. Human, hot, liquid, and sharp disagreements are treated more strictly than ordinary background disagreement.
+
+The reference models are intentionally simple. The design point is the *quorum boundary*, not a claim that the supplied synthetic-calibration models are production vision.
+
+## Safety authority
+
+The independent authority emits one of three dispositions:
+
+- `ALLOW`: request already fits the current measured envelope.
+- `MODIFY`: action may proceed only after force and/or speed is reduced.
+- `DENY`: no physical authority is granted.
+
+The authority also emits a bounded counterfactual, for example that separation must increase, confidence must improve, or consent must be reacquired.
+
+## Cycle invariants
+
+After a decision is granted, the runtime still re-checks invariants every cycle. Permission is not permanent. Consent loss, stale sensors, unexpected measured force, perception disagreement, E-stop, or watchdog failure can terminate authority after motion has begun.
+
+## Recovery
+
+Recovery is explicit rather than left to learned policy behavior:
+
+- zero effort when already in problematic contact;
+- retract when safe motion away from the hazard is available;
+- safe hold when uncertainty or timing prevents a trustworthy retreat;
+- operator required for latched faults or E-stop.
+
+## Evidence
+
+Decisions and runtime transitions can be recorded into a SHA-256 evidence chain. The hash chain does not prove the physical truth of a sensor measurement, but it can detect later modification of recorded evidence.
diff --git a/docs/architecture/ros2_and_hardware.md b/docs/architecture/ros2_and_hardware.md
new file mode 100644
index 0000000..a6d3fc5
--- /dev/null
+++ b/docs/architecture/ros2_and_hardware.md
@@ -0,0 +1,18 @@
+# ROS 2 and Hardware Integration
+
+The v0.2 ROS 2 layer intentionally uses standard interfaces where possible.
+
+## Inputs
+
+- `geometry_msgs/WrenchStamped` for force/torque
+- `std_msgs/Bool` for E-stop state
+
+## Outputs
+
+- `geometry_msgs/TwistStamped` for already-bounded velocity commands
+- `std_msgs/String` structured safety side-channel
+- `control_msgs/FollowJointTrajectory` action client for standard trajectory controllers
+
+The safety authority should run upstream of these outputs. Robot-specific code may reduce authority further, but it may not expand force or speed above the granted envelope.
+
+ROS 2 is loaded lazily. A non-ROS machine can run the protocol, perception, control, evidence, simulation, and tests. Starting a ROS bridge without `rclpy` produces an explicit unavailable error rather than silently simulating hardware.
diff --git a/docs/architecture/webxr_observer.md b/docs/architecture/webxr_observer.md
new file mode 100644
index 0000000..8ec86a4
--- /dev/null
+++ b/docs/architecture/webxr_observer.md
@@ -0,0 +1,16 @@
+# WebXR Safety Observer
+
+The WebXR observer is an observability surface, not the safety authority itself.
+
+It displays:
+
+- safety-authority disposition;
+- force and speed caps;
+- consent state;
+- controller state;
+- veto or derating reason;
+- colored hazard markers.
+
+The included browser client requests an `immersive-ar` WebXR session when a compatible browser and device are available. The same page falls back to a 2D safety visualization when WebXR is unavailable.
+
+XR visualization latency and spatial registration are not assumed safe enough to close a physical control loop. Those require device-specific measured validation.
diff --git a/docs/benchmarks/metrics.md b/docs/benchmarks/metrics.md
index 2c99b32..31c07ee 100644
--- a/docs/benchmarks/metrics.md
+++ b/docs/benchmarks/metrics.md
@@ -268,7 +268,7 @@ These are still software-path metrics unless backed by real runtime measurements
This is where the metric system becomes much more serious.
-Once HIL scaffolding is connected to actual measurements, the benchmark/evidence layer should eventually support metrics like:
+Once the HIL harness is connected to actual measurements, the benchmark/evidence layer should eventually support metrics like:
### 7.1 Contact metrics
- peak measured force
diff --git a/docs/governance/standards_crosswalk.md b/docs/governance/standards_crosswalk.md
index c7d0aa1..b2a6554 100644
--- a/docs/governance/standards_crosswalk.md
+++ b/docs/governance/standards_crosswalk.md
@@ -406,12 +406,12 @@ It only means the repository is attempting to align its architecture and documen
The highest-value next steps are:
-1. add stronger tests for consent, veto, force limits, and state transitions
-2. create structured event and replay artifacts
-3. add benchmark scenario and metric definitions
-4. add integrity handling for critical configs
-5. add runtime boundary code that preserves policy/safety separation
-6. add HIL scaffolding and evidence templates
+1. extend measured hardware tests for consent, veto, force limits, and state transitions
+2. exercise the existing structured event and replay artifacts against HIL data
+3. expand benchmark scenarios with measured robot cases
+4. extend integrity handling to signed deployment configuration
+5. validate the implemented runtime boundary on a physical controller
+6. connect the implemented HIL harness to measured hardware evidence
Those steps would materially raise the maturity of the crosswalk.
diff --git a/docs/governance/threat_model.md b/docs/governance/threat_model.md
index e24a84e..62b3fe2 100644
--- a/docs/governance/threat_model.md
+++ b/docs/governance/threat_model.md
@@ -240,9 +240,9 @@ Mitigation direction:
Execution may involve:
- simulation backend
- test executor
-- future ROS 2 bridge
-- future motion-planning backend
-- future robot controller bridge
+- ROS 2 bridge
+- robot-specific motion-planning backend
+- robot controller bridge
Risk:
- backend ignores limits
diff --git a/docs/safety/requirements_traceability.md b/docs/safety/requirements_traceability.md
index e4c66c8..2e1b7a3 100644
--- a/docs/safety/requirements_traceability.md
+++ b/docs/safety/requirements_traceability.md
@@ -1,565 +1,42 @@
# Requirements Traceability Matrix
-This document defines the initial traceability matrix for IX-HapticSight as the repository evolves from a protocol-oriented reference implementation into a stronger runtime and evidence-oriented architecture.
-
-The purpose of this matrix is simple:
-
-- identify what the project claims
-- identify what each claim depends on
-- identify where that claim is implemented, documented, or tested
-- identify what evidence is still missing
-
-This document is intentionally conservative.
-A requirement is not considered satisfied merely because a concept appears in prose.
-A requirement should map to at least one of the following:
-
-- normative documentation
-- source code
-- test coverage
-- benchmark scenario
-- replay artifact
-- future hardware-in-the-loop evidence path
-
----
-
-## 1. Traceability Philosophy
-
-IX-HapticSight should prefer explicit traceability over vague assurance.
-
-A reviewer should be able to ask:
-
-- what is the requirement
-- where is it defined
-- where is it implemented
-- where is it tested
-- where is it logged
-- what evidence remains missing
-
-If that chain does not exist, the requirement is still immature.
-
----
-
-## 2. Status Labels
-
-This matrix uses the following status labels.
-
-### `IMPLEMENTED`
-There is code or documentation in the current repository that materially satisfies the requirement at the reference-implementation level.
-
-### `PARTIAL`
-Some evidence exists, but the requirement is not yet fully represented in code, tests, logging, or runtime behavior.
-
-### `PLANNED`
-The requirement is part of the intended architecture, but the current repository does not yet implement it in a meaningful way.
-
-### `EVIDENCE-GAP`
-The requirement is conceptually present, but meaningful evidence for it is not yet available.
-
----
-
-## 3. Current Baseline Artifacts
-
-Current repository artifacts relevant to traceability include:
-
-- `docs/spec.md`
-- `docs/state_machine.md`
-- `src/ohip/schemas.py`
-- `src/ohip/consent_manager.py`
-- `src/ohip/contact_planner.py`
-- `src/ohip/nudge_scheduler.py`
-- `src/ohip/rest_pose.py`
-- `src/ohip/safety_gate.py`
-- `tests/test_schemas.py`
-- `tests/test_nudge_scheduler.py`
-- `configs/force_limits.yaml`
-- `configs/culture_profiles.yaml`
-- `examples/quickstart.py`
-
-This matrix also references upgrade-era documents such as:
-
-- `docs/safety/invariants.md`
-- future benchmark, replay, runtime, and HIL artifacts that will be added later in the 72-commit campaign
-
----
-
-## 4. Requirement Matrix
-
-## RQ-001 — Canonical protocol data structures shall be defined in a stable, implementation-agnostic form.
-
-**Intent:**
-The project must have clear message/data structures for consent, safety semantics, contact planning, and execution logging so that implementations do not drift silently.
-
-**Primary references:**
-- `docs/spec.md`
-- `src/ohip/schemas.py`
-
-**Current implementation anchors:**
-- `src/ohip/schemas.py`
-
-**Current test anchors:**
-- `tests/test_schemas.py`
-
-**Logging/replay relevance:**
-- execution/event structures exist conceptually in schemas, but dedicated replay/logging tooling is not yet present
-
-**Status:**
-`IMPLEMENTED` at reference-implementation level
-
-**Evidence gap:**
-- no dedicated event-log package yet
-- no schema compatibility tests across runtime backends yet
-
----
-
-## RQ-002 — Human-facing contact shall require valid consent semantics or an explicitly documented non-contact-only mode.
-
-**Intent:**
-The system must not treat human contact as default-permitted behavior.
-
-**Primary references:**
-- `docs/spec.md`
-- `docs/state_machine.md`
-- `docs/safety/invariants.md`
-
-**Current implementation anchors:**
-- `src/ohip/consent_manager.py`
-- `src/ohip/contact_planner.py`
-
-**Current test anchors:**
-- indirect coverage may exist in behavior paths, but there is not yet a dedicated consent test suite in the current baseline
-
-**Logging/replay relevance:**
-- consent decisions are not yet captured through structured event logging
-
-**Status:**
-`PARTIAL`
-
-**Evidence gap:**
-- no dedicated unit tests for consent freshness and revocation
-- no replay artifact showing denial, revocation, or stale-consent behavior
-- no benchmark suite for consent edge cases yet
-
----
-
-## RQ-003 — Safety-map semantics shall distinguish GREEN, YELLOW, and RED conditions.
-
-**Intent:**
-The repository must preserve clear tri-level safety semantics for permitted, verify-first, and prohibited conditions.
-
-**Primary references:**
-- `docs/spec.md`
-- `src/ohip/schemas.py`
-
-**Current implementation anchors:**
-- `src/ohip/schemas.py`
-- `src/ohip/safety_gate.py`
-
-**Current test anchors:**
-- partial schema coverage in `tests/test_schemas.py`
-
-**Status:**
-`PARTIAL`
-
-**Evidence gap:**
-- no dedicated tests for hazard-to-veto behavior
-- no scenario suite validating RED intersection behavior
-- no runtime replay evidence yet
-
----
-
-## RQ-004 — A hard hazard or veto condition shall prevent or interrupt unsafe action.
-
-**Intent:**
-The system must preserve veto authority above convenience execution.
-
-**Primary references:**
-- `docs/spec.md`
-- `docs/state_machine.md`
-- `docs/safety/invariants.md`
-
-**Current implementation anchors:**
-- `src/ohip/safety_gate.py`
-- conceptual interaction flow in `examples/quickstart.py`
-
-**Current test anchors:**
-- no dedicated veto-path test file currently present in the baseline archive
-
-**Status:**
-`PARTIAL`
-
-**Evidence gap:**
-- no dedicated unit tests for hard-veto priority
-- no fault-injection or replay evidence
-- no independent runtime watchdog path yet
-
----
-
-## RQ-005 — The state machine shall define bounded interaction states and explicit recovery paths.
-
-**Intent:**
-The project must not rely on vague or hidden control flow for approach, contact, retreat, and safe-hold behavior.
-
-**Primary references:**
-- `docs/state_machine.md`
-- `docs/spec.md`
-
-**Current implementation anchors:**
-- distributed logically across:
- - `src/ohip/contact_planner.py`
- - `src/ohip/rest_pose.py`
- - `src/ohip/safety_gate.py`
- - `src/ohip/nudge_scheduler.py`
-
-**Current test anchors:**
-- no dedicated state-machine conformance tests in the present baseline
-
-**Status:**
-`PARTIAL`
-
-**Evidence gap:**
-- no transition-table tests
-- no invariant tests against the FSM
-- no replay of actual transition sequences
-
----
-
-## RQ-006 — Force-limited contact behavior shall remain bounded by configured limits.
-
-**Intent:**
-If contact is planned or executed, it must remain inside explicitly selected constraints.
-
-**Primary references:**
-- `docs/spec.md`
-- `configs/force_limits.yaml`
-- `docs/safety/invariants.md`
-
-**Current implementation anchors:**
-- `configs/force_limits.yaml`
-- `src/ohip/contact_planner.py`
-- `src/ohip/safety_gate.py`
-
-**Current test anchors:**
-- no dedicated force-limit validation tests in the current baseline
-
-**Status:**
-`PARTIAL`
-
-**Evidence gap:**
-- no force-profile selection tests
-- no overforce event tests
-- no measured evidence
-- no structured overforce logging yet
-
----
-
-## RQ-007 — Rest posture behavior shall be explicit and non-threatening when idle or after recovery.
-
-**Intent:**
-The system should maintain a clear and bounded idle/rest behavior rather than ambiguous hand motion.
-
-**Primary references:**
-- `docs/spec.md`
-- `src/ohip/rest_pose.py`
-
-**Current implementation anchors:**
-- `src/ohip/rest_pose.py`
-
-**Current test anchors:**
-- none currently visible in baseline tests
-
-**Status:**
-`PARTIAL`
-
-**Evidence gap:**
-- no posture validation tests
-- no scenario coverage for recovery-to-rest behavior
-- no runtime evidence or replay
-
----
-
-## RQ-008 — Engagement scheduling shall prioritize safer interaction opportunities and avoid unsafe targets.
-
-**Intent:**
-Scheduling logic should respect safety semantics and support deterministic prioritization.
-
-**Primary references:**
-- `docs/spec.md`
-- `src/ohip/nudge_scheduler.py`
-
-**Current implementation anchors:**
-- `src/ohip/nudge_scheduler.py`
-
-**Current test anchors:**
-- `tests/test_nudge_scheduler.py`
-
-**Status:**
-`IMPLEMENTED` at reference-implementation level
-
-**Evidence gap:**
-- no replayable benchmark pack for scheduler edge cases
-- no runtime coordination tests involving multiple simultaneous requests
-
----
-
-## RQ-009 — The repository shall support transparent auditing of important decisions and outcomes.
-
-**Intent:**
-A serious safety-first interaction stack must support review after the fact.
-
-**Primary references:**
-- `docs/spec.md`
-- `docs/safety/invariants.md`
-
-**Current implementation anchors:**
-- conceptual only through schemas and documentation
-
-**Current test anchors:**
-- none
-
-**Status:**
-`PLANNED`
-
-**Evidence gap:**
-- no structured event logger package
-- no replay tool
-- no evidence bundle format
-- no benchmark result schema package yet
-
----
-
-## RQ-010 — The repository shall preserve explicit non-claims and avoid overstating deployment readiness.
-
-**Intent:**
-Documentation must not imply certification, medical validation, or production safety that the repo does not actually support.
-
-**Primary references:**
-- `ROADMAP.md`
-- `docs/safety/invariants.md`
-
-**Current implementation anchors:**
-- currently mixed; some legacy docs still contain language that needs tightening
-
-**Current test anchors:**
-- not applicable as a code test in the current baseline
-
-**Status:**
-`PARTIAL`
-
-**Evidence gap:**
-- README and some legacy documentation still need harmonization
-- no release checklist enforcing non-claim language yet
-
----
-
-## RQ-011 — The project shall maintain backend-agnostic core logic.
-
-**Intent:**
-Core policy, consent, and safety behavior should remain portable rather than tightly bound to one transport or middleware.
-
-**Primary references:**
-- `docs/spec.md`
-- `docs/architecture/package_map.md`
-- `docs/architecture/runtime_overview.md`
-
-**Current implementation anchors:**
-- current `src/ohip/` package is Python-only and middleware-agnostic
-
-**Current test anchors:**
-- indirect through existing unit tests
-
-**Status:**
-`IMPLEMENTED` at current scale
-
-**Evidence gap:**
-- future ROS 2 integration must preserve this boundary
-- no compatibility checks across multiple runtimes yet
-
----
-
-## RQ-012 — Runtime execution shall eventually distinguish approval logic from backend command transport.
-
-**Intent:**
-Consent, safety, planning, and backend execution must not collapse into one hidden path.
-
-**Primary references:**
-- `docs/architecture/runtime_overview.md`
-- `docs/architecture/execution_adapter.md`
-- `docs/architecture/node_graph.md`
-
-**Current implementation anchors:**
-- not yet implemented as a dedicated code boundary
-
-**Current test anchors:**
-- none
-
-**Status:**
-`PLANNED`
-
-**Evidence gap:**
-- no execution adapter package yet
-- no runtime coordinator yet
-- no execution fault tests yet
-
----
-
-## RQ-013 — Sensor freshness and signal health shall be explicit once runtime sensing interfaces are added.
-
-**Intent:**
-The system must not pretend stale sensor data is trustworthy in a safety path.
-
-**Primary references:**
-- `docs/safety/invariants.md`
-- `docs/architecture/runtime_overview.md`
-
-**Current implementation anchors:**
-- not yet represented as dedicated interface modules in the baseline archive
-
-**Current test anchors:**
-- none
-
-**Status:**
-`PLANNED`
-
-**Evidence gap:**
-- no force-torque, tactile, proximity, or thermal interface packages yet
-- no stale-signal tests yet
-
----
-
-## RQ-014 — Structured logging and replay shall support after-action review and benchmark comparison.
-
-**Intent:**
-Important behavior should be inspectable without guesswork.
-
-**Primary references:**
-- `docs/architecture/runtime_overview.md`
-- `docs/architecture/node_graph.md`
-- `docs/safety/invariants.md`
-
-**Current implementation anchors:**
-- not yet implemented as code
-
-**Current test anchors:**
-- none
-
-**Status:**
-`PLANNED`
-
-**Evidence gap:**
-- no event schema package beyond conceptual schema structures
-- no replay loader/publisher
-- no result comparison tooling
-
----
-
-## RQ-015 — Benchmark scenarios shall become reproducible and tied to documented metrics.
-
-**Intent:**
-The project should be able to compare behavior across changes using consistent scenarios.
-
-**Primary references:**
-- `ROADMAP.md`
-- `docs/safety/invariants.md`
-- future benchmark docs
-
-**Current implementation anchors:**
-- not yet implemented as a benchmark package
-
-**Current test anchors:**
-- none
-
-**Status:**
-`PLANNED`
-
-**Evidence gap:**
-- no scenario catalog yet
-- no metrics collector
-- no benchmark runner
-- no benchmark report schema
-
----
-
-## RQ-016 — Future hardware-in-the-loop evidence should be traceable to repository requirements.
-
-**Intent:**
-If the project eventually gathers physical evidence, that evidence should map cleanly back to documented requirements.
-
-**Primary references:**
-- `ROADMAP.md`
-- `docs/safety/invariants.md`
-
-**Current implementation anchors:**
-- none yet; only planned architecture direction
-
-**Current test anchors:**
-- none
-
-**Status:**
-`EVIDENCE-GAP`
-
-**Evidence gap:**
-- no HIL fixture architecture yet
-- no calibration templates
-- no fault-injection templates
-- no evidence bundle structure yet
-
----
-
-## 5. Requirement-to-Artifact Summary Table
-
-| Requirement | Primary Focus | Current Code Anchor | Current Test Anchor | Status |
-|---|---|---|---|---|
-| RQ-001 | canonical schemas | `src/ohip/schemas.py` | `tests/test_schemas.py` | IMPLEMENTED |
-| RQ-002 | consent for contact | `src/ohip/consent_manager.py` | none dedicated yet | PARTIAL |
-| RQ-003 | GREEN/YELLOW/RED semantics | `src/ohip/schemas.py`, `src/ohip/safety_gate.py` | partial schema tests | PARTIAL |
-| RQ-004 | veto priority | `src/ohip/safety_gate.py` | none dedicated yet | PARTIAL |
-| RQ-005 | bounded state machine | distributed in `src/ohip/` | none dedicated yet | PARTIAL |
-| RQ-006 | force-limited contact | planner + safety + configs | none dedicated yet | PARTIAL |
-| RQ-007 | rest posture behavior | `src/ohip/rest_pose.py` | none dedicated yet | PARTIAL |
-| RQ-008 | deterministic scheduling | `src/ohip/nudge_scheduler.py` | `tests/test_nudge_scheduler.py` | IMPLEMENTED |
-| RQ-009 | transparent auditing | not yet dedicated | none | PLANNED |
-| RQ-010 | explicit non-claims | docs/roadmap layer | none | PARTIAL |
-| RQ-011 | backend-agnostic core | `src/ohip/` | indirect existing tests | IMPLEMENTED |
-| RQ-012 | execution boundary | planned docs only | none | PLANNED |
-| RQ-013 | signal freshness | planned docs only | none | PLANNED |
-| RQ-014 | replayability | planned docs only | none | PLANNED |
-| RQ-015 | benchmark reproducibility | planned docs only | none | PLANNED |
-| RQ-016 | HIL traceability | not yet present | none | EVIDENCE-GAP |
-
----
-
-## 6. Near-Term Traceability Priorities
-
-The next highest-value traceability improvements are:
-
-1. add dedicated consent tests
-2. add dedicated safety-veto tests
-3. add force-limit and overforce tests
-4. add state-transition conformance tests
-5. add structured event definitions for logging and replay
-6. add benchmark scenario and result schemas
-7. add HIL evidence folder structure and templates
-
-These will convert several `PARTIAL` and `PLANNED` requirements into something much stronger.
-
----
-
-## 7. Review Rule
-
-A new feature should not be considered mature unless it can answer four questions:
-
-1. what requirement does it satisfy
-2. where is that requirement documented
-3. where is it implemented
-4. where is it tested or otherwise evidenced
-
-If one of those links is missing, the feature is still incomplete.
-
----
-
-## 8. Final Note
-
-This matrix will need regular updates as the 72-commit campaign progresses.
-
-It is intended to become stricter over time, not looser.
-As runtime, sensing, replay, benchmark, and HIL artifacts are added, they should be inserted into this matrix rather than left as disconnected files.
+This matrix describes the v0.2.0 reference implementation. `IMPLEMENTED` means implemented and tested at the stated software level. It does not imply physical validation or certification.
+
+| ID | Requirement | Implementation anchors | Test / evidence anchors | Status | Remaining evidence |
+|---|---|---|---|---|---|
+| RQ-001 | Canonical protocol schemas | `src/ohip/schemas.py` | `tests/test_schemas.py` | IMPLEMENTED | interoperability/version migration across external implementations |
+| RQ-002 | Consent must gate contact where required | `src/ohip/consent_manager.py`, `src/ohip_control/authority.py` | consent + authority tests | IMPLEMENTED | human-subject/user-interface validation |
+| RQ-003 | RED hazards must deny physical authority | `src/ohip/safety_gate.py`, `src/ohip_control/authority.py` | adversarial benchmark, randomized authority property test | IMPLEMENTED | physical hazard-sensor validation |
+| RQ-004 | Learned/agent output may not enlarge deterministic limits | `src/ohip_agent/broker.py`, `src/ohip_control/envelope.py` | broker tests, 2,000-case randomized authority property test | IMPLEMENTED | external VLA/LLM integration trials |
+| RQ-005 | Vision shall produce explicit confidence/uncertainty | `src/ohip_perception/segmentation.py` | perception tests, reproducible model build | IMPLEMENTED | field dataset calibration |
+| RQ-006 | Independent perception disagreement shall be detectable | `src/ohip_perception/fusion.py` | quorum tests | IMPLEMENTED | independent production model families and field tests |
+| RQ-007 | Perception-derived hazards shall map to tri-level safety state | `src/ohip_perception/hazard_map.py` | hazard-map and pipeline tests | IMPLEMENTED | calibrated camera/depth geometry |
+| RQ-008 | Multimodal state shall be able to override vision | `src/ohip_control/multimodal.py` | multimodal fusion tests | IMPLEMENTED | live synchronized sensor streams |
+| RQ-009 | Force and speed requests shall be clamped or denied | `src/ohip_control/envelope.py`, `authority.py` | envelope, authority, benchmark, property tests | IMPLEMENTED | robot/controller measurements |
+| RQ-010 | Runtime shall re-check safety after initial authorization | `src/ohip_control/invariants.py`, `realtime.py` | controller/invariant tests | IMPLEMENTED | hard-real-time deployment and timing evidence |
+| RQ-011 | Recovery shall be explicit | `src/ohip_control/recovery.py` | controller/recovery tests | IMPLEMENTED | measured recovery trajectories |
+| RQ-012 | Backend transport shall remain downstream of safety authority | `src/ohip_interfaces/execution_adapter.py`, `src/ohip_ros2/` | adapter and ROS contract tests | IMPLEMENTED | robot-specific integration |
+| RQ-013 | Live F/T transport path shall exist | `src/ohip_ros2/messages.py`, `bridge.py` | ROS wrench converter tests | IMPLEMENTED | live force/torque hardware evidence |
+| RQ-014 | Live tactile transport path shall exist | `src/ohip_ros2/messages.py`, `bridge.py` | tactile converter tests | IMPLEMENTED | live tactile hardware evidence |
+| RQ-015 | Missing ROS runtime shall not silently become simulated hardware | `src/ohip_ros2/bridge.py` | `test_ros2_unavailable_is_explicit.py` | IMPLEMENTED | ROS 2 deployment test |
+| RQ-016 | HIL PASS shall require real declared hardware + measured samples | `src/ohip_hil/harness.py` | HIL harness tests | IMPLEMENTED | actual HIL run |
+| RQ-017 | Runtime evidence shall be tamper-evident | `src/ohip_evidence/` | hash-chain/bundle tamper tests | IMPLEMENTED | signed external timestamp/identity if required |
+| RQ-018 | Safety state shall be externally observable in XR | `src/ohip_xr/`, `examples/webxr/` | XR payload/static integration tests | IMPLEMENTED | headset registration/latency measurements |
+| RQ-019 | Simulation shall remain distinguishable from hardware evidence | `src/ohip_sim/`, HIL status model, docs claim matrix | HIL and simulation tests | IMPLEMENTED | process discipline in future reports |
+
+## Evidence classes
+
+Future evidence should be explicitly labeled:
+
+- `SOFTWARE_TEST`
+- `SYNTHETIC_CALIBRATION`
+- `SIMULATION`
+- `REPLAY`
+- `HIL_MEASURED`
+- `PHYSICAL_ROBOT_MEASURED`
+
+Only the final two may support physical performance claims.
+
+## Current release evidence gap
+
+The v0.2.0 software architecture is substantially implemented, but the repository does not contain a physical robot test or HIL PASS. That gap is intentional and visible.
diff --git a/docs/state_machine.md b/docs/state_machine.md
index aaced0f..db309da 100644
--- a/docs/state_machine.md
+++ b/docs/state_machine.md
@@ -200,6 +200,6 @@ Cooldowns never inhibit safety motion; only inhibit new social contact nudges.
10) Versioning
-FSM v0.1 corresponds to /docs/spec.md v0.1 and /src/ohip/* APIs OHIP_SCHEMAS_VERSION == v0.1.0.
+FSM v0.1 corresponds to /docs/spec.md v0.1 and /src/ohip/* APIs OHIP_SCHEMAS_VERSION == v0.2.0.
Breaking changes to states/transitions bump minor version.
diff --git a/docs/validation/claim_matrix.md b/docs/validation/claim_matrix.md
new file mode 100644
index 0000000..94d5091
--- /dev/null
+++ b/docs/validation/claim_matrix.md
@@ -0,0 +1,46 @@
+# v0.2.0 Claim Matrix
+
+This file is normative for release claims.
+
+## Software claims supported in repository
+
+- executable RGB-D perception path;
+- executable reference semantic segmentation;
+- reproducible synthetic calibration training;
+- two-model perception quorum;
+- vision-derived hazard voxels;
+- deterministic safety authority;
+- dynamic force/speed derating;
+- cycle-level runtime invariant monitoring;
+- bounded soft-real-time reference controller;
+- deterministic recovery;
+- ROS 2 bridge implementation;
+- standard joint-trajectory action-client implementation;
+- WebXR observer implementation;
+- executable HIL evidence harness;
+- tamper-evident evidence chain;
+- deterministic simulation and adversarial software benchmarks.
+
+## Claims not supported without external evidence
+
+- production perception accuracy;
+- HIL PASS;
+- physical robot execution PASS;
+- certified hard-real-time performance;
+- collaborative-robot certification;
+- safety certification;
+- human-subject validation;
+- production deployment reliability.
+
+## Evidence labeling rule
+
+Every future report should label its source as one of:
+
+- SOFTWARE_TEST
+- SYNTHETIC_CALIBRATION
+- SIMULATION
+- REPLAY
+- HIL_MEASURED
+- PHYSICAL_ROBOT_MEASURED
+
+Only the last two may support hardware-performance claims.
diff --git a/docs/validation/hardware_evidence_policy.md b/docs/validation/hardware_evidence_policy.md
new file mode 100644
index 0000000..336cf5b
--- /dev/null
+++ b/docs/validation/hardware_evidence_policy.md
@@ -0,0 +1,21 @@
+# Hardware Evidence Policy
+
+IX-HapticSight does not treat a mock, simulator, generated signal, or replay as hardware evidence.
+
+The HIL harness can report `PASSED` only when all required hardware capabilities are positively declared and the configured executor returns measured samples.
+
+A physical-robot evidence package should retain at minimum:
+
+- robot and controller identity;
+- sensor identity and calibration state;
+- software revision;
+- configuration hashes;
+- synchronized force/torque and motion timestamps;
+- commanded versus measured trajectories;
+- limit and watchdog events;
+- fault-injection cases;
+- recovery outcome;
+- evidence-chain manifest;
+- operator/test witness metadata where appropriate.
+
+The repository can prepare and verify that structure. It cannot manufacture the measurements.
diff --git a/docs/validation/v0.2.0-release-evidence.json b/docs/validation/v0.2.0-release-evidence.json
new file mode 100644
index 0000000..01aeb50
--- /dev/null
+++ b/docs/validation/v0.2.0-release-evidence.json
@@ -0,0 +1,38 @@
+{
+ "authority_benchmark": {
+ "passed": 8,
+ "total": 8
+ },
+ "date": "2026-08-29",
+ "evidence_classes_absent": [
+ "HIL_MEASURED",
+ "PHYSICAL_ROBOT_MEASURED"
+ ],
+ "evidence_classes_present": [
+ "SOFTWARE_TEST",
+ "SYNTHETIC_CALIBRATION",
+ "SIMULATION"
+ ],
+ "hil_measured": "NOT_RUN_NO_HARDWARE",
+ "integration_demo": {
+ "evidence_chain_verified": true,
+ "status": "PASS"
+ },
+ "physical_robot_execution": "NOT_CLAIMED",
+ "python": "3.13.5",
+ "quickstart": {
+ "safety_ok": true,
+ "status": "PASS"
+ },
+ "randomized_authority_cases": 2000,
+ "reference_model_reproducibility": "PASS_BYTE_FOR_BYTE",
+ "release": "0.2.0",
+ "ros2_runtime_validation": "NOT_RUN_RCLPY_NOT_INSTALLED",
+ "schema": "ixhs-release-evidence-v1",
+ "software_verification": "PASS",
+ "tests": {
+ "failed": 0,
+ "passed": 183
+ },
+ "webxr_device_validation": "NOT_RUN_NO_DEVICE"
+}
diff --git a/examples/perception_to_contact_demo.py b/examples/perception_to_contact_demo.py
new file mode 100644
index 0000000..cc1e808
--- /dev/null
+++ b/examples/perception_to_contact_demo.py
@@ -0,0 +1,93 @@
+"""End-to-end software demonstration for IX-HapticSight v0.2.
+
+The demo intentionally uses synthetic RGB-D calibration data and a simulated
+contact plant. It proves software integration, not physical robot validation.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from ohip.schemas import SafetyLevel
+from ohip_control import ActionProposal, BoundedRealtimeController, ControllerInput, IndependentSafetyAuthority
+from ohip_evidence import EvidenceChain
+from ohip_perception import PerceptionFrame, ReferenceSegmenter, VisionPipeline
+from ohip_sim import ContactWorld
+
+ROOT = Path(__file__).resolve().parents[1]
+primary = ReferenceSegmenter.from_file(ROOT / "models/reference_segmenter_primary.json")
+secondary = ReferenceSegmenter.from_file(ROOT / "models/reference_segmenter_secondary.json")
+pipeline = VisionPipeline(primary, secondary=secondary)
+
+# Person-colored target plus ordinary object. Synthetic input is explicit.
+frame = PerceptionFrame(
+ rgb=[[(178, 122, 94), (107, 117, 110)]],
+ depth_m=[[0.40, 1.20]],
+ timestamp_s=1.0,
+)
+perception = pipeline.process(frame)
+
+proposal = ActionProposal(
+ action_id="demo-contact",
+ requested_force_N=5.0,
+ requested_speed_mps=0.20,
+ base_force_cap_N=3.0,
+ base_speed_cap_mps=0.10,
+ safety_level=SafetyLevel.YELLOW,
+ perception_uncertainty=0.10,
+ perception_quorum_ok=bool(perception.agreement is None or perception.agreement.passed),
+ consent_required=True,
+ consent_active=True,
+ human_present=True,
+ proximity_m=0.40,
+)
+authority = IndependentSafetyAuthority().decide(proposal)
+
+chain = EvidenceChain()
+chain.append("perception", {
+ "safe_for_autonomy": perception.safe_for_autonomy,
+ "reason": perception.reason,
+ "hazard_count": len(perception.hazards),
+}, timestamp_s=1.0)
+chain.append("authority", {
+ "disposition": authority.disposition.value,
+ "force_N": authority.granted_force_N,
+ "speed_mps": authority.granted_speed_mps,
+ "reason": authority.reason,
+}, timestamp_s=2.0)
+
+controller = BoundedRealtimeController(target_period_ms=50.0)
+world = ContactWorld(surface_position_m=0.02)
+last = None
+for _ in range(120):
+ measured = 0.0 if last is None else last.measured_force_N
+ control = controller.step(ControllerInput(
+ requested_speed_mps=authority.granted_speed_mps,
+ requested_force_N=authority.granted_force_N,
+ measured_force_N=measured,
+ force_cap_N=authority.granted_force_N,
+ speed_cap_mps=authority.granted_speed_mps,
+ sensor_age_ms=1.0,
+ consent_active=True,
+ contact_requested=True,
+ perception_quorum_ok=True,
+ contact_detected=measured > 0.25,
+ ))
+ last = world.step(
+ command_velocity_mps=control.command_speed_mps,
+ force_cap_N=max(0.0, authority.granted_force_N),
+ dt_s=0.005,
+ )
+ if control.stop or control.latched:
+ break
+
+chain.append("control", {
+ "state": controller.state.value,
+ "measured_force_N": 0.0 if last is None else last.measured_force_N,
+ "latched": controller.latched,
+}, timestamp_s=3.0)
+
+print("PERCEPTION:", perception.reason)
+print("AUTHORITY:", authority.disposition.value, authority.reason)
+print("GRANTED:", round(authority.granted_force_N, 3), "N", round(authority.granted_speed_mps, 3), "m/s")
+print("CONTROLLER:", controller.state.value, "latched=", controller.latched)
+print("EVIDENCE_CHAIN:", chain.verify())
diff --git a/examples/webxr/index.html b/examples/webxr/index.html
new file mode 100644
index 0000000..033986d
--- /dev/null
+++ b/examples/webxr/index.html
@@ -0,0 +1,171 @@
+
+
+
+
+
+ IX-HapticSight WebXR Safety Observer
+
+
+
+