@rangojs/router 0.0.0-experimental.126 → 0.0.0-experimental.128

package/src/index.ts

@@ -344,7 +344,12 @@ export {
 // bundle analysis output and slow build-time module resolution. Consumers
 // who need the values in non-RSC contexts can import from
 // `@rangojs/router/server`.
-export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
+export type {
+  OTelTracer,
+  OTelActiveSpanTracer,
+  OTelSpan,
+  OTelTracingOptions,
+} from "./router/telemetry-otel.js";
 // The full TelemetryEvent union PLUS its member types, so a consumer writing a
 // TelemetrySink can annotate a per-`type` handler (or construct an event literal
 // in a test) instead of only narrowing the opaque union.
@@ -366,6 +371,16 @@ export type {
   OriginCheckRejectedEvent,
 } from "./router/telemetry.js";
 
+// Span tracing config types a consumer annotates. SpanRunner/TraceSpan are the
+// internal runner contract (consumers go through createOTelTracing /
+// createCloudflareTracing, which return a ready RouterTracingConfig) and are not
+// exported.
+export type {
+  RouterTracingConfig,
+  TracePhase,
+  TracePhaseToggles,
+} from "./router/tracing.js";
+
 // Timeout types and error class
 export { RouterTimeoutError } from "./router/timeout.js";
 export type {

package/src/route-definition/dsl-helpers.ts

@@ -524,6 +524,22 @@ const middleware: RouteHelpers<any, any>["middleware"] = (...args: any[]) => {
   } as MiddlewareItem;
 };
 
+// Slot names become part of segment ids: a parallel/intercept slot is encoded
+// as `${shortCode}.${slotName}`, and loader segments append `D${index}.${loaderId}`.
+// A "." in the slot name collides with that separator -- loaderParentId
+// (segment-system.tsx) strips from the FIRST `D<index>.`, so a name like
+// "@D3.foo" is mis-cut to "@" and the loader's data is silently dropped. Reject
+// the dot at definition time so the failure is loud, not a corrupted tree at
+// runtime. (A bare "D" without a trailing dot -- e.g. "@Detail" -- is fine.)
+function assertValidSlotName(slotName: string): void {
+  invariant(
+    !slotName.includes("."),
+    `Slot name "${slotName}" must not contain ".". The dot is a reserved ` +
+      `segment-id separator; a name like "@D3.foo" corrupts loader segment-id ` +
+      `parsing and silently drops the loader's data. Rename the slot.`,
+  );
+}
+
 const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
   const { store, ctx } = requireDslContext(
     "parallel() must be called inside urls()",
@@ -539,6 +555,7 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
   );
 
   const slotNames = Object.keys(slots as Record<string, any>) as `@${string}`[];
+  for (const slotName of slotNames) assertValidSlotName(slotName);
 
   const namespace = `${ctx.namespace}.$${store.getNextIndex("parallel")}`;
 
@@ -698,6 +715,8 @@ const intercept = (
     "intercept() cannot be used inside parallel()",
   );
 
+  assertValidSlotName(slotName);
+
   const namespace = `${ctx.namespace}.$${store.getNextIndex("intercept")}.${slotName}`;
 
   // Dot-prefixed = local (add include prefix), unprefixed = global (use as-is)

package/src/router/instrument.ts

@@ -0,0 +1,440 @@
+/**
+ * Phase + event instrumentation — the single internal API for observing router
+ * work.
+ *
+ * The router exposes the same work on three surfaces, and the rule is: each
+ * surface has exactly one owner here, so they cannot drift.
+ *
+ *   - observePhase(): a span of work. Co-emits the `debugPerformance` perf
+ *     metric (metrics store -> [RSC Perf] timeline + Server-Timing) AND the
+ *     platform span (tracing runner -> Cloudflare custom spans / OTel). From one
+ *     wrap site, so the span set is always a subset of the perf phases and the
+ *     two can't disagree. Phases that meter their own perf metric with a finer
+ *     decomposition (request, middleware) pass `metric: false` and get the span
+ *     only — still co-located, still one owner per surface.
+ *   - observeEvent(): a discrete fact (TelemetrySink): cache decisions,
+ *     revalidation decisions, handler errors, timeouts, origin rejections.
+ *     Event-shaped, not phase-shaped — derived from the same call sites but a
+ *     separate surface from spans.
+ *
+ * Why phases, not events, are the parent abstraction: Cloudflare's span API is
+ * callback-bound (enterSpan wraps the actual work), so the callback boundary is
+ * the source of truth — async-context nesting (a loader's KV/D1/fetch spans
+ * landing under rango.loader) cannot be faithfully reconstructed from
+ * after-the-fact start/end events. Spans drive; events are emitted alongside.
+ *
+ * Phase identity lives in the PHASES registry below, so the raw `rango.*` span
+ * names, perf-metric labels, and span attributes have a single definition each.
+ *
+ * When neither perf surface nor tracing is active on the request, observePhase
+ * is a direct call — no wrapper, no timestamp, no allocation.
+ */
+
+import { _getRequestContext } from "../server/request-context.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
+import { getRouterContext } from "./router-context.js";
+import { resolveSink, safeEmit, type TelemetryEvent } from "./telemetry.js";
+import { appendMetric } from "./metrics.js";
+import { type MetricsStore } from "../server/context.js";
+import {
+  NOOP_TRACE_SPAN,
+  traceSpan,
+  runThenSettle,
+  type TracePhase,
+  type TraceSpan,
+  type ResolvedTracing,
+} from "./tracing.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
+
+/**
+ * Perf-metric boundary for a phase, or `false` for span-only. `false` means the
+ * caller records its own perf metric with a finer decomposition than a single
+ * wrap (request: a grand total incl. pre-context bootstrap; middleware: pre/post
+ * own-time), so observePhase opens the span but records no metric of its own.
+ */
+export type PhaseMetric =
+  | { label: string | (() => string); depth?: number }
+  | false;
+
+/** Describes one observable phase across the perf and span surfaces. */
+export interface PhaseSpec {
+  /** Perf timeline label + Server-Timing name, or false for span-only. */
+  metric: PhaseMetric;
+  /** Span phase gate (per-phase toggle in the tracing config). */
+  tracePhase: TracePhase;
+  /** Span name (rango.*). */
+  spanName: string;
+  /** Span attributes set automatically when the span opens. */
+  attributes?: Record<string, string | number | boolean>;
+}
+
+/**
+ * The router's observable phases. One definition per phase keeps the `rango.*`
+ * span names, perf-metric labels, and identifying attributes from spreading
+ * across call sites.
+ */
+export const PHASES = {
+  /** Whole request pipeline. Span only — handler:total is metered directly. */
+  request: {
+    metric: false,
+    tracePhase: "request",
+    spanName: "rango.request",
+  } as PhaseSpec,
+
+  /** One middleware (incl. its downstream onion). Span only — the perf metric
+   * is the middleware's exclusive pre/post own-time, recorded directly.
+   * `metricLabel` is that metric's label (e.g. "middleware:auth@*"); it doubles
+   * as the rango.middleware_name span attribute. */
+  middleware: (metricLabel: string): PhaseSpec => ({
+    metric: false,
+    tracePhase: "middleware",
+    spanName: "rango.middleware",
+    attributes: { "rango.middleware_name": metricLabel },
+  }),
+
+  /** The server-action execution (decode args + run the action body), before
+   * the revalidation render. The metric label carries the action id (the
+   * _rsc_action / action $$id) so the perf timeline shows WHICH action ran, not
+   * just "an action"; the span also gets it as rango.action_id. */
+  action: (id: string): PhaseSpec => ({
+    metric: { label: `action:${id}` },
+    tracePhase: "action",
+    spanName: "rango.action",
+    attributes: { "rango.action_id": id },
+  }),
+
+  /**
+   * One loader execution. `depth` is the perf-timeline indentation: 2 (default)
+   * for render-time loaders that nest under the render phase; 1 for a standalone
+   * fetchable `_rsc_loader` request, which has no render parent.
+   */
+  loader: (id: string, depth: number = 2): PhaseSpec => ({
+    metric: { label: `loader:${id}`, depth },
+    tracePhase: "loader",
+    spanName: "rango.loader",
+    attributes: { "rango.loader_id": id },
+  }),
+
+  /** Whole render phase: match + serialize + SSR. The metric label is resolved
+   * lazily at record time (after match has set the route name) so the perf
+   * timeline shows WHICH route rendered: `render:total:<routeName>`, falling back
+   * to `render:total` when there is no named route (unmatched / auto-generated). */
+  render: {
+    metric: {
+      label: () => {
+        const routeName = _getRequestContext()?._routeName;
+        return routeName && !isAutoGeneratedRouteName(routeName)
+          ? `render:total:${routeName}`
+          : "render:total";
+      },
+    },
+    tracePhase: "render",
+    spanName: "rango.render",
+  } as PhaseSpec,
+
+  /** SSR HTML render from the RSC stream. Colon-delimited like the other ssr:*
+   * setup metrics (ssr:module-load / ssr:stream-mode). */
+  ssr: {
+    metric: { label: "ssr:render-html" },
+    tracePhase: "ssr",
+    spanName: "rango.ssr",
+  } as PhaseSpec,
+} as const;
+
+/** Apply a phase spec's static attributes to a span (the no-op span ignores them). */
+function applyAttributes(
+  span: TraceSpan,
+  attributes: Record<string, string | number | boolean>,
+): void {
+  for (const key in attributes) span.setAttribute(key, attributes[key]);
+}
+
+/**
+ * Record a phase's perf metric for the interval [start, now]. The label may be
+ * lazy (resolved here, e.g. render:total needs the route name that match sets
+ * partway through the wrapped work).
+ */
+function recordPhaseMetric(
+  store: MetricsStore,
+  metric: Exclude<PhaseMetric, false>,
+  start: number,
+): void {
+  const label =
+    typeof metric.label === "function" ? metric.label() : metric.label;
+  appendMetric(store, label, start, performance.now() - start, metric.depth);
+}
+
+/**
+ * Instrument one unit of work: open its span AND (unless `metric: false`) record
+ * its perf metric, from a single wrap site. fn is invoked exactly once with the
+ * span (a no-op span when tracing is off); its return value is returned
+ * unchanged and thrown errors / rejected promises propagate unchanged. When fn
+ * returns a promise both the metric duration and the span end when it settles.
+ *
+ * This is the boundary for NON-streaming phases (action, loader): both the span
+ * and the metric settle when their own work completes. Streaming phases (request,
+ * middleware, render, ssr) use observeRequestPhase / observeStreamingPhase, where
+ * the SPAN is held open until body-drain (valid tree) while the perf metric is
+ * still recorded at construction (Server-Timing parity).
+ *
+ * Reads the metrics store + tracing off the RequestContext ALS, which is active
+ * for the WHOLE request — contrast observeEvent, which reads the RouterContext
+ * ALS (entered later, during match).
+ */
+export function observePhase<T>(
+  spec: PhaseSpec,
+  fn: (span: TraceSpan) => T,
+): T {
+  const reqCtx = _getRequestContext();
+  const store = reqCtx?._metricsStore;
+  const tracing = reqCtx?._tracing;
+
+  // Neither surface active: direct call, zero overhead.
+  if (!store && !tracing) return fn(NOOP_TRACE_SPAN);
+
+  // Attributes only land on a real span, so skip the wrapper when only the perf
+  // surface is active (traceSpan would apply them to NOOP_TRACE_SPAN for nothing).
+  const attributes = spec.attributes;
+  const wrapped: (span: TraceSpan) => T =
+    attributes && tracing
+      ? (span) => {
+          applyAttributes(span, attributes);
+          return fn(span);
+        }
+      : fn;
+
+  const runSpan = (): T =>
+    traceSpan(tracing, spec.tracePhase, spec.spanName, wrapped);
+
+  // Span-only — no perf metric to record (metric:false, or perf surface off).
+  const metric = spec.metric;
+  if (!store || metric === false) return runSpan();
+
+  // Record the phase duration on EVERY termination — success or failure — so a
+  // failed loader/render still shows its timing in the perf report (parity with
+  // the old track().finally() path it replaced).
+  const start = performance.now();
+  return runThenSettle(runSpan, () => recordPhaseMetric(store, metric, start));
+}
+
+/**
+ * Re-stream `response`'s body through a pass-through that fires `onDrain` exactly
+ * once when the body finishes — on natural end, a stream error, or a client
+ * cancel (so a span can never leak on an aborted response). A bodyless response
+ * fires immediately. Only used while instrumentation is active, so the per-chunk
+ * relay cost never touches an untraced request.
+ */
+function instrumentResponseDrain(
+  response: Response,
+  onDrain: () => void,
+): Response {
+  // WS-upgrade responses (status 101 / workerd `webSocket` property) must never
+  // be reconstructed: `new Response(body, { status: 101 })` throws and a copy
+  // drops the non-standard webSocket handoff (the invariant every other Response
+  // reconstruction site honors). A bodyless response has nothing to drain.
+  const source = response.body;
+  if (!source || isWebSocketUpgradeResponse(response)) {
+    onDrain();
+    return response;
+  }
+  let fired = false;
+  const fire = (): void => {
+    if (fired) return;
+    fired = true;
+    onDrain();
+  };
+  const reader = source.getReader();
+  const wrapped = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read();
+        if (done) {
+          controller.close();
+          fire();
+          return;
+        }
+        controller.enqueue(value);
+      } catch (error) {
+        controller.error(error);
+        fire();
+      }
+    },
+    cancel(reason) {
+      fire();
+      return reader.cancel(reason);
+    },
+  });
+  return new Response(wrapped, response);
+}
+
+/**
+ * Shared engine for the streaming phases (request, middleware, render, ssr). It
+ * opens the span, runs fn, records the phase's perf metric at CONSTRUCTION (so it
+ * still reaches the Server-Timing header / [RSC Perf] table, both built before
+ * the body drains), hands the constructed value to the caller via a side channel
+ * (streaming preserved), then holds the span open until `drain` resolves. The
+ * SPAN therefore ends at body-drain — keeping the trace tree valid (a loader
+ * child that resolves mid-stream ends before its parent) — while the perf metric
+ * stays the construction work-time. `onDeliver` lets the request phase instrument
+ * the final body before handing it back; `onError` lets it release the barrier on
+ * failure. Fire-and-forget: the value reaches the caller via the returned
+ * promise, so the span promise's rejection is swallowed (already surfaced there).
+ */
+function runDrainBoundPhase<R>(
+  spec: PhaseSpec,
+  fn: (span: TraceSpan) => R | Promise<R>,
+  tracing: ResolvedTracing | undefined,
+  store: MetricsStore | undefined,
+  drain: Promise<void>,
+  onDeliver: (value: R) => R,
+  onError?: () => void,
+): Promise<R> {
+  let deliver!: (value: R) => void;
+  let reject!: (error: unknown) => void;
+  const delivered = new Promise<R>((res, rej) => {
+    deliver = res;
+    reject = rej;
+  });
+
+  const start = performance.now();
+  const attributes = spec.attributes;
+  const metric = spec.metric;
+  const record = (): void => {
+    if (store && metric !== false) recordPhaseMetric(store, metric, start);
+  };
+  const spanCallback = async (span: TraceSpan): Promise<void> => {
+    if (attributes && tracing) applyAttributes(span, attributes);
+    let value: R;
+    try {
+      value = await fn(span);
+    } catch (error) {
+      record(); // a failed phase still shows its (construction) timing
+      onError?.();
+      reject(error);
+      throw error; // settle the span with the error, at construction
+    }
+    record(); // construction-bound metric, before the response/header is built
+    deliver(onDeliver(value));
+    await drain; // hold the span open until the response body drains
+  };
+
+  traceSpan(tracing, spec.tracePhase, spec.spanName, spanCallback).catch(
+    () => {},
+  );
+  return delivered;
+}
+
+/**
+ * The request phase (rango.request, metric:false). Owns the drain barrier: it
+ * runs fn to construct the final Response, instruments that Response's body so
+ * the barrier resolves at drain, hands the Response to the caller immediately
+ * (streaming preserved), and holds the span open until the body drains. Every
+ * streaming inner phase awaits the same barrier (via observeStreamingPhase), so
+ * the request/middleware/render/ssr chain ends at body-drain together and the
+ * trace tree is valid (no child span outlives its parent). The perf metrics
+ * (render:total, …) are recorded at construction so they still reach the
+ * Server-Timing header; only the SPANS are drain-bound. ctx.waitUntil holds the
+ * worker alive until drain so the span end runs. Pass-through when no surface is
+ * active.
+ */
+export function observeRequestPhase(
+  spec: PhaseSpec,
+  fn: (span: TraceSpan) => Promise<Response>,
+): Promise<Response> {
+  const reqCtx = _getRequestContext();
+  const store = reqCtx?._metricsStore;
+  const tracing = reqCtx?._tracing;
+
+  if ((!store && !tracing) || !reqCtx) return fn(NOOP_TRACE_SPAN);
+
+  let resolveDrain!: () => void;
+  const finalDrain = new Promise<void>((resolve) => {
+    resolveDrain = resolve;
+  });
+  reqCtx._finalDrain = finalDrain;
+
+  // Keep the worker alive until the body drains, so the drain-bound span end
+  // (and the inner phases' settle) runs before the runtime can reclaim it.
+  const ec = reqCtx.executionContext;
+  if (typeof ec?.waitUntil === "function") ec.waitUntil(finalDrain);
+
+  return runDrainBoundPhase<Response>(
+    spec,
+    fn,
+    tracing,
+    store,
+    finalDrain,
+    (response) => instrumentResponseDrain(response, resolveDrain),
+    resolveDrain, // release the barrier if fn fails before constructing a body
+  );
+}
+
+/**
+ * A streaming inner phase (rango.middleware / render / ssr). Its SPAN settles
+ * when the request's final response body drains (the barrier owned by
+ * observeRequestPhase), not when fn returns the constructed stream — so
+ * loader/Suspense children that resolve mid-stream nest under a still-open
+ * parent. fn's result is delivered at construction (streaming preserved) and the
+ * perf metric is recorded at construction (Server-Timing parity). Falls back to
+ * observePhase (construction-bound span) when there is no barrier — a
+ * non-streaming request, or instrumentation off.
+ */
+export function observeStreamingPhase<R>(
+  spec: PhaseSpec,
+  fn: (span: TraceSpan) => R | Promise<R>,
+): Promise<R> {
+  const reqCtx = _getRequestContext();
+  const store = reqCtx?._metricsStore;
+  const tracing = reqCtx?._tracing;
+  const finalDrain = reqCtx?._finalDrain;
+
+  if ((!store && !tracing) || !finalDrain) {
+    return Promise.resolve(observePhase(spec, fn));
+  }
+  return runDrainBoundPhase<R>(
+    spec,
+    fn,
+    tracing,
+    store,
+    finalDrain,
+    (value) => value,
+  );
+}
+
+/**
+ * Emit one discrete telemetry event (the event-shaped counterpart to
+ * observePhase). Resolves the sink from the active router context and stamps the
+ * request id when the event omits it. No-op (and total — never throws) when no
+ * sink is configured.
+ *
+ * This is the canonical emitter for SYNCHRONOUS facts that fire inside the
+ * request's ALS scope (handler errors, timeouts, origin rejections, revalidation
+ * decisions). A few emitters deliberately stay on the lower-level
+ * resolveSink + safeEmit because observeEvent's lazy, per-call
+ * getRouterContext() read does not fit them — keep this the complete list:
+ *   - router.ts wrapLoaderPromise (loader.start/end/error) and
+ *     segment-resolution/streamed-handler-telemetry.ts (streamed handler.error)
+ *     capture the sink + request id EAGERLY and emit from a fire-and-forget
+ *     continuation that runs after the ALS scope may have unwound.
+ *   - router/match-handlers.ts resolves the sink ONCE for the hot match-pipeline
+ *     loop (request.start/end/error, cache.decision, ...).
+ *   - segment-resolution/helpers.ts emits via a caller-provided report.telemetry
+ *     sink rather than the ALS router context.
+ */
+export function observeEvent(event: TelemetryEvent): void {
+  // getRouterContext() either throws (real impl, outside a router context — e.g.
+  // the build-time prerender path) or returns null/undefined (e.g. mocked).
+  // Either way there is no sink to emit to, so swallow and return.
+  let routerCtx: ReturnType<typeof getRouterContext> | null | undefined;
+  try {
+    routerCtx = getRouterContext();
+  } catch {
+    return;
+  }
+  if (!routerCtx?.telemetry) return;
+  const stamped =
+    event.requestId === undefined && routerCtx.requestId !== undefined
+      ? ({ ...event, requestId: routerCtx.requestId } as TelemetryEvent)
+      : event;
+  safeEmit(resolveSink(routerCtx.telemetry), stamped);
+}

