Skip to content

Commit c5d6607

Browse files
committed
[docs] align multi-delete lifecycle contract
Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>
1 parent 69eefc2 commit c5d6607

4 files changed

Lines changed: 21 additions & 9 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,10 @@ its annotated tag rather than from the newer branch tip.
3636
identities, incomplete board listings, reconnect/session races, response
3737
resource exhaustion, slow-trickle requests, and public API retry deadlines,
3838
with adaptive, keyboard-accessible, localized, and golden-tested states.
39+
- Added session-bound multi-selection for eligible regular files shown in one
40+
board folder, with protected-path exclusion, exact confirmation, sequential
41+
fail-fast deletion, one reconciliation listing, and honest partial results.
42+
Folders retain their separate one-at-a-time empty-directory deletion.
3943
- Advanced the independently versioned app source build from `0.1.0+2` to
4044
`0.1.0+3`, distinguishing this development build from TestFlight build 2.
4145
- Advanced the independently versioned app source build from `0.1.0+3` to

‎docs/decisions/0043-session-bound-visible-file-multi-delete.md‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,10 @@ from PyBLE's Material design system and PBLE/1 contract.
3737
tap or keyboard activation toggles a checkbox instead of opening the file.
3838
The normal navigation, create, transfer, import, rename, delete, and
3939
Open-as-Blocks affordances are replaced by a contextual selected-count bar.
40-
Cancel, Escape, system Back, navigation, a replaced listing, Files disposal,
41-
disconnect, or connection-session replacement clears the selection.
40+
Cancel, Escape, system Back, navigation that hides the Files presentation, a
41+
replaced listing, Files disposal, disconnect, or connection-session
42+
replacement clears the selection. Changing Editor/Console centre focus while
43+
the landscape Files sidebar remains visible is not navigation away from Files.
4244

4345
3. **Select all means all eligible files currently shown.** It never claims to
4446
include entries omitted by a truncated board listing, folders, locked
@@ -63,8 +65,11 @@ from PyBLE's Material design system and PBLE/1 contract.
6365
6. **The controller validates before the first mutation.** It rejects an empty
6466
or unknown selection, duplicate or unsafe leaf, directory, reserved path,
6567
path outside the captured directory, and path over PBLE/1's 128-byte UTF-8
66-
ceiling without sending `FILE_DELETE`. It verifies the captured directory
67-
and session before the first command and again before every later command.
68+
ceiling without sending `FILE_DELETE`. Once a valid ordered batch exists, a
69+
local busy or stale-session refusal reports every path as unattempted; an
70+
empty or malformed request has no accepted path list. It verifies the
71+
captured directory and session before the first command and again before
72+
every later command.
6873

6974
7. **Deletion is sequential, fail-fast, and non-atomic.** The controller awaits
7075
one ordinary `Connection.delete(path)` before issuing the next. It stops on
@@ -76,9 +81,12 @@ from PyBLE's Material design system and PBLE/1 contract.
7681
8. **The result reports reality.** A result records exact succeeded paths, the
7782
failed/current path when present, exact unattempted paths, and the neutral
7883
localized failure kind. Complete success exits selection mode. A failed or
79-
partial result removes succeeded names from the selection, retains the
80-
unresolved names, and announces how many were deleted and remain. It never
81-
calls the batch transactional.
84+
partial result removes succeeded names from the selection, retains unresolved
85+
names that still exist in the reconciled listing, and announces how many were
86+
deleted and remain selected. A failed path absent from reconciliation remains
87+
recorded in the result but is not kept as a non-rendered selection ghost. A
88+
later selection edit dismisses rather than rewrites that terminal accounting.
89+
It never calls the batch transactional.
8290

8391
9. **Files refreshes once, and never refreshes a successor board.** After any
8492
`FILE_DELETE` was attempted—including a timeout whose board-side outcome may

