Skip to content

Commit 2ccd960

Browse files
BryceWDesignBryceWDesign
authored
Create execution_adapter.md
1 parent cf4b204 commit 2ccd960

1 file changed

Lines changed: 378 additions & 0 deletions

File tree

‎docs/architecture/execution_adapter.md‎

Lines changed: 378 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,378 @@
1+
# Execution Adapter Semantics
2+
3+
This document defines the planned execution adapter boundary for IX-HapticSight.
4+
5+
The project currently contains protocol and planning logic in `src/ohip/`, but it does not yet contain a dedicated runtime execution layer. This document describes the execution contract that should exist as the repository evolves into a stronger runtime-oriented architecture.
6+
7+
The purpose of the execution adapter is to keep bounded interaction logic separate from backend-specific command transport.
8+
9+
---
10+
11+
## 1. Why an Execution Adapter Exists
12+
13+
IX-HapticSight should not tie its core safety, consent, and contact-planning logic directly to one robot backend or simulator.
14+
15+
A dedicated execution adapter layer exists to:
16+
17+
- translate bounded plans into backend commands
18+
- enforce local execution constraints
19+
- report execution acknowledgements and failures
20+
- support abort and retreat behavior
21+
- isolate backend-specific details from protocol logic
22+
- allow simulation and hardware backends to share the same high-level behavior model
23+
24+
Without this boundary, backend assumptions leak into planning and safety code and make the repository harder to audit.
25+
26+
---
27+
28+
## 2. Scope of the Execution Adapter
29+
30+
The execution adapter is responsible for converting already-approved, already-bounded plans into executable steps.
31+
32+
It is **not** responsible for:
33+
34+
- deciding whether consent is valid
35+
- deciding whether contact is ethically allowed
36+
- deciding whether safety vetoes should be ignored
37+
- inventing new goals outside the approved plan
38+
- weakening hard limits for convenience
39+
40+
The execution adapter is allowed to reject an execution request if it cannot honor safety or backend constraints.
41+
42+
---
43+
44+
## 3. Upstream Dependencies
45+
46+
The execution adapter should receive input from runtime coordination and planning layers, not directly from raw operator intent.
47+
48+
Expected upstream sources:
49+
50+
- interaction coordinator
51+
- contact planner
52+
- retreat planner
53+
- safety evaluator
54+
- watchdog or fault manager
55+
56+
The execution adapter should assume that upstream layers have already performed:
57+
58+
- consent checks
59+
- policy checks
60+
- hazard evaluation
61+
- force-limit selection
62+
- basic bounded-plan generation
63+
64+
The adapter may still perform local validation before executing.
65+
66+
---
67+
68+
## 4. Planned Responsibilities
69+
70+
The execution adapter boundary should handle the following responsibilities.
71+
72+
### 4.1 Command translation
73+
Translate bounded motion or posture plans into backend-specific commands.
74+
75+
Examples:
76+
- joint targets
77+
- Cartesian pose targets
78+
- velocity-limited trajectories
79+
- retreat motions
80+
- safe-hold postures
81+
82+
### 4.2 Local validation
83+
Validate that a command is executable under current backend assumptions.
84+
85+
Examples:
86+
- missing target frame
87+
- target outside backend workspace model
88+
- invalid pose vector
89+
- backend unavailable
90+
- motion mode incompatible with requested action
91+
92+
### 4.3 Limit application
93+
Apply or verify execution-side constraints such as:
94+
95+
- velocity scaling
96+
- acceleration limits
97+
- jerk limits where supported
98+
- workspace constraints
99+
- backend collision-check mode selection
100+
- execution timeout bounds
101+
102+
### 4.4 Abort handling
103+
Accept and prioritize abort commands over normal execution flow.
104+
105+
Examples:
106+
- emergency stop request
107+
- hazard-induced abort
108+
- overforce abort
109+
- stale-signal abort
110+
- consent revocation
111+
112+
### 4.5 Retreat handling
113+
Accept retreat requests and execute a safe retreat or safe hold behavior.
114+
115+
Examples:
116+
- reverse out of contact zone
117+
- move to a predefined neutral posture
118+
- hold position if motion is unsafe
119+
- report inability to retreat if backend constraints prevent motion
120+
121+
### 4.6 Execution reporting
122+
Return structured execution status to the rest of the system.
123+
124+
Examples:
125+
- accepted
126+
- running
127+
- completed
128+
- partially completed
129+
- rejected
130+
- aborted
131+
- faulted
132+
- retreat complete
133+
- retreat failed
134+
135+
---
136+
137+
## 5. Planned Interface Contract
138+
139+
A future implementation may represent the adapter through a stable interface class.
140+
141+
A conceptual shape is:
142+
143+
- `can_execute(plan) -> ExecutionCheckResult`
144+
- `execute(plan) -> ExecutionStartResult`
145+
- `abort(reason) -> ExecutionAbortResult`
146+
- `retreat(plan, reason) -> ExecutionRetreatResult`
147+
- `get_status() -> ExecutionStatus`
148+
- `get_backend_capabilities() -> BackendCapabilities`
149+
150+
The exact code shape may change, but the semantic contract should remain stable.
151+
152+
---
153+
154+
## 6. Required Input Semantics
155+
156+
The adapter should only accept plans that are already explicit.
157+
158+
A valid execution request should include, or be able to derive:
159+
160+
- interaction/session identifier
161+
- plan identifier
162+
- target posture or motion segment
163+
- active force-limit profile identifier
164+
- speed or timing constraints
165+
- relevant frame metadata
166+
- plan class
167+
- execution mode
168+
- timeout or completion expectation
169+
- reason code for retreat or abort if applicable
170+
171+
A plan that lacks essential metadata should be rejected rather than guessed.
172+
173+
---
174+
175+
## 7. Required Output Semantics
176+
177+
The adapter should emit structured responses rather than free-form strings.
178+
179+
A useful execution response should include:
180+
181+
- status code
182+
- backend timestamp
183+
- execution identifier
184+
- acknowledgement state
185+
- failure reason if any
186+
- backend fault indicator
187+
- current motion mode
188+
- retreat state when relevant
189+
- whether the action is reversible
190+
- any downgraded execution condition
191+
192+
This supports replay, audit, and benchmark comparison later.
193+
194+
---
195+
196+
## 8. State Expectations
197+
198+
The execution adapter should maintain a minimal internal state model.
199+
200+
Recommended execution states:
201+
202+
- `IDLE`
203+
- `READY`
204+
- `EXECUTING`
205+
- `ABORTING`
206+
- `RETREATING`
207+
- `SAFE_HOLD`
208+
- `FAULTED`
209+
- `UNAVAILABLE`
210+
211+
These are backend-facing states, not the full interaction protocol state machine.
212+
213+
The runtime coordinator should not have to infer execution state from scattered backend logs.
214+
215+
---
216+
217+
## 9. Abort Semantics
218+
219+
Abort behavior must be clear and prioritized.
220+
221+
### Hard rule
222+
If a valid abort command is received, the adapter must stop normal execution flow as soon as backend behavior allows.
223+
224+
Abort reasons may include:
225+
- emergency stop
226+
- operator stop
227+
- overforce
228+
- hazard violation
229+
- thermal threshold exceedance
230+
- stale critical signal
231+
- execution watchdog timeout
232+
- consent revoked
233+
234+
The adapter should report:
235+
236+
- whether abort was acknowledged
237+
- whether motion ceased
238+
- whether the system entered safe hold
239+
- whether follow-on retreat is possible or blocked
240+
241+
Abort is not a soft suggestion.
242+
It is a mode change.
243+
244+
---
245+
246+
## 10. Retreat Semantics
247+
248+
Retreat is distinct from abort.
249+
250+
Abort means:
251+
- stop the current action
252+
253+
Retreat means:
254+
- execute a bounded movement away from the interaction zone or toward a safer configuration
255+
256+
A retreat request should include:
257+
- retreat reason
258+
- target retreat posture or path
259+
- speed bound
260+
- whether contact is currently active
261+
- whether a hold-before-retreat is required
262+
263+
If retreat cannot be completed, the adapter must report the failure clearly rather than silently falling back to undefined behavior.
264+
265+
---
266+
267+
## 11. Safety Boundary Rules
268+
269+
The adapter should never:
270+
271+
- expand force limits on its own
272+
- reinterpret a blocked command as allowed
273+
- initiate new contact not described in the plan
274+
- continue execution after a latched hard veto unless explicitly cleared by system logic
275+
- suppress execution faults from the event log
276+
277+
The adapter may be conservative and reject execution.
278+
It may not become permissive on its own.
279+
280+
---
281+
282+
## 12. Backend Replaceability Goal
283+
284+
The execution adapter boundary is intended to support multiple backends over time.
285+
286+
Examples:
287+
- pure simulation backend
288+
- local test backend
289+
- ROS 2 bridge
290+
- motion-planning backend
291+
- future physical robot controller bridge
292+
293+
The goal is that the planner and safety logic remain stable while the backend changes.
294+
295+
This keeps the repository architecture stronger and easier to test.
296+
297+
---
298+
299+
## 13. Logging Requirements
300+
301+
The execution adapter should emit structured events for:
302+
303+
- plan acceptance
304+
- plan rejection
305+
- execution start
306+
- execution completion
307+
- execution abort
308+
- retreat start
309+
- retreat completion
310+
- retreat failure
311+
- backend fault
312+
- degraded mode entry
313+
- backend unavailability
314+
315+
These events are important for:
316+
- replay tooling
317+
- benchmark scoring
318+
- debugging
319+
- safety-case traceability
320+
321+
---
322+
323+
## 14. Benchmark-Relevant Metrics
324+
325+
The execution adapter is a major source of runtime metrics.
326+
327+
Examples of useful metrics:
328+
- command acceptance latency
329+
- abort acknowledgement latency
330+
- retreat start latency
331+
- retreat completion time
332+
- execution rejection rate by reason
333+
- backend fault frequency
334+
- safe-hold entry count
335+
- partial execution incidence
336+
- timeout incidence
337+
338+
These metrics should eventually feed benchmark and evidence tooling.
339+
340+
---
341+
342+
## 15. Current Repository Implication
343+
344+
At the current repository stage, the execution adapter is still mostly conceptual.
345+
346+
The existing files that feed this future boundary are:
347+
348+
- `src/ohip/contact_planner.py`
349+
- `src/ohip/rest_pose.py`
350+
- `src/ohip/safety_gate.py`
351+
352+
Those files express what the system wants to do and what should be blocked.
353+
They do not yet provide a runtime-grade execution contract.
354+
355+
This document exists to keep that future contract disciplined before code growth makes the boundary muddy.
356+
357+
---
358+
359+
## 16. Review Questions for Adapter Code
360+
361+
When execution adapter code is added, reviewers should ask:
362+
363+
1. Does this code only execute already-approved plans?
364+
2. Does it preserve hard abort priority?
365+
3. Can it report failures in structured form?
366+
4. Does it avoid inventing policy decisions?
367+
5. Can it be replaced without rewriting the protocol core?
368+
6. Does it preserve replay and benchmark usefulness?
369+
370+
If the answer to any of those is no, the adapter design is drifting.
371+
372+
---
373+
374+
## 17. Final Rule
375+
376+
The execution adapter should be a narrow bridge, not a second brain.
377+
378+
Its job is to execute bounded intent safely, report what happened, and refuse what it cannot do without violating constraints.

0 commit comments

Comments
 (0)