Skip to content

Commit bc2c566

Browse files
committed
[docs] Fail closed on incomplete board listings
Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>
1 parent 6d814c5 commit bc2c566

3 files changed

Lines changed: 28 additions & 15 deletions

File tree

‎docs/decisions/0040-sha-pinned-connected-github-import.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,11 @@ the selected `.py` files sequentially to the current board directory.**
7979
directories or other non-regular conflicts block the batch. Existing files
8080
require a separate, explicit confirmation naming the target paths; selecting
8181
Import is not itself overwrite consent. Immediately before the first PUT,
82-
the controller lists the directory again. A new or changed conflict
83-
invalidates prior consent and returns to review without writing.
82+
the controller lists the directory again. Both listings must carry explicit
83+
PBLE/1 completeness metadata: `FILE_LIST more=1`, or a Connection test double
84+
that cannot prove completeness, blocks the batch because an omitted entry
85+
could hide a conflict. A new or changed conflict invalidates prior consent
86+
and returns to review without writing.
8487

8588
6. **All bytes are acquired and validated before any board mutation.** The
8689
controller fetches every selected object from the pinned snapshot into one

‎docs/specifications/App/TDD.md‎

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -358,10 +358,12 @@ consent, bounded fetched candidate, operation generation, phase/progress,
358358
rate-limit metadata, and an honest complete/partial/cancelled result.
359359

360360
**Dependencies:** a pinned approved HTTP client behind `GithubApi` (HTTPS to
361-
the exact GitHub REST API host), `Connection.listDir`/`putFile`, the Files
361+
the exact GitHub REST API host), `Connection.listDir`/`putFile` plus the optional
362+
neutral `ConnectionDirectoryListingSource` completeness capability, the Files
362363
controller's current directory + refresh callback, connection-session stamps,
363-
and `lib/localization/`. The connected subset has no `lib/data/` dependency and
364-
never imports `lib/ble/`.
364+
and `lib/localization/`. Production and shipped fakes implement that capability;
365+
an unknown Connection double fails closed for import preflight. The connected
366+
subset has no `lib/data/` dependency and never imports `lib/ble/`.
365367

366368
**Satisfies in this increment:** the frozen connected subset of
367369
FR-IMPORT-1/-2/-3/-5, IF-4, NFR-OFF-2, CON-3/8/9, SEC-10. **Deferred, not
@@ -795,13 +797,18 @@ duplicate target, non-canonical escape, and any complete board path over
795797
PBLE/1's 128-byte UTF-8 ceiling. The review view renders exact remote → board
796798
path pairs before a network content fetch or PUT.
797799

798-
`review()` first requires the captured session stamp to be current, then calls
799-
`Connection.listDir(capturedCwd)`. Exact-name regular-file collisions are the
800-
overwrite set. A directory or other non-regular entry at a target is blocking;
801-
the importer never replaces or descends into it. A non-empty overwrite set
802-
opens a separate confirmation that lists the exact board paths. Consent is
803-
bound to `{sessionStamp, cwd, targetPaths, conflictPaths}`; changing selection,
804-
ref, folder, target data, or session invalidates it.
800+
`review()` first requires the captured session stamp to be current, then obtains
801+
`Connection.listDir(capturedCwd)` together with the neutral completeness bit
802+
exposed by `ConnectionDirectoryListingSource`. `PbleConnection` derives that bit
803+
from `FILE_LIST more`; its stable facade and `FakeConnection` preserve it. A
804+
truncated result—or an unknown Connection double that cannot prove
805+
completeness—fails closed before conflict classification. Exact-name
806+
regular-file collisions are the overwrite set. A directory or other non-regular
807+
entry at a target is blocking; the importer never replaces or descends into it.
808+
A non-empty overwrite set opens a separate confirmation that lists the exact
809+
board paths. Consent is bound to
810+
`{sessionStamp, cwd, targetPaths, conflictPaths}`; changing selection, ref,
811+
folder, target data, or session invalidates it.
805812

806813
Immediately after all content validates and before the first PUT, the
807814
controller requires the same session, lists `capturedCwd` again, and compares

‎docs/specifications/App/specs.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -239,9 +239,12 @@ to `[red]` before implementation:
239239
duplicate/escaping targets, and targets exceeding PBLE/1's 128-byte UTF-8
240240
path ceiling MUST fail before download. Existing regular files MUST be named
241241
in a separate explicit overwrite confirmation; an existing directory or
242-
other non-regular conflict MUST block import. The directory MUST be listed
243-
again immediately before the first PUT; a changed conflict set MUST
244-
invalidate prior confirmation and return to review with zero writes. MUST
242+
other non-regular conflict MUST block import. The board-listing seam MUST
243+
preserve PBLE/1's completeness bit, and `FILE_LIST more=1` (or a test double
244+
that cannot prove completeness) MUST block import rather than treating omitted
245+
names as absent. The directory MUST be listed again immediately before the
246+
first PUT; a changed conflict set MUST invalidate prior confirmation and
247+
return to review with zero writes. MUST
245248
- **A33-SUB-AC-5 (bounded all-fetch preflight)** — Before any board mutation,
246249
the client MUST fetch every selected file from the pinned snapshot and form
247250
one in-memory candidate. Each actual raw file MUST be at most 256 KiB and the

0 commit comments

Comments
 (0)