feat(records): monotonic atUs, interaction links, request ids and frame self time

[anilcancakir]

What

• Records carry a monotonic atUs, an interactionId with linkedBy (zone, frame, window), request ids, and frame block self time.

Why

• dusk's perf report joins HTTP, logs and frames to the gesture that caused them; wall-clock timestamps and anonymous records could not be joined.

Testing

• flutter test green.

Part of the LLM-first perf tracing set; release after wind_diagnostics_contracts.

[kodizm]

Note

Kodizm (AI-generated). May contain mistakes; verify before acting.

The new fields and the self-time stack walk look correct, but FramePerfRecord.blocks changes its public type while the CHANGELOG says nothing breaks, and the skill reference pages were not updated.

Major

lib/src/records/frame_perf_record.dart:43: blocks goes from Map<String, ({int micros, int count})> to Map<String, ({int micros, int selfMicros, int count})>. Dart record types with different fields are not assignable to each other, so any consumer that builds a FramePerfRecord with the old map type, or declares a variable of the old type from record.blocks, stops compiling. FramePerfRecord is exported from lib/telescope.dart, and this PR had to edit test/src/extensions/register_telescope_extensions_test.dart for exactly this reason. The CHANGELOG bullet says "Every new field is optional or defaulted, so every existing constructor call ... keeps compiling", which is not true for this field. It should be listed under ### Changed as a breaking change (correctness/API).

skills/fluttersdk-telescope/references/records.md:149: this still documents blocks as {name: {micros, count}} and has none of atUs, vsyncStartUs, interactionId, linkedBy or requestId/startUs/endUs. references/mcp-tools.md:350 and the telescope:frames sample output in references/cli-commands.md:208 are also stale. This breaks CLAUDE.md Golden Rule 2 (skill sync, which covers references/). Only SKILL.md was updated.

Minor

lib/src/commands/telescope_frames_command.dart:41: linkedBy is printed only when interactionId != null. But the new docblocks define linkedBy: window as the case where interactionId is null, so the CLI never shows that value. The same applies to telescope_requests_command.dart:38.

Tests

Covered: each record has new tests for toJson/atUs/link fields, the frames and requests command output has tests, and frame_perf_watcher_test.dart covers the selfMicros nesting computation.

CI

Lint & Test: success. Auto-merge low-risk Dependabot PRs: skipped.

[codecov]

Codecov Report

❌ Patch coverage is 98.61111% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
lib/src/watchers/frame_perf_watcher.dart	96.66%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[anilcancakir]

Round 1 fixes, all in 374de74:

• Major, lib/src/records/frame_perf_record.dart:43 (blocks type change undeclared): agreed, the record types are not assignable. CHANGELOG.md now has a ### Changed entry, BREAKING: FramePerfRecord.blocks is Map<String, ({int micros, int selfMicros, int count})>, with the two cases that stop compiling and the migration (add selfMicros, or let the type be inferred), and notes the JSON only gains a key. The ### Added bullet no longer says every existing constructor call keeps compiling; it names blocks as the exception.
• Major, skill references stale: references/records.md now documents atUs, interactionId and linkedBy on HTTP, event, query, frame, cache and model records; requestId, startUs, endUs on HTTP; vsyncStartUs and {micros, selfMicros, count} on frames. references/mcp-tools.md (telescope_frames returns) and both sample outputs in references/cli-commands.md (telescope:frames, telescope:requests) show the new fields.
• Minor, telescope_frames_command.dart:41 and telescope_requests_command.dart:38 (linkedBy=window never printed): each half of the suffix is now printed on its own. Reproduced first: two new tests, prints linkedBy=window, which carries no interactionId, failed on the old code and pass now.

Gates: flutter analyze no issues, flutter test 351 passed, dart format 0 changed.

@kodizm please re-review.

[kodizm]

Note

Kodizm (AI-generated). May contain mistakes; verify before acting.

All three round-1 findings are fixed in 374de74, and I found nothing new. This looks ready to merge.

This re-review covers only commit 374de74. The earlier commits were reviewed last round and have not changed.

• blocks type change: CHANGELOG.md now lists it under ### Changed as BREAKING, with a migration path. The ### Added bullet no longer claims every constructor call keeps compiling.
• Stale skill references: references/records.md, mcp-tools.md and cli-commands.md now document atUs, interactionId, linkedBy, requestId/startUs/endUs, vsyncStartUs and selfMicros. That satisfies CLAUDE.md Golden Rule 2. The telescope:frames and telescope:requests sample output now matches the field order and → arrow in the command code.
• linkedBy=window never printed: the frames and requests commands now print interactionId and linkedBy separately, so linkedBy=window appears when interactionId is absent. Records with neither field still print no suffix, which the existing negative test checks.

Tests

There is a new prints linkedBy=window, which carries no interactionId test in both telescope_frames_command_test.dart and telescope_requests_command_test.dart. The earlier record, watcher and command tests still cover the rest of the change.

CI

• Lint & Test: success.
• codecov/patch: success (98.61% of the diff covered, target 97.56%).
• Auto-merge low-risk Dependabot PRs: skipped.