Skip to content

Commit 3766aaa

Browse files
committed
[docs] freeze visible file multi-delete
Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>
1 parent 9f384c1 commit 3766aaa

7 files changed

Lines changed: 206 additions & 15 deletions

File tree

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# ADR-0043 — Bind visible-file multi-delete to one board session
2+
3+
- Status: **Accepted**
4+
- Date: 2026-08-27
5+
- Extends: [ADR-0010](0010-working-loop-in-memory-document.md)
6+
7+
## Context
8+
9+
The connected Files surface can delete one board entry after one confirmation,
10+
while FR-FILES-5 has kept multi-select bulk operations deferred. Deleting
11+
several files is useful for examples and classroom cleanup, but PBLE/1 exposes
12+
only one `FILE_DELETE` command per path. It has no batch transaction, rollback,
13+
recursive delete, or delete cancellation. A connection loss can also replace
14+
the live board behind the app's stable `Connection` facade.
15+
16+
A bulk UI must therefore avoid implying that the operation is atomic or that a
17+
confirmation from one board session remains valid for another. It must also
18+
avoid selecting the PyBLE control plane or transfer scratch files that the
19+
firmware workspace jail rejects.
20+
21+
The requested interaction may use familiar multi-selection behavior, but its
22+
source, identifiers, copy, visuals, state model, and tests are authored fresh
23+
from PyBLE's Material design system and PBLE/1 contract.
24+
25+
## Decision
26+
27+
1. **The first bulk-delete increment selects visible regular files only.** One
28+
selection contains eligible direct file children of the current Files
29+
directory. It never includes descendants or the directory itself. Folders
30+
retain the existing one-at-a-time deletion behavior, under which only an
31+
empty folder can be removed. Recursive deletion is not introduced or
32+
implied.
33+
34+
2. **Selection is explicit, local, and temporary.** A labelled Select action is
35+
the discoverable entry point; long-pressing an eligible file is an optional
36+
shortcut that enters selection and selects that row. In selection mode, a
37+
tap or keyboard activation toggles a checkbox instead of opening the file.
38+
The normal navigation, create, transfer, import, rename, delete, and
39+
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.
42+
43+
3. **Select all means all eligible files currently shown.** It never claims to
44+
include entries omitted by a truncated board listing, folders, locked
45+
entries, or descendants. Activating it while every eligible shown file is
46+
selected clears the selection. The accessible label states “shown files.”
47+
48+
4. **Firmware-reserved entries are locked before selection.** Relative to the
49+
board-reported `fs_root`, a lowercase top-level component beginning `pyble`
50+
or `pble`, exact top-level `boot.py` or `_boot.py`, and any component ending
51+
`.pbltmp` are non-editable. The predicate is case-sensitive and mirrors the
52+
PBLE/1 workspace jail. Such rows expose no open, rename, delete, Blocks, or
53+
bulk-selection action and are excluded from Select all. Ordinary files such
54+
as root `main.py`, and a `pyble*` basename below an ordinary child folder,
55+
remain eligible.
56+
57+
5. **One confirmation names one immutable intent.** Before deletion, the app
58+
shows the exact current board folder and every selected filename in stable
59+
display order, states that removal is permanent, and initially focuses the
60+
non-destructive action. Confirming captures the current directory, exact
61+
ordered direct-child paths, and opaque local connection-session stamp.
62+
63+
6. **The controller validates before the first mutation.** It rejects an empty
64+
or unknown selection, duplicate or unsafe leaf, directory, reserved path,
65+
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+
69+
7. **Deletion is sequential, fail-fast, and non-atomic.** The controller awaits
70+
one ordinary `Connection.delete(path)` before issuing the next. It stops on
71+
the first typed failure or session change. Confirmed earlier successes are
72+
never rolled back, and failed or unattempted paths are never retried
73+
automatically. Parallel `Future.wait`, recursion, and a new PBLE opcode are
74+
not used.
75+
76+
8. **The result reports reality.** A result records exact succeeded paths, the
77+
failed/current path when present, exact unattempted paths, and the neutral
78+
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.
82+
83+
9. **Files refreshes once, and never refreshes a successor board.** After any
84+
`FILE_DELETE` was attempted—including a timeout whose board-side outcome may
85+
be uncertain—the controller lists the captured directory once if and only if
86+
the captured session is still current. A primary delete failure remains the
87+
visible error even if that reconciliation also fails. If every delete
88+
succeeded, a reconciliation failure is surfaced separately through the
89+
existing file-error mapping.
90+
91+
10. **The UI remains adaptive and accessible.** The contextual bar uses the
92+
Signal selected-count and destructive colors; selected rows use
93+
`surfaceContainerHigh`; controls remain at least 48 dp. The bar and exact
94+
confirmation scroll or reflow in a narrow Files pane and at 2× text without
95+
clipping. Selected counts and partial results are live regions; focus moves
96+
into selection, never defaults to destructive confirmation, and returns to
97+
Select after cancel or completion. While deletion is active, selection and
98+
Files mutations are locked and item progress remains visible.
99+
100+
11. **Delivery remains spec-first and test-driven.** Controller tests prove
101+
validation, stable sequential order, no overlap, first-failure accounting,
102+
no rollback, one refresh, session replacement, and a concurrent-batch
103+
refusal. Widget, semantics, keyboard, and golden tests prove discoverable
104+
selection, shown-file Select all, protected/folder exclusion, exact
105+
confirmation, cancel-with-zero-I/O, partial truth, focus recovery, narrow
106+
panes, high contrast, and 2× text. Physical iPad and board acceptance is
107+
required before the feature's pull request is opened.
108+
109+
## Consequences
110+
111+
- Users can remove several board files with one review and confirmation.
112+
- Folders remain deliberately non-recursive and cannot be selected in this
113+
first bulk increment.
114+
- A late failure can leave an honestly reported partial deletion because
115+
PBLE/1 has no transaction or safe rollback.
116+
- The controller performs one final listing instead of one listing per file,
117+
reducing BLE round trips while preserving reconciliation.
118+
- Control-plane and scratch files become visibly locked in Files rather than
119+
relying only on a later firmware `EACCES` response.
120+
121+
## Alternatives considered
122+
123+
- **Call the existing single-delete method in a loop.** Rejected because it
124+
refreshes after every item, swallows the typed exception needed for partial
125+
accounting, and cannot prevent later deletes after failure.
126+
- **Delete files in parallel.** Rejected because PBLE/1 has one serialized
127+
mutation stream and parallel calls obscure deterministic failure accounting.
128+
- **Include folders or recursively delete trees.** Rejected for this increment:
129+
PBLE/1 removes only empty directories and supplies no recursive transaction.
130+
- **Roll back earlier successes.** Rejected because recreating deleted bytes is
131+
impossible without downloading and retaining every file, and a compensating
132+
write could overwrite a concurrent board change.
133+
- **Keep selection in the shared controller state.** Rejected because selection
134+
is presentation-local and must disappear when the Files presentation is
135+
disposed; the controller owns only the validated batch execution and result.
136+
137+
## Related
138+
139+
- [App requirements §4.5](../specifications/App/specs.md#45-workspace-file-explorer-libfiles--fr-files)
140+
- [App TDD §4.5](../specifications/App/TDD.md#45-libfiles--workspace-file-explorer)
141+
- [PBLE/1 file transfer §5](../specifications/protocol.md#5-file-transfer-the-reliability-core)
142+
- [Signal Files chrome §7.13](../specifications/App/design-system.md#713-files-pane-chrome-fr-files-tdd-45--84)
143+
144+
<!-- SPDX-License-Identifier: MIT -->

‎docs/decisions/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,5 +46,6 @@ Each ADR captures one significant decision: its context, the choice, and the con
4646
| [0040](0040-sha-pinned-connected-github-import.md) | Ship GitHub import first as a SHA-pinned, bounded connected-board subset while durable local files and provenance remain deferred | Accepted |
4747
| [0041](0041-separate-official-examples-repository.md) | Maintain the official user-facing runnable examples in a separately governed repository while PyBLE retains only its importer fixtures and bundled offline examples | Accepted |
4848
| [0042](0042-prefill-official-examples-and-discover-branches.md) | Prefill the editable official examples repository and provide bounded, branch-only discovery while retaining advanced explicit refs | Accepted |
49+
| [0043](0043-session-bound-visible-file-multi-delete.md) | Bind visible regular-file multi-delete to one board session with sequential fail-fast execution and honest partial results | Accepted |
4950

50-
Decided 2026-06-30 (0001–0005); 0006 accepted 2026-07-01; 0007, 0008, 0009 and 0010 accepted 2026-07-02; 0011 accepted 2026-07-03; 0012 accepted 2026-07-25; 0013 accepted 2026-07-27; 0014, 0015, 0016, and 0017 accepted 2026-07-28; 0018–0022 accepted 2026-07-29; 0023 and 0024 accepted 2026-08-01; 0025 and 0026 accepted 2026-08-02; 0027–0029 accepted 2026-08-03; 0030 accepted 2026-08-11; 0031–0033 accepted 2026-08-12; 0034 accepted 2026-08-13; 0035 and 0036 accepted 2026-08-16; 0037 and 0038 accepted 2026-08-20; 0039 accepted 2026-08-21; 0040 accepted 2026-08-22; 0041 accepted 2026-08-25; 0042 accepted 2026-08-27.
51+
Decided 2026-06-30 (0001–0005); 0006 accepted 2026-07-01; 0007, 0008, 0009 and 0010 accepted 2026-07-02; 0011 accepted 2026-07-03; 0012 accepted 2026-07-25; 0013 accepted 2026-07-27; 0014, 0015, 0016, and 0017 accepted 2026-07-28; 0018–0022 accepted 2026-07-29; 0023 and 0024 accepted 2026-08-01; 0025 and 0026 accepted 2026-08-02; 0027–0029 accepted 2026-08-03; 0030 accepted 2026-08-11; 0031–0033 accepted 2026-08-12; 0034 accepted 2026-08-13; 0035 and 0036 accepted 2026-08-16; 0037 and 0038 accepted 2026-08-20; 0039 accepted 2026-08-21; 0040 accepted 2026-08-22; 0041 accepted 2026-08-25; 0042 and 0043 accepted 2026-08-27.

0 commit comments

Comments
 (0)