Phase 2: Work-driven connection lifecycle (Approach B)

[itsniper]

Goal

Make work-driven link management the primary connection model: queue/work drives connect; idle teardown when quiet; reconnect Approach B; PoweredOn await—not silent no-ops.

PRD: Architecture (Connection model), FR-1.2 (Approach B parts), FR-1.4, FR-1.5, FR-8.6, FR-11, FR-9.2 (idle/hold logging)
Depends on: Phase 1 (Peripheral handle) — connect APIs live on the handle

High-level requirements

• Work-driven connect: when work requires a link, auto-connect without Advanced connect (full command queue may be stubbed until Phase 4; use an equivalent “work pending” / hold-for-work signal if commands are not yet present—implementation plan decides the interim hook, but product end-state is non-empty command queue).
• Idle disconnect: global config, default 5s, only when no pending work and no Advanced app hold (FR-1.5).
• Advanced app hold: Peripheral.connect(autoReconnect:) / disconnect() suppress idle while held; rare; Advanced docs (FR-11.2).
• Approach B reconnect:
  • Tier-0 on work-driven connects while linked; cancel on idle/intentional disconnect drops OS reconnect
  • Tier-1 armed only while work pending (or hold with reconnect); disarmed when quiet
  • Idle grace may allow one OS reconnect → re-cancel if still quiet
• PoweredOn (FR-1.4 / FR-8.6): scan/connect/work await usable radio; terminal states fail with typed errors; no silent scan no-op
• Single state machine for work-driven and Advanced connect (FR-11.4)
• Connection-state observation remains (FR-1.3.1 / FR-11.5)

Out of scope

• FR-10 discovery ready gate (Phase 3) — link restore/reconnect without GATT re-discover remains as today until Phase 3
• Full command queue / run-after-ready (Phase 4+)

Acceptance criteria

• Idle disconnect configurable globally, default 5s; does not fire while Advanced hold is set
• Advanced hold connect/disconnect documented and tested
• Work-driven path auto-connects when work requires a link (per interim or full queue hook)
• Tier-0 enabled on work-driven connect; cancelled on idle/intentional disconnect
• Tier-1 not left armed indefinitely with empty work and no hold
• Scan/connect no longer silently no-op when not PoweredOn; await or typed failure per FR-1.4
• Tests + DocC (Getting Started primary path vs Advanced hold)
• Logging for idle connect/disconnect and Advanced hold (FR-9.2)

Sub-issues

Planning/execution breakdown lives in child issues.

[itsniper]

Phase sequencing

Depends on: #50 (Peripheral handle + connect on handle).
Next: #52 (FR-10 discover-to-ready on ensure-linked path).

Sub-issues

• Phase 2a: PoweredOn await for scan/connect/work (FR-1.4, FR-8.6) #57 PoweredOn await
• Phase 2b: Idle disconnect (global default 5s) + Advanced app hold #58 Idle + Advanced hold
• Phase 2c: Approach B reconnect — Tier-0 while linked, Tier-1 while work pending #59 Approach B reconnect
• Phase 2d: Work-driven auto-connect when work requires a link #60 Work-driven auto-connect