Skip to content

Commit c40a338

Browse files
committed
[docs] record recovery candidate validation and remaining platform gates
Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>
1 parent 4479ff6 commit c40a338

8 files changed

Lines changed: 165 additions & 35 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,18 @@ and submission packet do not claim Play submission, approval, or rollout.
1919

2020
### App source
2121

22+
- Prepared app source candidate `0.3.0+9` with bounded on-device current-text
23+
recovery using Drift. Exact text and metadata commit atomically; startup
24+
offers offline preview, Restore and confirmed Discard, with separate local
25+
checkpoint status and an explicit Save recovery copy action. Storage errors
26+
preserve the previous copy and live text, with explicit volatile continuation.
27+
- Added document-epoch and connection-session guards for Editor Save/Run,
28+
Files Open/Upload and Blocks-to-Editor replacement. Restored drafts require
29+
current-destination confirmation before board writes; a board swap after text
30+
upload refuses Run and reports the partial outcome. Full project and Blocks
31+
graph persistence remain carried. Candidate validation is recorded under
32+
`docs/developments/2026-q4-reliable-workflow/c1-s2/`; no store release claimed.
33+
2234
- Added a full offline Privacy policy route from About, with the published
2335
policy, effective date and privacy contact. Reading it preserves the live
2436
board session, editor, Blocks and console state, including at large text
@@ -90,8 +102,8 @@ and submission packet do not claim Play submission, approval, or rollout.
90102
results or new release are claimed.
91103
- Specified bounded Drift current-text recovery, local restore/discard,
92104
failure handling and document/session guards in ADR-0048 and the App
93-
contracts. Implementation remains pending; sizing requires revising the
94-
original S2 forecast.
105+
contracts. The bounded successor is implemented in the 0.3.0 source candidate;
106+
acceptance and broader persistence obligations follow the C1-S2 record.
95107
- Verified live Android open-testing wording and prepared correction of the
96108
older public TestFlight description. Installed identities are now recorded;
97109
Android code/assets match the retained build-8 AAB, while iPad build-6 source

‎README.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ fetches and validates the complete batch, shows the exact destination paths,
7575
and asks separately before overwriting existing files. Import never creates a
7676
remote folder hierarchy, opens an editor document, or runs downloaded code.
7777

