Add shared cross-surface control overlay contract

README.md

@@ -58,6 +58,7 @@ Documentation for the whole stack lives at
 | `ActionResult` | Execution outcome with error taxonomy + state delta |
 | `Episode` / `Step` | Complete task trajectory (observation → action → result) |
 | `FailureRecord` | Classified failure for dataset pipelines |
+| `ControlOverlayFrameV1` / `ControlOverlayTimelineV1` | PHI-safe execution overlay state bound to exact evidence media |
 
 ## Quick start
 
@@ -140,6 +141,23 @@ schema = ComputerState.model_json_schema()
 print(json.dumps(schema, indent=2))
 ```
 
+The same API exports the versioned cross-surface overlay contracts:
+
+```python
+from openadapt_types import ControlOverlayFrameV1, ControlOverlayTimelineV1
+
+frame_schema = ControlOverlayFrameV1.model_json_schema()
+timeline_schema = ControlOverlayTimelineV1.model_json_schema()
+```
+
+The same schemas ship as `openadapt_types/schemas/control-overlay-frame-v1.json`
+and `control-overlay-timeline-v1.json` for TypeScript, Rust, and other consumers.
+
+Overlay schemas reject unknown fields and contain only closed presentation
+labels and canonical statuses. Screenshots, action targets, typed values,
+identities, URLs, logs, report bodies, and user-authored workflow names remain
+outside this public presentation contract.
+
 ## Design principles
 
 - **Pydantic v2**: runtime validation, JSON Schema export, fast serialization

openadapt_types/__init__.py

@@ -39,6 +39,28 @@
     ProcessInfo,
     UINode,
 )
+from openadapt_types.control_overlay import (
+    CONTROL_OVERLAY_FRAME_SCHEMA,
+    CONTROL_OVERLAY_STATE_ID_COMPONENTS,
+    CONTROL_OVERLAY_STATUS_BY_PHASE,
+    CONTROL_OVERLAY_TERMINAL_PHASES,
+    CONTROL_OVERLAY_TIMELINE_SCHEMA,
+    CONTROL_OVERLAY_WORKFLOW_LABEL_BY_MODE,
+    ControlOverlayControlsV1,
+    ControlOverlayDataClassification,
+    ControlOverlayFrameV1,
+    ControlOverlayMode,
+    ControlOverlayPhase,
+    ControlOverlayProfile,
+    ControlOverlayStepV1,
+    ControlOverlayTimelineBindingV1,
+    ControlOverlayTimelineEventV1,
+    ControlOverlayTimelineV1,
+    ControlOverlayWorkflowLabel,
+    build_control_overlay_timeline,
+    control_overlay_state_id,
+    is_terminal_control_overlay_phase,
+)
 from openadapt_types.episode import Episode, Step
 from openadapt_types.failure import FailureCategory, FailureRecord
 from openadapt_types.parsing import (
@@ -58,6 +80,27 @@
     "ElementRole",
     "ProcessInfo",
     "UINode",
+    # control_overlay
+    "CONTROL_OVERLAY_FRAME_SCHEMA",
+    "CONTROL_OVERLAY_STATE_ID_COMPONENTS",
+    "CONTROL_OVERLAY_STATUS_BY_PHASE",
+    "CONTROL_OVERLAY_TERMINAL_PHASES",
+    "CONTROL_OVERLAY_TIMELINE_SCHEMA",
+    "CONTROL_OVERLAY_WORKFLOW_LABEL_BY_MODE",
+    "ControlOverlayControlsV1",
+    "ControlOverlayDataClassification",
+    "ControlOverlayFrameV1",
+    "ControlOverlayMode",
+    "ControlOverlayPhase",
+    "ControlOverlayProfile",
+    "ControlOverlayStepV1",
+    "ControlOverlayTimelineBindingV1",
+    "ControlOverlayTimelineEventV1",
+    "ControlOverlayTimelineV1",
+    "ControlOverlayWorkflowLabel",
+    "build_control_overlay_timeline",
+    "control_overlay_state_id",
+    "is_terminal_control_overlay_phase",
     # action
     "Action",
     "ActionResult",