Skip to content

Commit 4b7489a

Browse files
BryceWDesignBryceWDesign
authored
Create package_map.md
1 parent 73c9002 commit 4b7489a

1 file changed

Lines changed: 351 additions & 0 deletions

File tree

‎docs/architecture/package_map.md‎

Lines changed: 351 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,351 @@
1+
# Package Map
2+
3+
This document defines the planned package responsibilities for the IX-HapticSight upgrade path.
4+
5+
It is written to separate stable protocol logic from runtime integration, sensing adapters, replay tooling, and benchmark infrastructure.
6+
7+
Where the current repository already has code, that is noted explicitly.
8+
Where a package is planned but not yet fully implemented, that is also noted explicitly.
9+
10+
---
11+
12+
## 1. Current Package Baseline
13+
14+
The present repository has one core Python package:
15+
16+
- `src/ohip/`
17+
18+
That package currently contains:
19+
20+
- `__init__.py`
21+
- `schemas.py`
22+
- `consent_manager.py`
23+
- `contact_planner.py`
24+
- `nudge_scheduler.py`
25+
- `rest_pose.py`
26+
- `safety_gate.py`
27+
28+
This is a reasonable reference-implementation layout, but it mixes concerns that should eventually be separated for runtime clarity and long-term maintainability.
29+
30+
---
31+
32+
## 2. Target Package Direction
33+
34+
The long-term structure should preserve a small, understandable core and add adjacent packages for runtime, interfaces, replay, and benchmarking.
35+
36+
The target direction is:
37+
38+
- `src/ohip/`
39+
- `src/ohip_runtime/`
40+
- `src/ohip_interfaces/`
41+
- `src/ohip_logging/`
42+
- `src/ohip_bench/`
43+
- `src/ohip_ros2/`
44+
45+
This does not mean all packages must become large immediately.
46+
It means responsibilities should stop collapsing into one directory as the repository grows.
47+
48+
---
49+
50+
## 3. Planned Responsibility by Package
51+
52+
### `src/ohip/`
53+
Purpose:
54+
- stable protocol definitions
55+
- canonical data models
56+
- policy structures
57+
- contact request semantics
58+
- shared enums and validation helpers
59+
- deterministic core logic that is runtime-agnostic
60+
61+
Current modules already here:
62+
- `schemas.py`
63+
- `consent_manager.py`
64+
- `contact_planner.py`
65+
- `nudge_scheduler.py`
66+
- `rest_pose.py`
67+
- `safety_gate.py`
68+
69+
Likely long-term contents:
70+
- `schemas.py`
71+
- `policy_models.py`
72+
- `interaction_state.py`
73+
- `consent_rules.py`
74+
- `contact_constraints.py`
75+
- `hazard_models.py`
76+
77+
Rule:
78+
- this package should stay lightweight and not absorb runtime transport code
79+
80+
---
81+
82+
### `src/ohip_runtime/`
83+
Purpose:
84+
- runtime orchestration
85+
- state ownership
86+
- coordinator logic
87+
- transition control
88+
- timeout handling
89+
- policy and safety evaluation sequencing
90+
- runtime-level fault handling
91+
92+
Planned examples:
93+
- runtime coordinator
94+
- interaction session controller
95+
- state transition manager
96+
- fault latch manager
97+
- watchdog helpers
98+
99+
Rule:
100+
- this package decides when things happen, not how hardware talks
101+
102+
---
103+
104+
### `src/ohip_interfaces/`
105+
Purpose:
106+
- device-agnostic input/output interfaces
107+
- normalized sensor payloads
108+
- execution adapter contracts
109+
- runtime backend abstraction
110+
111+
Planned subdomains:
112+
- force-torque interfaces
113+
- tactile interfaces
114+
- proximity interfaces
115+
- thermal interfaces
116+
- execution command interfaces
117+
118+
Likely future modules:
119+
- `force_torque.py`
120+
- `tactile.py`
121+
- `proximity.py`
122+
- `thermal.py`
123+
- `execution_adapter.py`
124+
- `signal_health.py`
125+
126+
Rule:
127+
- raw device-specific transport should not leak into core policy logic
128+
129+
---
130+
131+
### `src/ohip_logging/`
132+
Purpose:
133+
- structured event logging
134+
- replay records
135+
- event serialization
136+
- audit bundle generation
137+
- trace export helpers
138+
139+
Planned examples:
140+
- event schema definitions
141+
- log writers
142+
- replay session loaders
143+
- evidence bundle indexing
144+
- transition history formatting
145+
146+
Rule:
147+
- logs must explain behavior without requiring a human to read unrelated console output
148+
149+
---
150+
151+
### `src/ohip_bench/`
152+
Purpose:
153+
- benchmark scenario definitions
154+
- metrics collection
155+
- deterministic test harnesses
156+
- replayable benchmark execution
157+
- scenario result packaging
158+
159+
Planned benchmark groups:
160+
- consent benchmarks
161+
- hazard benchmarks
162+
- contact benchmarks
163+
- retreat and veto benchmarks
164+
- logging/replay integrity benchmarks
165+
166+
Rule:
167+
- benchmark logic should be independent from presentation docs and easy to re-run
168+
169+
---
170+
171+
### `src/ohip_ros2/`
172+
Purpose:
173+
- ROS 2-specific node wrappers
174+
- ROS 2 message/service bridges
175+
- parameter handling integration
176+
- launch files
177+
- lifecycle integration scaffolding
178+
179+
Planned examples:
180+
- lifecycle nodes
181+
- runtime coordinator node
182+
- consent node
183+
- safety node
184+
- contact planning bridge
185+
- replay publishing tools
186+
187+
Rule:
188+
- ROS 2 integration should remain an adapter layer, not redefine protocol semantics
189+
190+
---
191+
192+
## 4. Relationship Between Packages
193+
194+
The dependency direction should be controlled.
195+
196+
Preferred dependency flow:
197+
198+
- `ohip`
199+
- has no dependency on ROS 2 packages
200+
- `ohip_runtime`
201+
- may depend on `ohip`
202+
- `ohip_interfaces`
203+
- may depend on `ohip`
204+
- `ohip_logging`
205+
- may depend on `ohip`
206+
- `ohip_bench`
207+
- may depend on `ohip`, `ohip_runtime`, and `ohip_logging`
208+
- `ohip_ros2`
209+
- may depend on `ohip`, `ohip_runtime`, and `ohip_interfaces`
210+
211+
Avoid the reverse where possible.
212+
213+
In particular:
214+
- `ohip` should not depend on `ohip_ros2`
215+
- `ohip` should not depend on device transport libraries
216+
- `ohip` should not depend on benchmark harness code
217+
218+
This keeps the protocol core portable and easy to test.
219+
220+
---
221+
222+
## 5. Current-to-Target Mapping
223+
224+
This section shows where existing modules are likely to remain or move conceptually.
225+
226+
### `src/ohip/schemas.py`
227+
Current role:
228+
- canonical protocol data types
229+
230+
Likely future role:
231+
- remains in `ohip`
232+
- may be split into smaller files over time
233+
234+
---
235+
236+
### `src/ohip/consent_manager.py`
237+
Current role:
238+
- consent evaluation logic
239+
240+
Likely future role:
241+
- remains partially in `ohip`
242+
- runtime-facing orchestration may move to `ohip_runtime`
243+
244+
Split concept:
245+
- rule evaluation stays in core
246+
- session/time handling moves to runtime
247+
248+
---
249+
250+
### `src/ohip/contact_planner.py`
251+
Current role:
252+
- bounded contact decision logic
253+
254+
Likely future role:
255+
- core planning constraints remain in `ohip`
256+
- execution-bound planning orchestration may use `ohip_runtime`
257+
- hardware command translation belongs in interfaces or ROS 2 integration
258+
259+
---
260+
261+
### `src/ohip/nudge_scheduler.py`
262+
Current role:
263+
- schedule and timing logic for interaction
264+
265+
Likely future role:
266+
- policy rules remain in `ohip`
267+
- runtime timers and callbacks move to `ohip_runtime`
268+
269+
---
270+
271+
### `src/ohip/rest_pose.py`
272+
Current role:
273+
- rest and posture generation logic
274+
275+
Likely future role:
276+
- posture target generation can remain in `ohip`
277+
- runtime delivery of poses belongs elsewhere
278+
279+
---
280+
281+
### `src/ohip/safety_gate.py`
282+
Current role:
283+
- hazard and force gating logic
284+
285+
Likely future role:
286+
- core safety decision rules remain in `ohip`
287+
- runtime watchdog, fault latching, and actuator abort routing live in `ohip_runtime`
288+
289+
---
290+
291+
## 6. Why This Separation Matters
292+
293+
The current repository is still small enough that everything in one package is understandable.
294+
295+
That will stop being true once the project gains:
296+
297+
- runtime coordinators
298+
- sensing adapters
299+
- message definitions
300+
- replay tooling
301+
- benchmark runners
302+
- ROS 2 nodes
303+
- HIL scaffolding
304+
305+
Without separation, the result becomes harder to review and easier to break.
306+
307+
With separation:
308+
- policy stays readable
309+
- runtime stays replaceable
310+
- interfaces stay swappable
311+
- evidence tooling stays organized
312+
313+
---
314+
315+
## 7. Review Questions for New Package Work
316+
317+
When adding or moving code, the reviewer should ask:
318+
319+
1. Does this belong in the protocol core or in runtime plumbing?
320+
2. Does this code depend on a specific backend or transport?
321+
3. Could this logic be reused without ROS 2?
322+
4. Is this sensor-specific or policy-generic?
323+
5. Is this behavior needed at runtime, or only for replay or benchmarking?
324+
6. Does this change make the dependency graph cleaner or worse?
325+
326+
If the answer is unclear, the default should be to keep the protocol core smaller.
327+
328+
---
329+
330+
## 8. Near-Term Package Priorities
331+
332+
The first package-growth priorities should be:
333+
334+
1. preserve and stabilize `ohip`
335+
2. create `ohip_runtime` for orchestration
336+
3. create `ohip_interfaces` for sensing and execution boundaries
337+
4. create `ohip_logging` for structured event and replay artifacts
338+
5. create `ohip_bench` for benchmark harnesses
339+
6. add `ohip_ros2` after the previous boundaries are clear
340+
341+
This order reduces confusion and prevents ROS-specific assumptions from leaking into everything else.
342+
343+
---
344+
345+
## 9. Final Rule
346+
347+
The package map should help the repository become easier to understand as it grows.
348+
349+
If a package split adds ceremony without clarifying responsibility, it is premature.
350+
351+
If a package split makes safety, runtime ownership, replay, or interface boundaries clearer, it is likely justified.

0 commit comments

Comments
 (0)