[DX-5482] fix gap exceeds maxGap on startup

[Tofel]

Fixes a spurious "gap exceeds maxGap" failure when the classification window opens inside the recorder's/check's first-observation pass.
Adds Header.ReadyAt stamped after the pass; check refuses from < ReadyAt in recorder mode; single-step (live mode) clamps from to the pass completion with a blind-interval warning; the recorder child and live poller continue the first observations' schedule (NewSchedulerFromPolls) instead of re-staggering; CheckStartupHandoff simulates the poller's first cycles and refuses unsafe schedules at startup; budget errors now name rules by title and suggest the minimum concurrency.

[github-actions]

👋 Tofel, thanks for creating this pull request!

To help reviewers, please consider creating future PRs as drafts first. This allows you to self-review and make any final changes before notifying the team.

Once you're ready, you can mark it as "Ready for review" to request feedback. Thanks!

[github-actions]

📊 API Diff Results

No changes detected for module github.com/smartcontractkit/chainlink-testing-framework/grafana-alertcheck

View full report

[Copilot]

Copilot review overview

🟡 Changes recommended

Timestamp truncation, unordered concurrent dispatch, and unchanged schema versioning leave startup coverage guarantees incomplete.

Review effort: Balanced
Findings: 2 · 2

Open (4)

• ReadyAt requires a new schema version with legacy v1 support · New
• Polling model assumes an order the real dispatcher does not guarantee · New
• Truncated timestamps allow startup windows before exact readiness · New
• Whole-second comparison permits unbudgeted pre-readiness intervals · New

What changed in this PR

Fixes startup coverage gaps by recording readiness, preserving poll schedules, and validating startup handoffs.

Changes:

• Adds ReadyAt and startup-window handling.
• Continues seeded polling schedules across handoffs.
• Improves budget validation, diagnostics, tests, and documentation.

File	Description
internal/​gate/​watch.go	Records readiness and seeds the child scheduler.
internal/​gate/​watch_test.go	Tests readiness and seeded recording.
internal/​gate/​source_fake_test.go	Adds virtual-clock advancement.
internal/​gate/​schedule.go	Adds seeded scheduling and handoff simulation.
internal/​gate/​schedule_test.go	Tests scheduling, handoffs, and diagnostics.
internal/​gate/​log.go	Adds ready_at to headers.
internal/​gate/​coverage.go	Uses readiness for coverage bounds.
internal/​gate/​coverage_test.go	Tests readiness-bound coverage.
internal/​gate/​check.go	Handles startup blind intervals and seeded polling.
internal/​gate/​check_test.go	Tests recorder and live startup behavior.
docs/​reference/​log-format.md	Documents ready_at.
docs/​reference/​cli.md	Updates command behavior.
docs/​index.md	Updates single-step guidance.
docs/​architecture.md	Documents recorder handoff design.
docs/​advanced.md	Explains startup validation.
.changeset/​v0.1.7.md	Records release changes.

---

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

[Copilot]

Copilot review overview

🟡 Changes recommended

The handoff simulation can approve schedules whose real requeued polling order exceeds maxGap.

Review effort: Balanced
Findings: 1

Open (1)

• Suggests ineffective concurrency increase when minC is zero · New

Resolved since last review (4)

• Polling model assumes an order the real dispatcher does not guarantee
• ReadyAt requires a new schema version with legacy v1 support
• Whole-second comparison permits unbudgeted pre-readiness intervals
• Truncated timestamps allow startup windows before exact readiness

Previously missed (1)

In code that hasn't changed since last review

Misleading concurrency recommendation for non-utilization failures

grafana-alertcheck/​internal/​gate/​schedule.go:400

This branch is reached only when utilization already fits; the remaining per-rule and burst-bound failures cannot be fixed by adding workers because concurrency does not shorten a request. Keeping “raising concurrency” here sends operators toward a change that will still fail the same check.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The handoff simulation can allocate memory proportional to an unbounded concurrency value, and one ReadyAt comment is inaccurate.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Suggests ineffective concurrency increase when minC is zero

Previously missed (2)

In code that hasn't changed since last review

Cap simulated concurrency to prevent excessive allocations

grafana-alertcheck/​internal/​gate/​handoff.go:100

--concurrency has no upper bound, and unlike observeAll, this simulation allocates one heap entry per requested worker. A value much larger than the rule count can therefore allocate enormous slices (and repeat that allocation per batch) even though the real poller can never use more than one worker per rule. Cap the simulated worker count to the remaining job count.

Correct outdated zero-value ReadyAt documentation

grafana-alertcheck/​internal/​gate/​log.go:74

This comment is now inconsistent with single-step construction: check stamps the synthesized header's ReadyAt after the first-observation pass. Only legacy log headers leave this field zero, so documenting single-step synthesis as another zero-value case is misleading.