The materialization hole scan reports on every start: one unconditional INFORMATION line with the pass's full tally, so a zero-hole start no longer reads the same as a start whose scan never ran (#3756)

[erikdarlingdata]

Descends from #3731 / #3653 Q10. Closes #3756.

The lie

TimescaleSupport.RepairMaterializationHolesAsync (#3731, Q10) runs at every service start and returns a MaterializationHoleRepairSummary. What the issue could not see from the log, the source shows: the pass wrote its own end-of-pass summary only when it had repaired, deferred or failed something, and a Debug line otherwise. At the level a production log is read that is nothing — and nothing is also what a start writes when the scan is never reached, and what a scan that threw before its first probe and was swallowed writes once you have not read the per-aggregate WARNING. So on the first install to carry the scan, the largest production store's log had no repair line, the reading "the day's refreshes had already healed it, the scan correctly found nothing" was almost certainly right, and it could not be confirmed. The countersign accepted "zero needed" on inference. This is the self-proving-flag class (#3574's visibility, #3735's collection_health_age_seconds): a check whose negative outcome is indistinguishable from its non-execution has not reported.

What lands

Storage — the pass returns the whole tally and writes no summary of its own. MaterializationHoleRepairSummary gains HolesFound and BucketsFound — counted as the scan SAW them, contiguous ranges and the buckets they span, before the cap decides what this start repairs and what it leaves — and Elapsed, from a Stopwatch started at entry so it is the pass's own cost (detect, every probe, every refresh) and not the caller's connection open. The record's doc states the arithmetic a reader of the line needs: BucketsFound == BucketsRepaired + BucketsDeferred always; HolesRepaired + HolesDeferred exceeds HolesFound by one for every range the cap split (one hole as the scan saw it, two lines as the repair reported it). Buckets are the unambiguous currency. The conditional Information/Debug summary at the end of the pass is removed — one owner, one line per start — and the per-hole, per-deferral and per-failure lines stay: they are the detail the summary counts.

Worker — one INFORMATION line per start, whatever the counts. RunMaterializationHoleRepairAsync takes the returned tally and the very next statement is the line, with no condition between them:

TimescaleDB: materialization hole scan (#3653 Q10) — {Scanned} aggregate(s) walked, {Skipped} skipped, {HolesFound} hole(s) found spanning {BucketsFound} bucket(s), {HolesRepaired} hole(s) / {BucketsRepaired} bucket(s) repaired ({Forced} needed the forced refresh), {HolesDeferred} hole(s) / {BucketsDeferred} bucket(s) deferred past the cap, {Remaining} bucket(s) still reading as holes after repair, {Failures} isolated failure(s), in {ElapsedMs} ms.

The TimescaleDB: prefix is the neighbouring baseline-backfill line's. Beside it, a new catch (OperationCanceledException) arm writes a different line — the scan was cancelled before it could report; at shutdown that is expected and the next start's scan re-finds anything this one left — and rethrows, so the drain at shutdown sees exactly the cancellation it was written to swallow. The connection-open WARNING is untouched. Every outcome of a launched scan now leaves a different line, all from this one method: returned (the summary, zeros included), threw outside its isolation or could not connect (the WARNING), cancelled (the cancellation line). A start that never launches it — plain-PostgreSQL mode, or the TimescaleDB block faulting first — already writes its own line at the launch site's catch, and nothing in the runner can or should speak for that case.

Why this shape

The line is the worker's, not the pass's. The thing the line has to prove is that the scan RAN on this start, and "this start" is the worker's concept: the worker owns the connection open, the launch, the drain, and therefore the two outcomes a summary written inside the pass can never report (the pass never entered; the pass was cut short). Putting the line at the call site puts all three arms in one method, so a reader has one place to look and the pass cannot produce a second summary on a start that had holes.

INFORMATION even when Failures > 0. The issue asks for INFORMATION with the failure count and the file's conventions agree: the per-aggregate isolation already writes a WARNING naming the aggregate and the message. The summary's job is the census; repeating the failure at WARNING would count it twice in any warning-rate read of the service log.

Found counted before the cap. Otherwise "found" is just "repaired plus deferred" restated, and the reader cannot tell one 26-bucket hole from a 24 and a 2. The straddle is real (the cap splits exactly at the budget — CapMaterializationHoleRepairs), so the record's summary states the relationship instead of leaving the reader to reconcile three numbers that do not add.

What this does NOT do

• Does not touch the launch site (holeRepair = RunMaterializationHoleRepairAsync(...)), the drain, EvaluatePgLongRunningQueryAsync, LatestCpuSql, or anything else in DarlingWorker.cs — the hunk is the runner only.
• Does not change any scan, cap, refresh or dependency-order behaviour of the pass; no SQL changes; no rung.
• Does not add a line for the never-launched case — plain-PostgreSQL mode and the TimescaleDB-block fault already write theirs.
• Does not touch the sibling RunBaselineBackfillAsync, whose if (backfilled > 0) is the same silent-zero shape; it is coverage-gated to a no-op on every start after the first, so it is a separate noise decision, reported rather than made here.

Tests (Darling.Tests only — this is Darling-only code; Lite has no twin)

Executed here (net10.0 mactest harness against timescale/timescaledb:2.28.1-pg18, the CI tag, on desktop-linux):

• MaterializationHoleRepairTests 10/10 — the 8 existing pure pins plus two new: Worker_WritesTheSummaryLine_Unconditionally_AndThePassWritesNoneOfItsOwn (source pins: the runner takes the tally; the next LogInformation is the summary; no if ( or return; between call and line; every placeholder the tally carries is named; the cancellation arm exists, says "cancelled before it could report" and rethrows; the connection-open WARNING stays; the Storage file no longer contains the old summary template and does contain the found counters and the pass clock) and TheTally_CarriesEveryCountTheLineNames_AndStatesTheStraddleArithmetic. Red-first shown by mutation: gating the worker's line on summary.HolesFound > 0 → the source pin fails on the if (.
• MaterializationHoleRepairLiveTests 2/2 live: the existing outage-tail test extended — first pass HolesFound 1 / BucketsFound 2, Elapsed > 0, the pass writes no summary line of its own; the zero-hole second pass returns the walk (AggregatesScanned >= 1, Scanned + Skipped == Targets.Count, every hole count 0, Elapsed > 0, and nothing at Information or Warning from the pass) — this is the issue's named pin, on the tally the worker's unconditional line reports. New OneHoleRepairedAndOneDeferred_TheTallyCarriesFoundRepairedAndDeferredExactly_AgainstDevPostgres: one 26-bucket hole planted below the hourly policy window and inside the raw horizon, under the 24-bucket cap → found 1 / 26, repaired 1 / 24, deferred 1 / 2 on the same pass, buckets add up, ranges exceed found by one, the deferral line names [H25, H27) and the cap; pass two repairs the remainder 1 / 2; pass three is the zero walk. Red-first shown by mutation: holesFound += 0 → both live tests fail Expected: 1, Actual: 0.
• Censuses: RepoFileAdoptionTests, StragglerCommandTimeoutTests, LiveCleanupConversionRatchetTests, MeasurementContractCensusTests, McpPageContractTests, FleetIdentifierScrubTests, LivePostgresCollectionHygieneTests, DocCommentHygieneTests (76/77; the one red is TheDerivedProjectListCoversEveryProjectInTheTree finding the uncommitted harness csproj — the documented artifact). Harness total 220/221 for the same reason.
• Storage, Service and the real Darling.Tests (net10.0-windows) each build -c Release -p:EnableWindowsTargeting=true with 0 warnings.

CI-first: nothing of substance — the worker's line is a LogInformation over the record's fields and cannot be driven here (the worker is a hosted service); its shape is pinned by source and its inputs live. The full Darling.Tests run on Windows is CI's.

The existing Worker_LaunchesTheRepair… pin's ReadWorkerSource private root walk is retired for RepoFile.ReadRepoFile (raw; every anchor is single-line, so it is deliberately not on the LF roster).

Closes #3756