|
| 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 --> |
0 commit comments