[mstoykov]

What?

Stack 3 of 6

Base: async-group-base (stack PR 2, #6341)

Head: feature/async-group-timers

The next PR will target this branch and add k6/websockets listener propagation.

When async-metric-context is enabled, setTimeout() and setInterval() capture the complete tags
and metadata active when their callback is registered. Each callback invocation applies a clone of
that snapshot and restores the context it interrupted afterward.

For repeating intervals, the already-wrapped callback is rearmed so every tick starts from the
original registration snapshot. Mutations made by one tick remain available to Promise work created
by that tick, through the tracker in stack PR 1, but do not leak into the parent or the next tick.

When the feature is disabled, timers use the existing direct callback path without capturing or
applying metric context.

Tests cover one-shot and repeating timers, group-tag propagation, complete tag and metadata
restoration, callback-mutation isolation, and reuse of the interval's registration snapshot. The
Promise tracker from stack PR 1 separately covers async descendants created by a timer callback.

Why?

Timer callbacks are scheduled by k6's timer and event-loop implementation, not as Sobek Promise
reactions. The Promise tracker therefore cannot infer the context in which setTimeout() or
setInterval() was called. Without an explicit snapshot, a timer fires under whatever mutable VU
context happens to be live at dispatch time, which can attribute its checks, custom metrics, and
asynchronous descendants to an unrelated group or set of tags.

Registration time is the stable ownership boundary: it reflects the operation that created the
timer. Dispatch-time capture would preserve the race, while carrying only the group tag would make
custom tags and metadata behave differently from Promise continuations.

Alternatives considered:

• A general wrapper around every event-loop task would not know which registration logically owns a
  timer and would affect unrelated internal tasks. Capturing in the timer API keeps the ownership rule
  explicit while reusing the common helper from stack PR 1.
• Capturing a new context whenever an interval rearms would make one tick's mutations leak into later
  ticks. Reusing the original wrapped callback gives intervals repeatable registration-time
  semantics.
• Implementing this only inside group() would miss timers registered under custom tag or metadata
  contexts and timers created without importing k6.

Checklist

• I have performed a self-review of my code.
• I have commented on my code, particularly in hard-to-understand areas.
• I have added tests for my changes.
• I have run linter and tests locally (make check) and all pass.

Checklist: Documentation (only for k6 maintainers and if relevant)

Please do not merge this PR until the following items are filled out.

• I have added the correct milestone and labels to the PR.
• I have updated the release notes: TBD for the complete experimental stack
• I have updated or added an issue to the
  k6-documentation: TBD for async metric-context semantics
• I have updated or added an issue to the
  TypeScript definitions:
  not applicable; timer signatures do not change

Related PR(s)/Issue(s)

• group doesn't work with async calls well (#2728)
  — its callback section describes the per-API boundary
• Implement AsyncContext via the TC39 standard for async groups
  (#5673)

[szkiba]

LGTM. Good work.