package/src/router/loader-resolution.ts

@@ -5,8 +5,8 @@
  */
 
 import type { ReactNode } from "react";
-import { track } from "../server/context";
 import type { EntryData } from "../server/context";
+import { observePhase, PHASES } from "./instrument.js";
 import { contextGet } from "../context-var.js";
 import type {
   ResolvedSegment,
@@ -382,7 +382,11 @@ function createLoaderExecutor<TEnv>(
       },
     };
 
-    const doneLoader = track(`loader:${loader.$$id}`, 2);
+    // Meter this loader once via observePhase (loader:<id> perf metric +
+    // rango.loader span); loaderFn runs inside the span callback so its KV/D1/
+    // fetch spans nest under it. This is one of the observePhase loader funnels —
+    // see instrument.ts for the single-metering contract.
+    //
     // Run the loader body inside loader scope so request-scoped reads
     // (cookies()/headers() and non-cacheable ctx.get) are exempt from the
     // cache-purity guards: loaders always run fresh, so their reads never leak
@@ -392,14 +396,15 @@ function createLoaderExecutor<TEnv>(
     // throw. rendered() gating uses the captured isDslLoader (above), so this
     // does not grant rendered() to handler-invoked loaders. Uses a body-only
     // scope, so isInsideLoaderScope() / barrier / deadlock gating is unchanged.
-    const promise = Promise.resolve(
-      runInsideLoaderBodyScope(() =>
-        loaderFn(loaderCtx as LoaderContext<any, TEnv>),
-      ),
-    ).finally(() => {
-      pendingLoaders.delete(loader.$$id);
-      doneLoader();
-    });
+    const promise = observePhase(PHASES.loader(loader.$$id), () =>
+      Promise.resolve(
+        runInsideLoaderBodyScope(() =>
+          loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+        ),
+      ).finally(() => {
+        pendingLoaders.delete(loader.$$id);
+      }),
+    );
 
     loaderPromises.set(loader.$$id, promise);
     return promise;

package/src/router/match-middleware/cache-lookup.ts

@@ -94,7 +94,7 @@
 import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext, type RouterContext } from "../router-context.js";
