Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

docs(design): scope attempts to the retried call and define transitions

zchpeter2769d46eac30
diff --git a/docs/design/task-run-log-previous-attempts.md b/docs/design/task-run-log-previous-attempts.md
index 076cd27c94..1da80ae588 100644
--- a/docs/design/task-run-log-previous-attempts.md
+++ b/docs/design/task-run-log-previous-attempts.md
@@ -47,8 +47,13 @@ attempt stays flat.
- The `RETRY_INFO` marker stops rendering as a standalone green "Retry" section.
Its payload (error, `retryCount`, `maximumRetries`) feeds the umbrella and
nested-row labels instead.
-- The summary bar gains an "N attempts" chip whenever the run has more than one
- attempt.
+- The umbrella sits inside the retried execution scope, not at the top of the run.
+ A run can hold several such scopes — a versioned release executes each file
+ separately — so each gets its own umbrella in place.
+- The summary bar gains an "N retries" chip whenever the run retried at all. It
+ counts `RETRY_INFO` entries across the whole run, which is the one retry number
+ that stays unambiguous when several scopes each retried a different number of
+ times. Per-scope counts live on that scope's umbrella.
## States
@@ -79,6 +84,13 @@ sections.
![Several previous attempts, expanded](task-run-log-previous-attempts/06-multiple-attempts-expanded.png)
+**One-time sections stay outside.** Prior backup runs once, before the retried
+call, and the schema sync once after it. Neither belongs to an attempt, so both
+stay at top level and keep their own durations — the umbrella sits between them,
+holding only the retried execution.
+
+![One-time sections outside the attempts](task-run-log-previous-attempts/10-one-time-sections-outside.png)
+
**Terminal failure, and a retry in progress.** Left: retries are exhausted, so the
final attempt's failure is state — red and auto-expanded — while the superseded
attempts stay folded. Right: the chip reads "retrying 2/3" and the running section
@@ -86,38 +98,143 @@ streams normally.
![Failed and running](task-run-log-previous-attempts/07-failed-and-running.png)
-## Rendering truth table
+## What the log stream contains
-| Run state | Previous attempts row | Final attempt sections |
-|---|---|---|
-| DONE after retries | grey, collapsed | flat, green — reads like a clean run |
-| FAILED after retries | grey, collapsed | flat, red; error sections auto-expand as today |
-| RUNNING, retrying | grey, collapsed; summary chip reads "retrying i/N" | streams normally |
-| No `RETRY_INFO` in the log | absent | unchanged rendering |
+Only part of a task run's log is attempt material. The executor emits one-time
+sections around the retried call, and the retry marker is written inside it, so
+the stream interleaves three kinds of entry:
-Auto-expand applies only to final-attempt error sections, narrowing today's
-behavior. The umbrella and the superseded attempts never auto-expand; a superseded
-failed section pre-expands only once the user opens its attempt.
+| Entry type | Where it is emitted | Attempt material? |
+|---|---|---|
+| `PRIOR_BACKUP_START` / `_END` | before `driver.Execute` | no — runs once |
+| `COMPUTE_DIFF_START` / `_END` | before `driver.Execute` (declarative) | no — runs once |
+| `RELEASE_FILE_EXECUTE` | before each file's `driver.Execute` | no — it opens a scope |
+| `TRANSACTION_CONTROL` | inside `driver.Execute` | **yes** |
+| `COMMAND_EXECUTE` | inside `driver.Execute` | **yes** |
+| `RETRY_INFO` | inside `driver.Execute`'s retry loop | **yes** — it is the boundary |
+| `DATABASE_SYNC_START` / `_END` | baseline changelog, and after `driver.Execute` | no — runs once |
+| `GHOST_MIGRATION_START` / `_END` | replaces `driver.Execute` | no — never retried |
+
+`DATABASE_SYNC` appears on both sides of the retried call, so position alone does
+not classify an entry; the type does. Prior backup's own statements run with empty
+`ExecuteOptions` and log nothing, so they cannot be mistaken for attempt material.
+
+Retries are also narrower than they look: `LogRetryInfo` has exactly one caller,
+PostgreSQL's lock-timeout loop in `backend/plugin/db/pg/pg.go`. No other engine
+produces a `RETRY_INFO`, and the gh-ost path never calls `driver.Execute` at all.
## Attempt derivation contract
-- Entries are already sorted by log time. Split at `RETRY_INFO` markers: the
- segment before the first marker is attempt 1, the segment between markers i and
- i+1 is attempt i+1, and the segment after the last marker is the final attempt.
- A marker belongs to no attempt's sections; it annotates the boundary.
-- Derive attempts inside each replica group and each release-file group, after
- those groupings are applied. The driver retry wraps a single file's execution on
- a single connection, so a marker must not create boundaries across file or
- replica scopes.
-- An empty final segment — a marker written but the retry's entries not yet
- arrived, or the run died there — renders the umbrella with no final-attempt
+- **Scope.** A retried execution scope is a maximal contiguous span of attempt
+ material that contains at least one `RETRY_INFO`. One-time entries before and
+ after it stay at top level, in place, and never fall inside an attempt. Without
+ this, an enabled prior backup — logged before the retried call — would be filed
+ under attempt 1, hidden as history on a run where it actually ran once, and
+ counted in that attempt's duration.
+- **Split.** Within a scope, split at the `RETRY_INFO` markers: the span before
+ the first marker is attempt 1, the span between markers i and i+1 is attempt
+ i+1, and the span after the last marker is the final attempt. A marker belongs
+ to no attempt's sections; it annotates the boundary.
+- **Nesting.** Derive scopes inside each replica group and each release-file
+ group, after those groupings are applied. The driver retry wraps one file's
+ execution on one connection, so a marker must never create a boundary across a
+ file or replica scope.
+- **Empty final segment.** A marker written but the retry's entries not yet
+ arrived, or the run died there, renders the umbrella with no final-attempt
sections. The run status chip carries the state.
-- An attempt's duration is its segment's span; the umbrella's duration is the sum
- of its attempts' spans.
+- **Durations.** An attempt's duration is its span; the umbrella's duration is the
+ sum of its attempts' spans. One-time sections keep their own durations and are
+ counted in neither.
- The "N sections · M entries" summary keeps counting everything, superseded
attempts included.
-- Frontend-only. Attempt boundaries derive entirely from `RETRY_INFO` entries
- already in the stream, so no proto or backend change is required.
+- Frontend-only. Scopes and boundaries derive entirely from entries already in the
+ stream, so no proto or backend change is required.
+
+## Rendering truth table
+
+Colors and auto-expansion come from the entries themselves, never from the task
+run's status. The two are genuinely independent in both directions:
+`runStandardMigration` logs a failed `DATABASE_SYNC` and only warns, so a **DONE**
+run can hold a red final section; `runVersionedRelease` returns an error if
+`UpdateDatabase` fails after a clean execution, so a **FAILED** run can hold an
+all-green log.
+
+| Condition | Previous attempts row | Sections outside it |
+|---|---|---|
+| An error entry in the final segment | grey, collapsed | that section red, auto-expanded |
+| No error entry in the final segment | grey, collapsed | green, collapsed — reads like a clean run |
+| Scope still streaming | grey, collapsed; chip reads "retrying i/N" | running section spins |
+| A one-time section failed (backup, sync) | unaffected | that section red, auto-expanded, at top level |
+| No `RETRY_INFO` anywhere | absent | unchanged rendering |
+
+Auto-expand applies to error sections outside the superseded attempts — the final
+segment and the one-time sections — which narrows today's behavior only by
+excluding superseded material. The umbrella and the attempts inside it never
+auto-expand; a superseded failed section pre-expands once the user opens its
+attempt.
+
+## Transitions
+
+A live log is polled every five seconds, and each poll re-derives the whole view
+from the full entry list. Derivation is pure over that list, so a late or
+out-of-order entry needs no incremental patching — it simply re-derives. What
+needs deciding is what the reader sees move, and what survives the move.
+
+### Two "previous" things, one nested inside the other
+
+A previous *run* never appears in the Previous attempts row. These are different
+levels and only one of them is this design's subject:
+
+| | In-run retry | Re-run |
+|---|---|---|
+| Created by | the driver's lock-timeout loop | a person clicking Re-run on a failed or canceled task |
+| Recorded as | a `RETRY_INFO` inside one `task_run` | a new `task_run` row |
+| Shown in | the Previous attempts row, inside this run's log | the task run history sheet, beside this log |
+
+Re-running a failed task therefore does **not** put the old run into Previous
+attempts; it starts a new run whose log begins empty, and the failed run moves
+into the history sheet with its own log intact.
+
+The two are easy to conflate, and the labels should carry the difference rather
+than leave it to be inferred: the history button reads "History (3)" today, which
+names no level. Renaming it "Previous runs (3)" pairs it with "Previous attempts"
+so the unit word — run against attempt — states which level each one is. That is a
+locale-only change and is not otherwise part of this work.
+
+### What the reader sees change
+
+| Transition | On screen | Decision |
+|---|---|---|
+| Run starts, no retry yet | flat sections streaming | no umbrella exists |
+| First `RETRY_INFO` arrives | the sections just watched fold into a new umbrella; a fresh segment starts streaming below it | the umbrella *appears above* the live segment, so the streaming rows keep their place at the bottom and the eye does not chase them |
+| A later `RETRY_INFO` arrives | the note goes "1 attempt" to "2 attempts"; the latest segment folds in | same |
+| Final attempt finishes | sections settle; an error in the final segment auto-expands | decided by entries, not by run status |
+| Run reaches a terminal status | the viewer remounts — its key carries the status — so everything returns to defaults | acceptable, because collapsed *is* the default |
+| Someone clicks Re-run | a new `task_run`; the viewer remounts on the new name with no umbrella; the finished run moves to the history sheet | not a retry, and not this row's business |
+
+### What must survive a poll
+
+Expansion state does not survive one today. `resolvedDatasetKey` in
+`useTaskRunLogSections.ts` is built from every entry in the log, and its effect
+clears every expansion set whenever that key changes — which, on a live run, is
+every time an entry arrives. Section ids compound it: they are positional
+(`section-${index}`), so inserting an attempt boundary renumbers every section
+after it.
+
+Both are survivable today because a live log is watched more than it is read. This
+change ends that: the reason to open a superseded attempt is to read the error
+that caused the retry, and retries happen *while the run is still streaming*. As
+it stands, the row a reader just opened would close under them within five
+seconds, and under positional ids could reopen as a different section entirely.
+
+So this design depends on two fixes, both in the grouping layer:
+
+- **Stable ids.** Derive a section's id from what it is — its scope, attempt
+ ordinal, entry type, and first entry's timestamp — rather than from its index.
+- **A narrower reset.** Reset expansion only when the log's identity changes, that
+ is, when the viewer is showing a different task run. With stable ids an append
+ needs no reset at all: sections that did not exist before are simply absent from
+ the expanded set.
## Alternatives rejected
@@ -142,16 +259,47 @@ rule above.
## Implementation outline
-Implementation follows in a separate PR.
+Implementation follows in a separate PR, after #21417 lands.
-- `frontend/src/components/task-run-log/model.ts`: split entries by attempt on
- `RETRY_INFO` boundaries, and an attempt-group type whose row status is
- superseded regardless of the errors it contains, with the entries themselves
- untouched.
+- `model.ts`: classify each entry as attempt material or one-time per the
+ inventory above, cut scopes and attempts from that classification, and add an
+ attempt-group type whose row status is superseded regardless of the errors it
+ contains, with the entries themselves untouched.
- `useTaskRunLogSections.ts`: a third grouping layer alongside the replica and
- release-file layers, and auto-expand restricted to final-attempt error sections.
+ release-file layers, and auto-expand restricted to error sections outside the
+ superseded attempts. Also the two transition fixes — content-derived section
+ ids in place of positional ones, and an expansion reset keyed to the task run
+ rather than to every appended entry — without which an opened attempt closes on
+ the next poll.
- `TaskRunLogViewer.tsx` and `SectionHeader.tsx`: the umbrella and nested-attempt
- rows (rotate icon, muted text, count note), plus locale keys for the labels.
-- Tests mirror the truth table and the marker-splitting cases: no marker, one
- marker, several markers, a marker inside a release-file group, replica-grouped
- entries, and an empty final segment.
+ rows, plus locale keys for the labels.
+- Tests mirror the truth table and the cutting cases: no marker, one marker,
+ several markers, a marker inside a release-file group, several release-file
+ groups retrying different numbers of times, replica-grouped entries, an empty
+ final segment, and a prior-backup section that must stay outside attempt 1.
+ Transition coverage appends entries to a rendered log and asserts that ids hold
+ and an opened attempt stays open across the append, that the first marker folds
+ the earlier sections without disturbing the streaming segment, and that a
+ different task run does reset the view.
+
+### Building on #21417
+
+That PR adds `Collapsible` / `CollapsibleTrigger` / `CollapsiblePanel` in
+`frontend/src/components/ui/collapsible.tsx`, wrapping Base UI, and uses them for
+the MCP capability ladder. The attempt rows should be built on the same primitive
+and follow the same conventions it establishes:
+
+- Base UI owns `aria-expanded` and `aria-controls`; the consumer supplies the
+ visible label and its own indicator. Today's `SectionHeader` hand-rolls
+ `aria-expanded` on a `Button` and has no `aria-controls` at all. That gap is
+ survivable one level deep, but the umbrella adds a third level, which is where a
+ screen-reader user most needs the control relationship stated.
+- A `ChevronRight` rotated 90° when open, rather than swapping two icons, so the
+ indicator animates instead of jumping.
+- Row sets carry an explicit `role="list"`, because Tailwind's preflight strips
+ the marker and Safari then drops list semantics — the same reason the ladder
+ states it.
+
+Migrating the existing section headers onto the primitive is the natural
+follow-up and would remove the inconsistency, but it is not required by this
+change and should not ride along with it.
diff --git a/docs/design/task-run-log-previous-attempts/10-one-time-sections-outside.png b/docs/design/task-run-log-previous-attempts/10-one-time-sections-outside.png
new file mode 100644
index 0000000000..590352daa6
Binary files /dev/null and b/docs/design/task-run-log-previous-attempts/10-one-time-sections-outside.png differ