Files
pipelines/app/notes/R2c.md
T

115 lines
6.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# R2c — native retry / restart action
Small app-only addition, new files only. `RetryRunAction(run, gateway,
onRunChanged)` is the deliberate retry entry point for a stopped failed run; it
does not add a screen or controller and is not wired into the shell.
## What changed
| File | Lines | Responsibility |
| --- | --- | --- |
| `lib/features/runs/actions/retry_action.dart` | 123 | `RetryRunAction`, gating, send/refusal/resync orchestration |
| `lib/features/runs/actions/retry_dialog.dart` | 207 | Native resume/restart confirmation, refusal display, key lifetime |
| `lib/features/runs/actions/retry_eligibility.dart` | 16 | `canRetryRun` mirroring the web `canRetry` |
| `lib/features/runs/actions/retry_intent.dart` | 29 | Mode, confirmed intent and idempotency-key generation |
| `lib/features/runs/actions/retry_wording.dart` | 33 | Web-verbatim words, titles, error wording and test keys |
| `test/.../retry_test_support.dart` | 112 | Fake gateway and Material/Cupertino hosts |
| `test/.../retry_action_test.dart` | 245 | Eligibility, both platforms, modes and key fields |
| `test/.../retry_resilience_test.dart` | 223 | Immediate refusals, recheck outcomes, key retention |
| `test/.../retry_safety_test.dart` | 133 | Double submit, late replies, narrow 2x layout |
No repository, gateway, socket, controller, shell, main, pubspec, web, server or
device file was edited.
## Behavior
Eligibility is exactly the browser's rule: a loaded run that is not executing and
whose status is `failed` (`run != null && !run.executing && status == "failed"`).
A stale `failed` status while execution is still in flight, a running/waiting/
succeeded/canceled run, and a malformed run render nothing.
The button is a Material `FilledButton` or a Cupertino `CupertinoButton.filled`,
labelled `Retry`. Opening the prompt sends nothing, and `Keep` only closes it.
The first confirmation is the browser's retry copy: title `Retry run {id}?`,
message `Only failed runs can be retried. The server starts a new run from the
same input.`, confirm `Retry`, dismiss `Keep`, plus the browser-only secondary
`Restart from start` that leads to a distinct confirmation. That second prompt
uses title `Restart run {id}?`, message `This replays the whole pipeline from the
start instead of resuming the failed stage.` and confirm `Restart from start`;
the resume actions are gone, so the more destructive choice cannot be mistaken
for resume.
Resume calls `RunsRepository.retryRun` with only `run_id` and `request_key`, so
`retry_mode` is omitted and the server's `resume` default applies. Restart sends
`retry_mode: "restart"` with the same two required fields.
A `request_key` is created on the first confirm of an open prompt, not on opening
or `Keep`. It survives a refusal, so pressing confirm again for the same
uncertain request reuses the key and the server can dedupe it. Closing the prompt
and opening it again is a fresh deliberate intent and gets a new key, so a resume
attempt followed by a restart attempt never shares a key. Switching to the
restart confirmation before any send simply confirms restart with that prompt's
first key. Keys are bounded and run-scoped (`app-retry-{runId}-…`, well under the
server's 128-character cap).
A server refusal returns to the prompt immediately: the exact server words are
visible and `Keep`/back are available while the detached `get_run` recheck is
still pending. One bounded re-read is issued per refusal, single-flight through a
retained future, with no retry loop or polling. If server truth says the run is no
longer retryable, confirm is disabled and an attempted tap sends nothing; the
refusal stays visible until dismissal. If the recheck itself fails, truth is
unknown, so confirm is re-enabled and a deliberate retry uses the retained key.
Late retry replies and late rechecks after disposal or navigation are ignored.
Construction, controls and error colour are standard Material/Cupertino defaults;
there is no custom palette, fixed control size or dependency. The narrow layout
relies on the native dialog's own scrolling/wrapping.
## Acceptance checks
Fake-gateway widget tests, both platforms, no socket or real server:
- eligibility table for stopped failed vs executing failed, running, waiting,
succeeded and canceled runs, plus the same visibility table under both apps;
- `Retry` opens the native `AlertDialog`/`CupertinoAlertDialog`, `Keep` closes it
and the recorded gateway calls are still empty;
- resume sends exactly `{run_id, request_key}` and no `retry_mode`; restart sends
exactly `{run_id, request_key, retry_mode: "restart"}`;
- key format is deterministic under an injected clock/entropy, bounded, fresh per
call, retained across an uncertain retry (resume and restart), and different
after a deliberate reopen or mode change;
- refusal message appears while `get_run` is deliberately unresolved, with Keep
enabled, confirm disabled and no callback yet; Keep then closes and the late
recheck still delivers server truth safely;
- ineligible recheck (`succeeded`) blocks a repeat action; failed recheck leaves
the same key and a working deliberate retry;
- two confirm taps while in flight produce one `retry_run`; both the retry reply
and the recheck are safe after disposal;
- 320×480 at 2× text: both resume and restart confirmations render on both apps
with no exception, and Keep sends nothing.
## Checks actually run
```
dart format lib/features/runs/actions test/features/runs/actions # clean
flutter analyze # No issues found!
flutter test test/features/runs/actions # 40 passed
flutter test # 69 passed
flutter build web # Built build/web (14.5s)
```
## Honest limits
- **Not wired into a run-detail screen.** This branch has no runs screen or
controller; the manager owns that integration. There is no browser interaction
or rendered capture for this widget, and `flutter build web` proves compilation
only, not rendered behavior.
- Browser parity is by source/word/request-shape comparison with
`web/src/actions.js` and `web/src/repository.js`; the web client itself was not
changed and no live web retry was performed.
- **Mobile unverified.** No Android/iOS build, emulator, ADB or device was used.
- No real server or run was retried, canceled or otherwise mutated; all evidence
uses local fakes.
- The candidate is committed, not pushed or deployed.