Skip to content

Commit 94a7b2d

Browse files
committed
[docs] define owned app connection teardown lifecycle
Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>
1 parent 6f70155 commit 94a7b2d

2 files changed

Lines changed: 33 additions & 0 deletions

File tree

‎docs/specifications/App/TDD.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -506,6 +506,38 @@ UI reads down (watch providers) and writes up (call `Connection` methods / DAO m
506506
- **Test compatibility:** a test overriding `connectionProvider` directly with a `FakeConnection` still **wins** (the override replaces the derived body), so the existing widget/golden suite (`shell_harness.pumpShell`) is untouched. New connect-flow tests inject `FakeScanner` + a `ConnectionFactory` returning `FakeConnection` + a fake `BleReadinessSource` through a `PbleConnectionManager`, or override `connectionManagerProvider` with a fake manager — no fake radio / fake `BleLink` needed (FR-CONN-7, D5).
507507
- The `ConnectController` (`Notifier`) projecting the manager into `ConnectState` for the connect surface lives in `lib/connect` ([§4.8](#48-libconnect--scanconnect-flow-ui)); it is the one place with the connect-flow intents.
508508

509+
**Owned-link teardown clarification (2026-09-06, FR-CONNECT-7).**
510+
511+
`PbleConnection.fromLink` owns the exact supplied `BleLink` and the
512+
`BleByteTransport` it constructs. Its first `dispose()` retires the connection,
513+
removes link/event listeners, aborts in-flight work, calls that link's
514+
`disconnect()` exactly once, and releases the owned byte adapter and protocol
515+
resources. Concurrent/repeated disposals await the same completion, including
516+
the same failure. Cleanup must still attempt the remaining resources if one
517+
step fails; preserve the first failure and its stack. A terminal HELLO failure
518+
on this owned-link path must close it, and a late HELLO/event must never publish
519+
`ready` or touch disposed notifiers. The direct `PbleConnection(engine: ...)`
520+
constructor retains its existing protocol-engine lifetime semantics but does
521+
not disconnect or dispose a caller-owned byte transport.
522+
523+
The manager retires its old facade binding before awaiting teardown, and waits
524+
for the old owned connection's close before opening a replacement. Every
525+
connect/disconnect/dispose intent invalidates earlier pending connect results.
526+
If an uncancellable factory returns a board after supersession, close that
527+
exact stale board once without attaching it or changing the current selected
528+
board, phase, or error. Failures from stale work remain with that operation;
529+
they must not overwrite a newer session. Manager disposal prevents new work,
530+
releases its streams/notifiers even on board-close failure, and is idempotent.
531+
No new wire command, permission flow, board identity gate, reset, version bump,
532+
or automatic connection retry is introduced by this clarification.
533+
534+
Host regressions must exercise the real HELLO-ready `PbleConnection` over a
535+
recording fake `BleLink`, including physical-disconnect call/state, shared
536+
dispose completion, late HELLO, cleanup failure, external transport ownership,
537+
replacement and late factory results after disconnect/disposal. Existing
538+
connection/facade and wire-conformance tests remain required. Host tests alone
539+
do not fill the physical ordinary-disconnect/reconnect rows on either tablet.
540+
509541
### 6.3 Single active writer / serialization
510542

511543
The app is one client to one board (SEC-2). `PbleConnection` serializes mutating operations (`runFile`/`runSource`/`putFile`/`delete`/`mkdir`/`rename`/`softReboot`) through an internal queue so commands cannot interleave; a `RUN` while running surfaces `EBUSY` as `EBusy` ([§14](#14-error-handling--mapping)) rather than corrupting state (FR-RUN-3). Read-only ops (`listDir`, `deviceInfo`) and `stop` are not blocked behind a long transfer beyond correctness.

‎docs/specifications/App/specs.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1002,6 +1002,7 @@ implementation:
10021002
- **FR-CONNECT-4** — The screen MUST list **saved boards** and reconnect them by remembered identifier; on link loss the app MUST auto-reattempt and in-flight transfers MUST resume per [protocol.md §5](../protocol.md#5-file-transfer-the-reliability-core). MUST (*source: PRD §8.1, §19.3, §13.1; verify: integration; story: A-03/A-22*)
10031003
- **FR-CONNECT-5** — The flow MUST be scan → connect → use only: no pairing-code step, no account, no session-lock/heartbeat, and no board-identity gating (the non-goals of [PRD §4.3](../prd.md)). MUST (*source: PRD §8.1, §9.6, §19.3, §4.3; verify: widget; story: A-22*)
10041004
- **FR-CONNECT-6** — The connect flow MUST refuse a board with an unsupported `proto_version` and prompt to update the firmware/app rather than failing silently. MUST (*source: PRD §18.3; verify: widget/integration; story: A-10/A-22*)
1005+
- **FR-CONNECT-7** — Ordinary Disconnect, replacement of the selected board, and disposal of an owned connection MUST close that connection's actual BLE link, not merely detach the UI. Teardown MUST be idempotent, abort pending protocol/transfer work and release owned subscriptions; a close failure MUST remain an error, not a successful physical-disconnect claim. A superseded or cancelled connection attempt MUST NOT publish its late result or disturb a newer session, and MUST close any link it eventually acquires. Direct engine-backed connections MUST NOT acquire ownership of externally supplied transports. MUST (*source: FR-BLE-4/5, FR-CONN-5/7, SEC-2; verify: actual protocol engine with recording fake links, manager races, real iPadOS/Android disconnect/reconnect HIL*)
10051006

10061007
**Connected Board-info identity slice — FROZEN (`[docs]` 2026-08-22, additive to FR-CONNECT-2).** The testable acceptance criteria are:
10071008

0 commit comments

Comments
 (0)