[autodev] Step 13 partial: arch + module-layout cycle-1 sync

Item 1 of the deferred Step 13 refresh set per
_docs/02_document/ripple_log_cycle1.md.

architecture.md:
- Components C1: KltRansac is the cycle-1 operational default while
  AZ-332/AZ-333 are BLOCKED awaiting Tier-2 prerequisites; ADR-001 /
  ADR-002 unchanged (the seam holds; the selection shifted).
- Principle #3: same KltRansac note (cross-link to Components).
- § Technology Stack: OpenCV pin row reflects the cycle-1 relaxation
  to >=4.11.0.86,<4.12 with the leftover-file pointer; OKVIS2 + VINS-
  Mono rows note BLOCKED with AZ-592 / AZ-593 follow-ups.
- § NFR: Dependency CVE pinning row notes the relaxation and the
  CVE-2025-53644 re-validation owed before close.
- § ADR-001: cycle-1 operational note (KltRansac default; AZ-332/333
  facade-only; AZ-589/590 closed Won't-Fix).
- § ADR-009: new Cycle-1 implementation subsection covers
  _STRATEGY_REGISTRY + register_strategy (AZ-591) and the
  pre_constructed kwarg + build_pre_constructed (AZ-618 umbrella;
  Phases A-F including AZ-625 / AZ-687).

module-layout.md:
- shared/runtime_root entry: package layout (was single file in the
  Plan-era sketch); new public-surface table covering __init__.py,
  airborne_bootstrap.py, _replay_branch.py, and the per-component
  factory modules; ownership rows extended (AZ-591, AZ-618, AZ-625,
  AZ-687).

system-flows.md: intentionally not modified — F2 / F8 narratives are
at the component-flow abstraction level and do not reference
compose_root / pre_constructed mechanics, so they have not drifted.

Items 2-4 of the ripple-log refresh set (C1 description, the other
13 components, 8 helpers, tests/*.md) remain deferred to subsequent
sessions.

State: Step 13 stays in_progress; sub_step advanced to phase 6
(component-doc-updates).

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-19 16:35:12 +03:00
parent 4f122b604d
commit 1ca9a59b0b
3 changed files with 43 additions and 14 deletions
+9 -4
View File
@@ -397,10 +397,15 @@ Bootstrap reference: `_docs/02_tasks/todo/AZ-263_initial_structure.md`. Architec
### shared/runtime_root
- **File**: `src/gps_denied_onboard/runtime_root.py`
- **Purpose**: Composition root — config → strategy resolution → graph wiring (ADR-009). The ONLY place that may import concrete strategy classes across components. Per-binary CMake `BUILD_*` flags + composition root validator enforce ADR-002 build-time exclusion. Hosts `compose_root(config)` (airborne; serves both `config.mode == "live"` and `config.mode == "replay"` per ADR-011) and `compose_operator(config)` (operator-orchestrator). No separate `compose_replay` function — replay is a configuration of `compose_root`, not a sibling composition root.
- **Owned by**: AZ-263 (Bootstrap stub); per-component additions that wire a new strategy are owned jointly by the bootstrap epic and the consuming component task (touching `runtime_root.py` is allowed only via the explicit "wire-in" task in each component's epic). The replay-mode branch of `compose_root` is owned by AZ-401.
- **Consumed by**: the airborne binary entrypoint (live + replay modes), the operator-orchestrator binary entrypoint, and the research/comparative binary entrypoint.
- **Package**: `src/gps_denied_onboard/runtime_root/` (Python package; a single-file layout was the Plan-era sketch — cycle 1 grew it into a package because the airborne bootstrap, the registry seam, and the per-component factories each have non-trivial concerns and own their own tests).
- **Purpose**: Composition root — config → strategy resolution → graph wiring (ADR-009). The ONLY place that may import concrete strategy classes across components. Per-binary CMake `BUILD_*` flags + composition root validator enforce ADR-002 build-time exclusion.
- **Public surface (cycle-1)**:
- `__init__.py` — hosts `compose_root(config, *, pre_constructed=...)` (airborne; serves both `config.mode == "live"` and `config.mode == "replay"` per ADR-011) and `compose_operator(config)` (operator-orchestrator). Also owns the module-level `_STRATEGY_REGISTRY` dict, the `register_strategy(...)` API (AZ-591), and the `StrategyNotLinkedError` envelope. No separate `compose_replay` function — replay is a configuration of `compose_root`, not a sibling composition root.
- `airborne_bootstrap.py``register_airborne_strategies()` populates the 7 airborne strategy slots in `_STRATEGY_REGISTRY`; `build_pre_constructed(config)` builds the airborne 12-key infrastructure dict in 6 dependency-ordered phases (A→F); `AIRBORNE_REQUIRED_PRE_CONSTRUCTED_KEYS` is the documented per-component dependency map; `AirborneBootstrapError` envelope. See architecture.md § ADR-009 cycle-1 implementation note for the rationale.
- `_replay_branch.py` — replay-only frame source / FC adapter / clock / mavlink transport / replay sink wiring; merged over `pre_constructed` by `compose_root` (replay entries take precedence — they own the replay-only seam per ADR-011).
- Per-component factory modules (`c10_factory.py`, `c11_factory.py`, `c12_factory.py`, `clock_factory.py`, `fc_factory.py`, `frame_source_factory.py`, `inference_factory.py`, `matcher_factory.py`, `pose_factory.py`, `refiner_factory.py`, `rerank_factory.py`, `state_factory.py`, `storage_factory.py`, `vio_factory.py`, `vpr_factory.py`, `warm_start_wiring.py`, `spoof_recovery_sink.py`, `errors.py`) — each builds one component's strategies behind that component's `BUILD_*` flag gates.
- **Owned by**: AZ-263 (Bootstrap stub) for the package skeleton; AZ-591 owns `_STRATEGY_REGISTRY` + `register_strategy`; AZ-618 (umbrella → AZ-619..AZ-624) owns `airborne_bootstrap.py` + `build_pre_constructed` + per-phase seeds; AZ-625 owns the eager `(StateEstimator, ISam2GraphHandle)` build (Phase E.5); AZ-687 owns the replay-mode component-block guard. Per-component additions that wire a new strategy are owned jointly by the bootstrap epic and the consuming component task (touching the package is allowed only via the explicit "wire-in" task in each component's epic). The replay-mode branch of `compose_root` is owned by AZ-401.
- **Consumed by**: the airborne binary entrypoint (live + replay modes), the operator-orchestrator binary entrypoint, and the research/comparative binary entrypoint. Tests stub the registry via `clear_strategy_registry()` and the infrastructure dict via the same `pre_constructed=...` kwarg the production caller uses.
### shared/cli/replay