fix(github): render row-copy progress percentages at their true precision

[aparajon]

Why this matters

Progress percents render as rounded whole numbers, and a copy that has begun but not yet reached 1% rounds up to 1% — an operator watching 13M of 43B rows copied sees "1%" when the engine reports 0.03%, a 30x overstatement, sitting next to a multi-day ETA that contradicts it. Above 1% the rounding hides movement instead: on a huge table consecutive refreshes read the same whole number for hours even though the copy is advancing. Operators make stop/keep-waiting decisions from this line; it should show the figure the engine actually measured.

What it does

Row counts become the source of truth for every textual percent. Wherever a render site has the copied/total counts — and every row-copy site does — ui.FormatRowCopyPercent recomputes the percent from them and renders two decimals (45.37%, 0.03%), so the displayed figure always agrees with the row counts beside it. The engine's whole-number percent is only a fallback for the rare site without counts. Progress bars and threshold comparisons keep their integer widths, so a started copy still lights its first bar segment.

Two display invariants worth calling out:

• Never reads as not started. The fraction is floored at 0.01%: once rows have copied, the text can't show 0.00% and masquerade as an idle copy.
• Never reads as finished early. The fraction is capped at 99.99% while copied rows still trail the total: a copy in its final stretch can't show 100.00% beside a live ETA and masquerade as done.
• Progress comparisons agree with the display. ui.RowCopyFraction gives renderers the same row-derived value for ordering, so slowest-shard and least-progressed-table selection can tell two sub-1% copies apart instead of comparing rounded integers that read equal.

