# Runtime Interfaces

> Generated from repository source files. Do not edit this page directly; edit the source file listed below and rerun `vp run docs:generate`.

> Source: `system/runtime-interfaces.md`

## SAH-BRI-Grasp Runtime Interfaces

Status: `runtime binding draft`

This file defines implementation-facing interfaces for `SAH-BRI-Grasp`. It is a design specification, not an implementation and not an experimental result. Field names are stable enough for prototype planning, while thresholds, hardware values, and middleware choices remain `needs confirmation`.

## Evidence Boundary

* `YOLO-001` supports object detections with class, bounding box, and confidence.
* `SSVEP-003`, `SSVEP-004`, `SSVEP-005`, `SSVEP-007`, and `SSVEP-010` support SSVEP decoder baselines and protocol constraints in fixed-target settings.
* `MI-005`, `MI-006`, `MI-008`, and `BRI-004` support low-dimensional or high-level EEG/BRI control roles and no-control/delay constraints.
* `GRASP-001`, `GRASP-005`, `GRASP-006`, and `GRASP-007` support the boundary between object detection, grasp execution, hand-eye calibration, and robot-side visual servoing.
* `SA-001` and `SA-002` support shared-autonomy arbitration as a comparator and design rationale.

No field in this file validates project performance.

## Module Boundary

```text
VisionSource
  -> ObjectDetector
  -> CandidateManager
  -> StimulusRenderer
  -> EEGAcquisition
  -> SSVEPDecoder
  -> MIDecoder
  -> DecisionFusion
  -> RobotPlanner
  -> RobotExecutor
  -> VerificationAndRecovery
```

## Common Envelope

All runtime records should carry this envelope:

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `record_id` | string | system requirement | unique record identifier |
| `record_type` | string | system requirement | one of the record types in this file |
| `schema_version` | string | system requirement | start with `sah-bri-grasp-runtime-v0.1` |
| `sequence_index` | integer | system requirement | monotonic within a session log |
| `monotonic_ns` | integer | system requirement | primary timebase for latency analysis |
| `wall_time_iso8601` | string | system requirement | secondary human-readable time |
| `timestamp` | number/string | deprecated alias | keep only for compatibility with older sketches |
| `source_module` | string | system requirement | module that produced the record |
| `session_id` | string | system requirement | matches session record |
| `protocol_version` | string | system requirement | frozen before evidence-producing trials |
| `hardware_inventory_id` | string | needs confirmation | required for physical sessions |
| `run_mode` | enum | system requirement | dry\_run / replay / simulation / physical |
| `input_record_ids` | string\[] | system requirement | upstream record links, empty at source |

## Runtime Binding Decisions

These decisions are fixed for the next implementation draft and can be revised only by changing `schema_version`.

| Decision | Binding | Status |
| --- | --- | --- |
| canonical event log | `data/runtime/<session_id>/events.jsonl` | draft frozen |
| message serialization | newline-delimited JSON objects matching this file | draft frozen |
| middleware | file-first canonical log; ROS/local process buses may mirror records as adapters | draft frozen |
| record ID rule | `<record_type>_<session_id>_<sequence_index>` with zero-padded six-digit sequence index | draft frozen |
| primary timebase | `monotonic_ns` from the logging host | draft frozen |
| wall-clock field | ISO-8601 string with timezone offset in `wall_time_iso8601` | draft frozen |
| multi-host synchronization | requires a session-level sync record with method and estimated error bound before evidence-producing trials | needs confirmation |
| replay rule | replay consumes the same JSONL records and writes a separate replay log without rewriting original record IDs | draft frozen |
| physical-robot rule | physical motion requires `run_mode = physical`, valid hardware inventory, calibration record, threshold freeze record, and preflight pass | system requirement |

## Vision Frame

Produced by `VisionSource`.

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `frame_id` | string/int | system requirement | unique frame identifier |
| `camera_id` | string | needs confirmation | from hardware inventory |
| `rgb_image_ref` | string | system requirement | local path, buffer handle, or stream reference |
| `depth_image_ref` | string/null | needs confirmation | required if grasp-pose method needs depth |
| `intrinsics_id` | string | needs confirmation | camera intrinsics record |
| `camera_pose_hint` | object/null | needs confirmation | optional external pose estimate |