78-
The current App source version is `0.2.0+8`; App and firmware versions are
78+
The next App source candidate is `0.3.0+9`; App and firmware versions are
7979
independent. The published Android version is `0.2.0`, available through
8080
[Google Play open testing](https://play.google.com/store/apps/details?id=dev.pyble.pyble).
8181
iPad testing continues through TestFlight. The
@@ -91,6 +91,22 @@ does not establish its installed build/source identity or mean those earlier
9191
artifacts contain later connection-lifecycle fixes. Both platforms share the
9292
same Flutter source and app test gates. The iOS/iPadOS project minimum is 15.
9393

94+
### Next app candidate: local draft recovery
95+
96+
The `0.3.0+9` source candidate adds one on-device current-text recovery copy.
97+
After restart, preview and explicitly Restore or Discard the last committed
98+
copy before connecting. “Saved locally” means the matching transaction finished;
99+
pending edits may not survive immediate termination. The separate **Save
100+
recovery copy** action works without a board. Recovered text requires explicit
101+
confirmation of the current board destination before Save, Run or Files Upload.
102+
103+
This bounded feature covers text up to 1 MiB, including Python explicitly copied
104+
from Blocks. Blocks workspace graphs, projects/history and exported backups
105+
remain outside this increment. Uninstalling or clearing app data removes local
106+
copies. See the [candidate execution record](docs/developments/2026-q4-reliable-workflow/c1-s2/00_Execution_Record.md)
107+
for automated and device evidence; source implementation does not establish
108+
store availability or release qualification.
109+
94110
### Firmware
95111

96112
The board-side agent is built with upstream MicroPython and exposes PBLE/1 as a

‎docs/ROADMAP.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -37,13 +37,14 @@ v0.7.0 remains non-normative and requires separate maintainer approval.
3737
and launches are verified on connected tablets; fresh enrollment/reinstallation
3838
was not exercised. The pilot kit, recovery design and validation inventory
3939
are prepared; this does not complete the Sprint or board qualification.
40-
- Implement the [bounded current-text recovery contract](specifications/App/current-draft-recovery.md)
41-
after replanning against its 45–72 hour working estimate for engineering,
42-
recipe, representative platform checks and follow-up. Current drafts remain
43-
volatile; full A-24 and Blocks persistence remain separate scope.
40+
- Validate and qualify the implemented [bounded current-text recovery candidate](developments/2026-q4-reliable-workflow/c1-s2/00_Execution_Record.md)
41+
against the [contract](specifications/App/current-draft-recovery.md). Source
42+
candidate `0.3.0+9` supplies atomic local checkpoints and offline recovery;
43+
full A-24 and Blocks graph persistence remain separate scope. The original
44+
45–72 hour estimate remains a forecast, not measured effort.
4445
- Correct the [stale public TestFlight description](developments/2026-q4-reliable-workflow/c1-s1/05_TestFlight_Metadata_Correction.md)
4546
through the distribution owner; replacement copy is prepared, not published.
46-
- Continue the app 0.2.0 beta train; source is currently `0.2.0+8`. The
47+
- Prepare the next app `0.3.0+9` candidate while retaining the published 0.2.0 channel baseline. The
4748
[Android publication review](testing/website/android-open-testing-2026-09-25.md)
4849
records live open-testing availability. The
4950
[prepared build-8 handoff](testing/google-play/0.2.0-build-8.md) remains a

‎docs/developments/2026-q4-reliable-workflow/c1-s2/00_Execution_Record.md‎

Lines changed: 28 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
| Candidate | App `0.3.0+9`; local source/build candidate, with final revision/artifact identity to be recorded at qualification |
1212
| Scope | PYB-006.2 bounded current-text recovery; supporting PYB-009.1 recipe and applicable PYB-008.1 observations |
1313
| Contract | [Current-draft recovery](../../../specifications/App/current-draft-recovery.md), [ADR-0048](../../../decisions/0048-bounded-current-text-draft-recovery.md) |
14-
| Overall state | Candidate source implemented; integrated verification and required physical acceptance remain in progress. PYB-006.2 and M-02 are not Done |
14+
| Overall state | Candidate source implemented; 968 ordinary Flutter tests pass, Android engineering recovery checks pass, and required physical acceptance remains partial. PYB-006.2 and M-02 are not Done |
1515
| S1 state | Unchanged: six Done, two Prepared, four Awaiting evidence; M-01/SG0 and pilot work remain unfinished |
1616
| Capacity/calendar | Original S2 allowance 24h and 12–25 October dates remain historical forecasts. The 45–72h estimate / 60h S2–S4 option is not measured effort or confirmed human capacity |
1717
| Method | Separate storage, coordinator and UI Git worktrees; root integrates board/session guards, regressions, release records and qualification attempts |
@@ -47,9 +47,9 @@ source progress; it is not a Done Increment or release admission.
4747
| C1-S2-T04 / PYB-006.2 | Implemented — durable storage and schema | Final integration and physical storage evidence |
4848
| C1-S2-T05 / PYB-006.2 | Implemented — startup choices/coordinator/UI | Final integration and physical interaction/restart evidence |
4949
| C1-S2-T06 / PYB-006.2 | Implemented — failure guidance/localization/volatile choices | Final localization/accessibility/regression checks |
50-
| C1-S2-T07 / PYB-006.2 | In progress — integration and source gates | Final suite/check results tied to integrated revision |
51-
| C1-S2-T08 / PYB-008.1 | Awaiting physical Android candidate evidence | Lenovo absent from current ADB discovery; an API 34 emulator is available for additional nonphysical checks |
52-
| C1-S2-T09 / PYB-008.1 | Awaiting physical iPad candidate evidence | Wireless iPad visible; development execution currently requires Developer Mode to be enabled |
50+
| C1-S2-T07 / PYB-006.2 | Implemented and checked — full analysis, 968 ordinary tests, formatting and source gates pass | Pinned golden CI and final release evidence remain tracked separately |
51+
| C1-S2-T08 / PYB-008.1 | Awaiting physical Android candidate evidence | Lenovo connected and isolated engineering storage/relaunch/offline UI checks pass; remaining board/interaction matrix recorded in [platform report](02_Platform_Qualification.md) |
52+
| C1-S2-T09 / PYB-008.1 | Awaiting physical iPad candidate evidence | iPad connected over USB; signed and unsigned builds succeed, but launch still requires Developer Mode to be enabled |
5353
| C1-S2-T10 / PYB-006.2 | In progress — integration/evidence review | Record final checks, immutable candidates, physical results and carried limitations |
5454
| C1-S2-T11 / PYB-011.2 | Awaiting participant evidence | No consenting activation dates or mature follow-up records supplied |
5555

@@ -61,33 +61,33 @@ records the final complete run and exact candidate revision before acceptance.
6161

6262
| Scenario | Implemented evidence | Current acceptance state |
6363
|---|---|---|
64-
| DR-T01 | Real repository validation/round-trip tests: exact Unicode, filenames, content bound and invalid metadata | Component tests passing; final integration pending |
65-
| DR-T02 | File-backed close/reopen retains the committed slot and generation | Component tests passing; platform execution pending |
66-
| DR-T03 | Child-process SIGKILL before/after write checkpoints; whole old/new committed content oracle | Host interruption tests passing; Android/iPad termination observations pending |
67-
| DR-T04 | Real storage failure injection plus controller failure state retains previous copy and live edits | Component tests passing; final integration pending |
68-
| DR-T05 | Bad hash/metadata, corrupt/truncated database and unsupported version fixtures; bounded startup error UI | Component tests passing; final integration pending |
64+
| DR-T01 | Real repository validation/round-trip tests: exact Unicode, filenames, content bound and invalid metadata | Automated integrated suite passing |
65+
| DR-T02 | File-backed close/reopen retains the committed slot and generation | Automated suite and Lenovo separate-process harness passing; iPad pending |
66+
| DR-T03 | Child-process SIGKILL before/after write checkpoints; whole old/new committed content oracle | Host interruption tests and Lenovo force-stop/relaunch pass; iPad and precisely timed physical interruption phases pending |
67+
| DR-T04 | Real storage failure injection plus controller failure state retains previous copy and live edits | Automated integrated suite passing |
68+
| DR-T05 | Bad hash/metadata, corrupt/truncated database and unsupported version fixtures; bounded startup error UI | Automated integrated suite passing |
6969
| DR-T06 | Fresh v1/reopen, exported first schema and unsupported-version refusal; no fictional released v0 | Component tests passing; future schema migrations remain gated on new fixtures |
70-
| DR-T07 | Explicit Restore/Discard, failed discard, volatile Retry, late hydration and no implicit board writes | Controller/UI tests passing; physical interaction pending |
70+
| DR-T07 | Explicit Restore/Discard, failed discard, volatile Retry, late hydration and no implicit board writes | Automated suite and Lenovo Restore/offline preview/relaunch pass; complete interaction matrix pending |
7171
| DR-T08 | Deterministic 500ms / continuous-edit 2s scheduling; delayed commits, startup timeout and epoch tests | Component tests passing; physical lifecycle interruption pending |
72-
| DR-T09 | Active write/replacement serialization, tombstones and no queued resurrection | Component tests passing; final integration pending |
72+
| DR-T09 | Active write/replacement serialization, tombstones and no queued resurrection | Automated integrated suite passing |
7373
| DR-T10 | Recovered-target cancellation and stale document/path/session consent | Recording-connection tests passing; physical target consent pending |
7474
| DR-T11 | Stable-facade board swap, delayed GET, stale completion and PUT-to-Run attachment refusal | Recording-connection tests passing; final integrated regression pending |
7575
| DR-T12 | Explicit generated text handoff with editor-epoch/revision guards; existing workspace/sidecar behavior retained | Affected automated regression required in final suite; representative device checks pending |
76-
| DR-T13 | Local/board status separation, ARB error/status copy, disconnected preview, keyboard and 2× text | UI component tests passing; final localization/goldens and device evidence pending |
77-
| DR-T14 | Exact recorded Android/iPad candidate, offline restore and explicit current target consent | Not run on required physical candidates; concrete access/setup gaps above |
76+
| DR-T13 | Local/board status separation, ARB error/status copy, disconnected preview, keyboard and 2× text | Automated UI/localization pass; physical Lenovo 2× preview observed; local golden baseline mismatch reproduced unchanged, pinned CI pending |
77+
| DR-T14 | Exact recorded Android/iPad candidate, offline restore and explicit current target consent | Partial Lenovo engineering observations; signed iPad candidate not yet launched; physical board consent still pending |
7878

79-
## Reported verification and remaining admission
79+
## Verification and remaining admission
8080

8181
| Check | Reported result / limitation |
8282
|---|---|
8383
| Storage component suite | 21 passing, including file-backed tests and fault-controlled child-process SIGKILL checks |
8484
| Coordinator/document suite | 27 passing, including failed discard, delayed hydration, replacement/session races and conflict Retry choice |
85-
| UI component suite | 52 passing in the latest component report |
85+
| UI component suite | 57 passing in the latest component report; included in the final ordinary suite |
8686
| Integrated storage/coordinator/guard subset | 51 passing in an integration subset; overlaps component suites |
8787
| Static analysis | Full app analysis reported no issues at the latest integration checkpoint |
88-
| Full app regression and repository gates | Final integrated results in progress; record actual counts and revision before marking acceptance |
89-
| Android additional harness | API 34 emulator booted/build work underway; does not satisfy physical Lenovo evidence |
90-
| iPad additional harness | Wireless device discovery succeeds; Developer Mode currently prevents development execution |
88+
| Full app regression and repository gates | At app source `4479ff6`: 968 ordinary Flutter tests pass; analysis clean; 204 Dart files formatted; no-leak/SPDX/import/locale/DCO pass; 42 publication tests and Markdown links pass after documentation updates |
89+
| Android additional harness | Lenovo Android 12 separate-process seed/verify and production-entry offline UI checks pass in an isolated app; [scope/artifacts](02_Platform_Qualification.md) |
90+
| iPad additional harness | USB discovery and signed build succeed; Flutter launch reports Developer Mode disabled; owner setup requested |
9191
| Candidate store state | No Google Play/TestFlight submission, approval, new public availability or installed-store verification established by this work |
9292
| Firmware and Ready | No new firmware publication or complete five-profile qualification; no second-operator reproduction or PyBLE Ready award |
9393

@@ -107,3 +107,13 @@ physical recovery/consent observations and any affected release matrix. Preserve
107107
failed/not-run rows rather than weakening the contract to meet a date. Human
108108
pilot work continues as its own evidence stream. No full A-24 completion,
109109
qualified release or publication follows from source commits alone.
110+
111+
## Local golden diagnosis and review branch
112+
113+
The 33 local pixel comparisons fail on macOS 27.0.1 with Flutter 3.44.1.
114+
All 33 rendered test images match byte-for-byte with the same tests run from
115+
unchanged `origin/main` at `8dde8d6` on this host. Existing baselines are retained;
116+
this result is not a golden pass. The workflow pins macOS 15, whose result is
117+
tracked on [draft PR #40](https://github.com/PyBLE-dev/PyBLE/pull/40).
118+
The source and documentation are reviewable on `feature/current-draft-recovery`.
119+
No merge or store publication is implied by that draft.

‎docs/developments/2026-q4-reliable-workflow/c1-s2/01_Operator_Recipe.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ procedures for any affected BLE/profile matrix rows.
9393

9494
## Additional isolated platform-storage harness
9595

96-
`app/integration_test/draft_recovery_device_test.dart` provides `seed` and `verify`
96+
`app/integration_test/draft_recovery_device_qualification.dart` provides `seed` and `verify`
9797
phases using the actual platform Application Support store and a recording board
9898
seam. The phase is selected with `PYBLE_RECOVERY_TEST_PHASE=seed` or `verify`.
9999
The qualification database is `qualification-current-draft.sqlite`, separate
@@ -138,3 +138,10 @@ Two representative recovery runs do not qualify five firmware profiles or award
138138
PyBLE Ready. This recipe is complete as a prepared instruction set; execution,
139139
correction from actual observations and second-operator reproduction remain
140140
separate evidence obligations under PYB-009.
141+
142+
The manual harness is deliberately separate from the single CI Android smoke
143+
entry point. Use `--keep-app-running` with `flutter drive` for the seed phase:
144+
its default cleanup uninstalls the app and removes its private data. Force-stop
145+
that exact isolated package before the verify phase, retain both artifacts, and
146+
verify the second installation preserves the same data container. Never run a
147+
qualification harness over a user's installed store app.

0 commit comments

Comments
 (0)