-import { resolveSink, safeEmit } from "../telemetry.js";
+import { observeEvent } from "../instrument.js";
 import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
 import { treeHasStreaming } from "./segment-resolution.js";
 import type { PrerenderStore, PrerenderEntry } from "../../prerender/store.js";
@@ -546,19 +546,14 @@ export function withCacheLookup<TEnv>(
         traceSource: "cache-hit",
       });
 
-      const routerCtx = getRouterContext<TEnv>();
-      if (routerCtx.telemetry) {
-        const tSink = resolveSink(routerCtx.telemetry);
-        safeEmit(tSink, {
-          type: "revalidation.decision",
-          timestamp: performance.now(),
-          requestId: routerCtx.requestId,
-          segmentId: segment.id,
-          pathname: ctx.pathname,
-          routeKey: ctx.routeKey,
-          shouldRevalidate,
-        });
-      }
+      observeEvent({
+        type: "revalidation.decision",
+        timestamp: performance.now(),
+        segmentId: segment.id,
+        pathname: ctx.pathname,
+        routeKey: ctx.routeKey,
+        shouldRevalidate,
+      });
 
       if (!shouldRevalidate) {
         segment.component = null;

package/src/router/match-middleware/cache-store.ts

@@ -168,6 +168,18 @@ export function withCacheStore<TEnv>(
     if (!requestCtx) return;
 
     const cacheScope = ctx.cacheScope;
+
+    // Record the route's segment-DSL cache tags into the request tag union NOW,
+    // synchronously in the pipeline. The actual store write (cacheRoute) runs in
+    // requestCtx.waitUntil() below — and the proactive path re-resolves the whole
+    // tree first — so cacheRoute's own tag recording races the document cache's
+    // post-body-drain snapshot of _requestTags. On a first-write miss the document
+    // tag union could miss these tags and revalidateTag()/updateTag() would not
+    // invalidate the cached document. Recording here (before the snapshot) closes
+    // the window for both the direct and proactive write paths; the duplicate
+    // record inside cacheRoute is idempotent.
+    cacheScope.recordTags(requestCtx);
+
     const reqId = INTERNAL_RANGO_DEBUG
       ? getOrCreateRequestId(ctx.request)
       : undefined;

package/src/router/middleware.ts

@@ -19,6 +19,7 @@ import {
 } from "../redirect-origin.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { appendMetric, createMetricsStore } from "./metrics.js";
+import { observeStreamingPhase, PHASES } from "./instrument.js";
 import { stripInternalParams } from "./handler-context.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
@@ -478,9 +479,17 @@ export async function executeMiddleware<TEnv>(
       return nextPromise;
     };
 
+    // Wrap the middleware (including its downstream next() chain) in its span
+    // via the unified phase API. metric:false — the middleware's perf metric is
+    // its exclusive pre/post own-time, recorded directly above and below, finer
+    // than a single wrap. Spans nest by async context, so this onions
+    // middleware-over-middleware and the core handler underneath. Pass-through
+    // when neither surface is active.
     let result: Response | void;
     try {
-      result = await entry.handler(ctx, wrappedNext);
+      result = await observeStreamingPhase(PHASES.middleware(metricLabel), () =>
+        entry.handler(ctx, wrappedNext),
+      );
     } catch (error) {
       // Thrown Response is short-circuit control flow, not an error.
       // Fall through to the `if (result instanceof Response)` branch below
@@ -622,6 +631,7 @@ export async function executeInterceptMiddleware<TEnv>(
       return stubResponse;
     }
 
+    const ordinal = index;
     const middleware = middlewares[index++];
     const ctx = createMiddlewareContext(
       request,
@@ -643,9 +653,20 @@ export async function executeInterceptMiddleware<TEnv>(
       return next();
     };
 
+    // Span-wrap each intercept middleware as rango.middleware (metric:false —
+    // intercept runs inside the render phase already metered by render:total, so
+    // it contributes a span but no separate perf metric). Bare MiddlewareFns
+    // have no pattern, so the label is scoped to "*" like a pattern-less entry.
+    const label = getMiddlewareMetricLabel(
+      { handler: middleware, pattern: null } as MiddlewareEntry<TEnv>,
+      ordinal,
+    );
+
     let result: Response | void;
     try {
-      result = await middleware(ctx, guardedNext);
+      result = await observeStreamingPhase(PHASES.middleware(label), () =>
+        middleware(ctx, guardedNext),
+      );
     } catch (error) {
       // Thrown Response is short-circuit control flow, parity with the
       // explicit-return path below. Real errors propagate.