Covers the PR comment (running summary, table lines, checksum progress, shard summaries, recovering, stopped/failed labels) and the CLI (progress view, shard lines, watch TUI, the apply command's streaming log lines). The webhook shard summary gains row counts — the storage task already carries them — so per-shard percents get the same precision. Also swaps a literal failed glyph in the sharded status labels for glyph.Failed, which the severityglyphs lint requires.

How it moves us toward the northstar

The progress comment is the operator's window into a change that can run for days — its authority depends on showing what the engine measured, not a rounding of it. A percent that agrees with the row counts at every magnitude keeps that window trustworthy exactly when the stakes are highest: the biggest tables, where a rounded percent is off by a day of wall-clock.

PR comment — sub-1% copy on a 43B-row table

Schema Change Status — Production

Database: boardgames | Apply ID: apply-7aa13cf03496454b

Applied by @operator at 2026-09-01 15:14:06 UTC

Status: In Progress

events: 🟦⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜ 0.03%

• Rows: 13,186,540 / 43,234,523,345 · ETA: 2d 5h

PR comment — mid-copy multi-table apply (TEMPLATES.md preview)

📊 1/3 complete · 1 running (62.38%) · 1 queued

Schema testapp

users: 🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦⬜⬜⬜⬜⬜⬜⬜⬜ 62.38%

ALTER TABLE `users` ADD INDEX `idx_email`(`email`);

• Rows: 914,707 / 1,466,232 · ETA: 3m 15s

products: ⏳ Queued

ALTER TABLE `products` ADD INDEX `idx_price`(`price_cents`);

orders: 🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 ✅ Complete

CLI progress view — sub-1% copy, same table as above

     ~ events: 🟦⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜ 0.03%
       • Rows: 13,186,540 / 43,234,523,345 · ETA: 2d 5h

Opened by Claude (Fable 5).

[Copilot]

Pull request overview

Improves operator-facing progress reporting for long-running schema changes by rendering sub-1% row-copy progress as an accurate fractional percentage (e.g., 0.03%) instead of rounding up to 1%, keeping early progress and ETA consistent across the GitHub PR comment and CLI views.

Changes:

• Add ui.FormatRowCopyPercent and update templates/CLI rendering paths to use it for textual row-copy (and related) percent displays while keeping progress-bar thresholds on whole-number display percent.
• Update PR comment and CLI progress templates to print fractional percents for sub-1% progress (including shard lines and checksum progress in the CLI).
• Refresh/rename affected tests and swap a literal failed glyph for glyph.Failed to satisfy lint expectations.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pkg/webhook/templates/sharded_apply.go	Use glyph.Failed for failed status phrase to satisfy lint and keep glyphs consistent.
pkg/webhook/templates/apply.go	Route row-copy percent text through ui.FormatRowCopyPercent across multiple PR-comment render paths (running/recovering/stopped/failed summaries).
pkg/webhook/templates/apply_test.go	Update PR-comment assertions to expect fractional sub-1% output and rename the test accordingly.
pkg/ui/format.go	Introduce FormatRowCopyPercent and clarify RowCopyDisplayPercent’s role (bars/thresholds vs. textual percent).
pkg/ui/format_test.go	Add unit tests for FormatRowCopyPercent covering whole percents, sub-1% fractions, clamps, and missing totals.
pkg/cmd/internal/templates/progress.go	Use FormatRowCopyPercent in CLI progress output for row copy, checksum verification, stopped/cancelled labels, and parsed engine progress.
pkg/cmd/internal/templates/progress_states_test.go	Update CLI progress-state tests to expect fractional sub-1% output (including checksum “just started”).
pkg/cmd/internal/templates/progress_shard.go	Render shard copy percent via FormatRowCopyPercent using shard row counts for sub-1% accuracy.
pkg/cmd/internal/templates/progress_shard_test.go	Update shard progress tests to assert fractional sub-1% output.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[morgo]

🤖 Approving on Morgan's behalf (automated review).

Checked the helper split at cd48fc36 across every render site rather than taking the description's word for it, and the discipline holds: RowCopyDisplayPercent (integer) drives bars and threshold switches, FormatRowCopyPercent drives text, RowCopyFraction drives ordering. All three are applied consistently in webhook/templates/apply.go, cmd/internal/templates/progress.go, and watch_tui_view.go — no site mixes a rounded integer into a comparison. The Checksumming percent at apply.go:783 divides by ChecksumRowsTotal, but it's inside if table.ChecksumRowsTotal > 0, so no div-by-zero. RowCopyFraction clamps overshoot to 100, which matches the existing ClampRows/EstimateExceeded convention for Spirit reporting copied > estimated total.

Reproduced the headline claim — 13,186,540 / 43,234,523,345 renders 0.03%, exactly as advertised. CI green, display-only, off the MySQL data path.

One finding: the floor invariant has no ceiling counterpart, so an unfinished copy can read 100.00%.

FormatRowCopyPercent floors at 0.01 so a started copy never reads as idle, but nothing caps the top:

frac := math.Max(RowCopyFraction(pct, rowsCopied, rowsTotal), 0.01)
return fmt.Sprintf("%.2f%%", frac)

Anything from ~99.995% up rounds to 100.00%. Ran it:

999999999/1000000000       -> 100.00%   (exact 99.99999990)
99999/100000               -> 100.00%   (exact 99.99900000)
43234523344/43234523345    -> 100.00%   (exact 100.00000000)
9999/10000                 ->  99.99%   (exact 99.99000000)

On this PR's own 43B-row example that's the last ~2.16M rows — the copy displays 100.00% next to a live ETA for a stretch that, at the rate implied by the example, is not brief. The old integer render showed 99% there, so this is a narrow regression in the direction that reads worst: "100%" reads as done, and an operator deciding whether to keep waiting is exactly who this PR is for.

The symmetric guard is expressible from the counts the function already has:

if rowsCopied < rowsTotal {
    frac = math.Min(frac, 99.99)
}

That preserves "never reads as not started" and adds "never reads as finished before it is." Worth a follow-up, not a revision.

Coordination note: the sharded_apply.go literal-glyph → glyph.Failed one-liner in here is the third copy of the same drive-by — #910 and #1240 both carry it too. Whichever two land second will need that hunk dropped.

[aparajon]

🤖 Addressing morgo's review — the missing ceiling was a real gap, and you're right that it's strictly worse than the integer rendering it replaced: the old code could never say a copy was done early, and the new precision made that possible from ~99.995%.

Fixed in this PR rather than a follow-up: 2d0607e adds your exact guard — FormatRowCopyPercent now caps at 99.99% while rowsCopied < rowsTotal — and the doc comment states both bounds as one invariant: the rendering never reads as not-started and never reads as finished while the counts say otherwise. Your three probe values are pinned as tests, including the 43B-row pair from the PR body.

Deliberately not capped: RowCopyFraction still returns the true fraction. It feeds ordering (slowest-shard, least-progressed-table), where clamping two near-done copies to the same value would make the selection arbitrary exactly when it matters. Only the display caps.

On the glyph drive-by triplicated with #910/#1240: agreed, no action — it's byte-identical in all three, so whichever land later rebase the duplicate hunk away cleanly.

Reply generated by Claude Code (Claude Fable 5).