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): fold retried attempts into one row in the task run log
zchpetera0a999fb3cab
diff --git a/docs/design/task-run-log-previous-attempts.md b/docs/design/task-run-log-previous-attempts.mdnew file mode 100644index 0000000000..b121665dfd--- /dev/null+++ b/docs/design/task-run-log-previous-attempts.md@@ -0,0 +1,113 @@+# Task run log: fold in-run retries into a Previous attempts row++When a statement fails with a retryable error such as a lock timeout, the executor+retries the whole execution inside the same task run, up to the project's+Execution retry policy maximum (the lock-timeout loop in+`backend/plugin/db/pg/pg.go`). Each attempt appends its entries to the same+`task_run_log` stream, separated by a `RETRY_INFO` marker. The log viewer groups+consecutive entries by type and renders any section containing an error as red,+auto-expanded. A run that failed once and then passed on a retry therefore keeps a+red, auto-expanded failure section forever (BYT-9993; the customer's read: the UI+is correct, but the failed step should not stay red once it passed).++Task-level re-run is not the problem and does not change: re-running a FAILED or+CANCELED task creates a new `task_run` row, and `task_run_log` is keyed by+`(project, task_run_id)`, so entries never cross runs.++## The rule++Only the final attempt's failure is state. An attempt followed by a `RETRY_INFO`+marker is superseded — its failure is the reason the retry ran — so it renders as+history: grey, collapsed, never auto-expanded, one click from the full record.++## Decision++All superseded attempts fold into a single **Previous attempts** row; the final+attempt stays flat.++- The final attempt's sections render at top level, unchanged from today, in every+ run state (DONE, FAILED, RUNNING).+- Everything before the final attempt collapses into one umbrella row in its+ chronological position, above the final attempt's sections.+- The umbrella's right-side note is the **count** ("2 attempts"). One failure+ reason cannot summarize several attempts, and the count is the first fact a+ reader wants; per-attempt reasons sit on the nested rows.+- Grey, not amber, and no fill color. The row is set apart only by a rotate icon+ and muted text. Amber is still a warning hue, and history should not catch the+ eye. Red appears only on the error entries inside the expanded record, which+ stays faithful — nothing is rewritten.+- Expanding the umbrella reveals one nested row per attempt ("Attempt 1 · failed:+ lock timeout · 1.0s"). Expanding an attempt reveals its sections with their+ original marks, the failed section pre-expanded.+- With exactly one previous attempt, expanding the umbrella goes straight to that+ attempt's sections — no middle level for a list of one. The note still reads+ "1 attempt".+- 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.++## Rendering truth table++| 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 |++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.++## 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+ 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.+- 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.++## Alternatives rejected++- **Flat attempt rows**, one grey row per attempt at top level: failure reasons+ read without a click, but the default view then varies with the retry count, and+ for lock-timeout retries every attempt carries the same reason, which is most of+ what the extra rows would show.+- **Attempt lanes**, every attempt a labeled group in the GitHub Actions style:+ the clearest symmetry, but it puts a permanent nesting level on the common+ success path and its final lane header restates the run's own status chip.+- **Status softening only**, keeping the flat list and marking superseded sections+ grey: the smallest change, but the interleaved Transaction rows of two attempts+ stay cryptic and the standalone "Retry" pseudo-section survives.+- **Amber for history**: rejected everywhere, including row fills. See the color+ rule above.++## Implementation outline++Implementation follows in a separate PR.++- `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.+- `useTaskRunLogSections.ts`: a third grouping layer alongside the replica and+ release-file layers, and auto-expand restricted to final-attempt error sections.+- `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.