‎docs/specifications/App/TDD.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1893,7 +1893,7 @@ Every verb wraps the typed `PbleException` ([§14.1](#141-status-byte--typed-exc
18931893

18941894
**Visible regular-file multi-delete — FROZEN (`[docs]` 2026-08-27, [ADR-0043](../../decisions/0043-session-bound-visible-file-multi-delete.md)).** `FilesView` owns a temporary selection of eligible shown direct regular-file names plus captured `cwd` and opaque session stamp. A labelled Select action or eligible-row long press enters; rows become checked toggles, Select all includes eligible shown files only, and Cancel/Escape/Back exits. Folders and locked entries never enter the set. The contextual bar replaces normal Files actions and uses a live selected count, destructive Delete, and item progress. One scrollable dialog presents the exact `cwd` and ordered names with Cancel focused before Delete.
18951895

1896-
`deleteMany` snapshots the controller's displayed order, rejects unknown/directory/unsafe/reserved/overlength names and a mismatched expected `cwd` or session before the first `Connection.delete`, then awaits each delete serially. A second batch receives a local `busy` failure and sends no verb. On the first typed error or session change it starts no later delete and returns exact succeeded/current/unattempted accounting. It performs no rollback or automatic retry. If at least one delete was issued, it calls `listDir(capturedCwd)` exactly once only while the captured session is current; a primary delete error wins over a reconciliation error. Complete success clears selection; failed/partial removes succeeded names, keeps unresolved names selected, focuses and announces one localized result, and leaves the refreshed listing visible. Folders retain the existing single empty-directory delete; there is no recursion or new PBLE opcode.
1896+
`deleteMany` snapshots the controller's displayed order, rejects duplicate/unknown/directory/unsafe/reserved/overlength names and a mismatched expected `cwd` or session before the first `Connection.delete`, then awaits each delete serially. A second valid batch receives a local `busy` failure, reports all of its ordered paths unattempted, and sends no verb. On the first typed error or session change it starts no later delete and returns exact succeeded/current/unattempted accounting. It performs no rollback or automatic retry. If at least one delete was issued, it calls `listDir(capturedCwd)` exactly once only while the captured session is current; a primary delete error wins over a reconciliation error. Complete success clears selection; failed/partial removes succeeded names, keeps still-rendered unresolved names selected, focuses and announces one localized result, and leaves the refreshed listing visible. Reconciliation cannot create a selected ghost for an absent failed path, and a later selection edit dismisses rather than mutates prior result accounting. Navigation that hides Files clears local selection even if an already-issued, non-cancellable board delete must finish; switching Editor/Console centre focus while the landscape Files sidebar remains visible does not hide it. Folders retain the existing single empty-directory delete; there is no recursion or new PBLE opcode.
18971897

18981898
**(e) Seam providers — `lib/app/providers.dart` (owner: app-architect).** Adds one Connection-derived provider beside `connectionProvider`/`connStateProvider`:
18991899

‎docs/specifications/App/specs.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,7 @@ The client implements the PBLE/1 wire contract; it references [protocol.md](../p
153153

154154
**Working-loop increment — FROZEN (A-30 subset · `[docs]` 2026-07-02, [ADR-0010](../../decisions/0010-working-loop-in-memory-document.md), [TDD §11.6](TDD.md#116-working-loop-provider-contract-frozen)).** In scope: `listDir` rooted at `fs_root` with into/up navigation, open-in-editor (`getFile` → editor buffer), upload-current-buffer (`putFile`), mkdir, delete, rename, `newFile`, continuous transfer progress + whole-file CRC success, typed-error → localized message, disabled-with-guidance while disconnected (FR-FILES-1/2/3/4/8, binding via the `Connection` seam only, CON-8). **Deferred:** export-to-device-storage **Download** (needs local persistence + a new dep — open-in-editor is the read-into-app path this increment). `.py`/data-only holds (FR-FILES-7, CON-3).
155155

156-
**Visible-file multi-delete — FROZEN (`[docs]` 2026-08-27, [ADR-0043](../../decisions/0043-session-bound-visible-file-multi-delete.md), [TDD §11.6](TDD.md#116-working-loop-provider-contract-frozen)).** A labelled Select action and eligible-file long press enter a contextual mode scoped to the exact shown direct regular files in one `cwd`; folders, descendants, firmware-reserved/control-plane paths, transfer scratch paths, and omitted/truncated entries are never selected. Select all means all eligible **shown files**. Tap/Space toggles instead of opening; normal navigation and mutation affordances are unavailable until Cancel/Escape/Back. One confirmation displays the exact folder and ordered filenames. The app then validates the captured `cwd`, paths, and opaque connection-session stamp, awaits ordinary `Connection.delete` calls sequentially, stops before the next path on the first failure/session change, never rolls back or retries, and refreshes the captured folder once only if the same session remains current. Complete, failed, and partial results truthfully identify succeeded, failed/current, and unattempted paths; unresolved files remain selected. Folders retain the existing one-at-a-time empty-directory delete and no recursive delete exists.
156+
**Visible-file multi-delete — FROZEN (`[docs]` 2026-08-27, [ADR-0043](../../decisions/0043-session-bound-visible-file-multi-delete.md), [TDD §11.6](TDD.md#116-working-loop-provider-contract-frozen)).** A labelled Select action and eligible-file long press enter a contextual mode scoped to the exact shown direct regular files in one `cwd`; folders, descendants, firmware-reserved/control-plane paths, transfer scratch paths, and omitted/truncated entries are never selected. Select all means all eligible **shown files**. Tap/Space toggles instead of opening; normal navigation and mutation affordances are unavailable until Cancel/Escape/Back. One confirmation displays the exact folder and ordered filenames. The app then validates the captured `cwd`, paths, and opaque connection-session stamp, awaits ordinary `Connection.delete` calls sequentially, stops before the next path on the first failure/session change, never rolls back or retries, and refreshes the captured folder once only if the same session remains current. Complete, failed, and partial results truthfully identify succeeded, failed/current, and unattempted paths; still-rendered unresolved files remain selected, while reconciliation never creates a selected ghost for an absent path. Navigation that hides Files clears selection without cancelling an already-issued board mutation. Folders retain the existing one-at-a-time empty-directory delete and no recursive delete exists.
157157

158158
### 4.6 Code Editor (`lib/editor/`) — FR-EDIT
159159

0 commit comments

Comments
 (0)