Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
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.mdindex 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 andnested-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.+**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.+++**Terminal failure, and a retry in progress.** Left: retries are exhausted, so thefinal attempt's failure is state — red and auto-expanded — while the supersededattempts stay folded. Right: the chip reads "retrying 2/3" and the running section@@ -86,38 +98,143 @@ streams normally.-## 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-attemptsections. 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, supersededattempts 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.pngnew file mode 100644index 0000000000..590352daa6Binary files /dev/null and b/docs/design/task-run-log-previous-attempts/10-one-time-sections-outside.png differ