## Object Detection

Produced by `ObjectDetector`.

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `detection_id` | string | system requirement | unique detection ID |
| `frame_id` | string/int | system requirement | source frame |
| `class_label` | string | inferred from `YOLO-001` | object category |
| `confidence` | number | inferred from `YOLO-001` | detector confidence; threshold not fixed |
| `bbox_xywh` | number\[4] | inferred from `YOLO-001` | image-space bounding box |
| `mask_ref` | string/null | needs confirmation | optional instance mask |
| `depth_summary` | object/null | needs confirmation | optional depth statistics |
| `detector_id` | string | needs confirmation | model/version/weights |

## Candidate

Produced by `CandidateManager` from one or more detections.

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `candidate_id` | string | system requirement | stable selectable object ID |
| `track_id` | string | needs confirmation | persistent object track |
| `source_detection_ids` | string\[] | system requirement | detections used to create/update candidate |
| `class_label` | string | inferred | copied or fused from detector |
| `bbox_xywh` | number\[4] | inferred | current selectable box |
| `candidate_score` | number | needs confirmation | detector/tracking/fusion score |
| `stability_score` | number | needs confirmation | jitter/loss-derived score |
| `lost` | boolean | system requirement | candidate unavailable or occluded |
| `last_seen_timestamp` | number/string | system requirement | target-loss analysis |
| `grasp_affordance_ref` | string/null | needs confirmation | optional grasp-pose candidate source |

## Candidate Freeze Set

Produced by `CandidateManager` and consumed by `StimulusRenderer`.

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `freeze_set_id` | string | system requirement | set used for one selection period |
| `candidate_ids` | string\[] | system requirement | selectable candidates |
| `freeze_started_at` | number/string | system requirement | start time |
| `freeze_duration_s` | number | needs confirmation | must be frozen before data collection |
| `layout_id` | string | needs confirmation | screen/AR layout |
| `candidate_box_geometry` | object | needs confirmation | pixel and visual-angle geometry |
| `target_lost_policy` | enum | needs confirmation | pause / keep / cancel / refreeze |

## Stimulus Binding

Produced by `StimulusRenderer`.

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `binding_id` | string | system requirement | unique stimulus binding |
| `freeze_set_id` | string | system requirement | candidate set being stimulated |
| `candidate_id` | string | system requirement | bound candidate |
| `stimulus_code` | string | needs confirmation | frequency/phase/code label |
| `frequency_hz` | number/null | needs confirmation | SSVEP frequency if used |
| `phase_rad` | number/null | needs confirmation | phase if used |
| `render_geometry` | object | needs confirmation | position, size, visual angle |
| `display_id` | string | needs confirmation | display hardware |

## EEG Window

Produced by `EEGAcquisition`.

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `eeg_window_id` | string | system requirement | unique window ID |
| `channel_set_id` | string | needs confirmation | exact electrode set |
| `start_timestamp` | number/string | system requirement | window start |
| `duration_s` | number | needs confirmation | frozen before session |
| `sampling_rate_hz` | number | needs confirmation | hardware/preprocessing dependent |
| `preprocessing_id` | string | needs confirmation | filter/epoch pipeline |
| `data_ref` | string | system requirement | local path or buffer handle |
| `quality_flags` | string\[] | needs confirmation | artifact/contact flags |

## SSVEP Decision

Produced by `SSVEPDecoder`.

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `ssvep_decision_id` | string | system requirement | unique decoder output |
| `eeg_window_id` | string | system requirement | source EEG window |
| `binding_id` | string/null | system requirement | matched stimulus binding |
| `predicted_candidate_id` | string/null | system requirement | selected candidate or null |
| `decoder_id` | string | needs confirmation | CCA/FBCCA/TRCA/other |
| `confidence` | number | needs confirmation | decoder confidence |
| `accepted` | boolean | system requirement | after confidence/consistency gate |
| `rejection_reason` | string/null | system requirement | low confidence, conflict, artifact, etc. |

## MI Decision

