Add beforeAttempt hook and default traceparent enrichment in contextIdPlugin

[gkoos]

Summary

Add per-attempt observability metadata with minimal surface area by extending the existing contextIdPlugin and adding one new core plugin hook.

Goals

• Keep the core plugin set small (no parallel telemetry-header plugin variants)
• Preserve existing contextIdPlugin behavior by default
• Add raceparent propagation that is default-on
• Keep and enrich incoming raceparent by default

Proposed Changes

1) Add a new core hook

Add one new plugin lifecycle hook that runs immediately before each physical fetch attempt.

Proposed signature:

• �eforeAttempt?: (ctx: PluginRequestContext, attempt: number) => void | Promise

Semantics:

• �ttempt is 1-based
• Called for the initial attempt and every retry attempt
• Called for hedged attempts as well
• Runs after preRequest, before dispatching that specific attempt

2) Extend contextIdPlugin (no new competing plugin)

Enhance contextIdPlugin to optionally emit W3C Trace Context raceparent header.

Default behavior:

• x-context-id: remains enabled (current behavior)
• raceparent: enabled by default
• Incoming raceparent: keep and enrich by default

Trace model:

• Logical request: one stable trace-id
• Physical attempt: new span-id per attempt
• Header format: 0---

When incoming raceparent exists:

• Parse and reuse trace-id + flags
• Generate a new span-id for each attempt
• If parsing fails, fallback to generated trace-id/span-id

3) Minimal plugin API extension

Proposed options on contextIdPlugin:

• existing: generate, inject, order
• new: raceparent?: boolean | { enabled?: boolean; flags?: string }

Keep defaults simple and backwards-compatible.

Acceptance Criteria

• New hook exists and is documented in plugin lifecycle types/docs
• contextIdPlugin writes raceparent by default
• Same logical request keeps stable trace-id across retries/hedges
• Each attempt gets a distinct span-id
• Incoming valid raceparent is preserved/enriched by default
• Existing context-id tests still pass
• New tests cover retry and hedge attempt behavior for raceparent

Notes

This intentionally avoids introducing multiple first-party plugins for similar observability concerns. One hook + one plugin evolution keeps the API small.