Produced by `MIDecoder`.

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `mi_decision_id` | string | system requirement | unique decoder output |
| `eeg_window_id` | string | system requirement | source EEG window |
| `predicted_command` | enum | inferred | confirm / cancel / pause / stop / rest / no\_control |
| `decoder_id` | string | needs confirmation | CSP/FBCSP/EEGNet/other |
| `confidence` | number | needs confirmation | decoder confidence |
| `accepted` | boolean | system requirement | after no-control and confidence gate |
| `rejection_reason` | string/null | system requirement | low confidence, no-control, conflict, artifact, etc. |

## Fused Intent

Produced by `DecisionFusion`.

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `intent_id` | string | system requirement | unique fused decision |
| `state_before` | string | system requirement | state-machine source state |
| `state_after` | string | system requirement | state-machine destination |
| `selected_candidate_id` | string/null | system requirement | chosen object if any |
| `requested_action` | enum | system requirement | select / confirm / cancel / pause / stop / plan / execute / recover |
| `ssvep_decision_id` | string/null | system requirement | linked SSVEP evidence |
| `mi_decision_id` | string/null | system requirement | linked MI evidence |
| `fusion_policy_id` | string | needs confirmation | arbitration policy version |
| `confidence_summary` | object | needs confirmation | decoder and safety confidence |
| `safety_gate_result` | object | system requirement | pass/fail and reasons |

## Robot Plan

Produced by `RobotPlanner`.

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `plan_id` | string | system requirement | unique plan ID |
| `intent_id` | string | system requirement | source fused intent |
| `candidate_id` | string | system requirement | target candidate |
| `grasp_method_id` | string | needs confirmation | geometric, GGCNN-like, Dex-Net-like, etc. |
| `calibration_record_id` | string | needs confirmation | required for physical robot |
| `target_pose_ref` | string/null | needs confirmation | object/grasp pose estimate |
| `pregrasp_pose_ref` | string/null | needs confirmation | safe approach pose |
| `trajectory_ref` | string/null | needs confirmation | planned path |
| `planning_status` | enum | system requirement | planned / rejected / failed |
| `failure_reason` | string/null | system requirement | unreachable, collision, invalid transform, etc. |

## Robot Execution

Produced by `RobotExecutor`.

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `execution_id` | string | system requirement | unique execution ID |
| `plan_id` | string | system requirement | source plan |
| `robot_mode` | enum | needs confirmation | simulation / replay / physical |
| `started_at` | number/string | system requirement | execution start |
| `ended_at` | number/string/null | system requirement | execution end |
| `execution_status` | enum | system requirement | not\_started / running / completed / aborted / safety\_stopped |
| `safety_gate_triggered` | string/null | system requirement | gate name if stopped |
| `operator_override` | boolean | system requirement | manual stop/intervention |
| `result_ref` | string/null | needs confirmation | execution log or telemetry |

## Verification Result

Produced by `VerificationAndRecovery`.

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `verification_id` | string | system requirement | unique verification output |
| `execution_id` | string | system requirement | source execution |
| `task_success` | boolean/null | needs confirmation | criterion must be frozen |
| `grasp_success` | boolean/null | needs confirmation | criterion must be frozen |
| `target_still_visible` | boolean/null | needs confirmation | vision-based check |
| `failure_mode` | string/null | system requirement | failure taxonomy |
| `recovery_action` | enum/null | system requirement | retry / refreeze / pause / abort / none |

## Safety Gate Result

Any module may emit a safety gate result.

| Field | Type | Status | Notes |
| --- | --- | --- | --- |
| `gate_id` | string | system requirement | unique gate output |
| `gate_name` | string | system requirement | confidence, target\_loss, transform, collision, etc. |
| `input_record_ids` | string\[] | system requirement | records checked |
| `passed` | boolean | system requirement | gate result |
| `severity` | enum | system requirement | info / warning / block / emergency |
| `reason` | string | system requirement | concise reason |
| `threshold_record_id` | string | needs confirmation | frozen threshold source |
| `next_state` | string | system requirement | state-machine target |

## Implementation Rules

1. Treat all thresholds as configuration loaded from a threshold-freeze record.
2. Log every rejected decision and safety-blocked action.
3. Preserve links from trial logs to runtime records.
4. Do not execute physical robot motion without a valid calibration record and safety gates.
5. Keep detector success, BCI selection success, robot planning success, and grasp success as separate outcomes.
6. Version every decoder, detector, fusion policy, calibration, and grasp method.