@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/router/find-match.ts

@@ -1,5 +1,8 @@
 import { tryTrieMatch } from "./trie-matching.js";
-import { getRouteTrie, getRouterTrie } from "../route-map-builder.js";
+import {
+  getRouterTrie,
+  isRouterTrieAuthoritative,
+} from "../route-map-builder.js";
 import {
   findMatch as findRouteMatch,
   isLazyEvaluationNeeded,
@@ -8,39 +11,55 @@ import {
 import type { MetricsStore } from "../server/context";
 import type { RouteEntry } from "../types";
 
+// The single-entry cache is module-lifetime, keyed only on pathname, so the same
+// result object is handed to every same-pathname request. ctx.params aliases
+// this object, so handlers mutating it would corrupt the cache for later requests.
+// Clone params; entry/flags are read-only and shared safely.
+function cloneMatchResult<TEnv>(
+  r: RouteMatchResult<TEnv> | null,
+): RouteMatchResult<TEnv> | null {
+  return r ? { ...r, params: { ...r.params } } : null;
+}
+
 export interface FindMatchDeps<TEnv = any> {
   routesEntries: RouteEntry<TEnv>[];
-  evaluateLazyEntry: (entry: RouteEntry<TEnv>) => void;
+  // Returns a Promise only when it had to resolve an async include provider
+  // (`() => import()`); void for eager/precomputed includes, so the per-entry
+  // match loop pays no microtask in the common case.
+  evaluateLazyEntry: (entry: RouteEntry<TEnv>) => void | Promise<void>;
   routerId: string;
 }
 
 /**
  * Create a findMatch function bound to router state.
  * Includes single-entry cache to avoid redundant matching within the same request.
+ *
+ * Async because a lazy include may be backed by an async provider
+ * (`() => import("./routes")`) that must be resolved before its routes can be
+ * matched. The hot path is unaffected: `await` only suspends on the first
+ * request to a not-yet-loaded dynamic include; eager routes resolve in the same
+ * microtask. Every caller already runs inside an async match pipeline.
  */
 export function createFindMatch<TEnv = any>(
   deps: FindMatchDeps<TEnv>,
-): (pathname: string, ms?: MetricsStore) => RouteMatchResult<TEnv> | null {
+): (
+  pathname: string,
+  ms?: MetricsStore,
+) => Promise<RouteMatchResult<TEnv> | null> {
   // Single-entry cache for findMatch to avoid redundant matching within the same request.
   // previewMatch and match both call findMatch with the same pathname — this ensures
   // the route matching work (which may check thousands of routes) only happens once.
   let lastFindMatchPathname: string | null = null;
   let lastFindMatchResult: RouteMatchResult<TEnv> | null = null;
 
-  // Wrapper for findMatch that uses routesEntries
-  // Handles lazy evaluation by evaluating lazy entries on first match.
-  // Phase 1: try O(path_length) trie match.
-  // Phase 2: fall back to regex iteration.
-  return function findMatch(
+  return async function findMatch(
     pathname: string,
     ms?: MetricsStore,
-  ): RouteMatchResult<TEnv> | null {
-    // Return cached result if same pathname (avoids double-match per request)
+  ): Promise<RouteMatchResult<TEnv> | null> {
     if (lastFindMatchPathname === pathname) {
-      return lastFindMatchResult;
+      return cloneMatchResult(lastFindMatchResult);
     }
 
-    // Helper to push sub-metrics
     const pushMetric = ms
       ? (label: string, start: number) => {
           ms.metrics.push({
@@ -51,17 +70,15 @@ export function createFindMatch<TEnv = any>(
         }
       : undefined;
 
-    // Phase 1: Try trie match (O(path_length))
-    // Only use the per-router trie. The global trie merges routes from ALL
-    // routers and must not be used — in multi-router setups (host routing)
-    // overlapping paths like "/" would match the wrong app's route.
     const routeTrie = getRouterTrie(deps.routerId);
+    let trieMatched = false;
     if (routeTrie) {
       const trieStart = performance.now();
       const trieResult = tryTrieMatch(routeTrie, pathname);
       pushMetric?.("match:trie", trieStart);
 
       if (trieResult) {
+        trieMatched = true;
         // Find the RouteEntry that contains this route.
         // Multiple entries can share the same staticPrefix (e.g., several
         // include("/", patterns) calls all produce staticPrefix=""). Evaluate
@@ -69,11 +86,33 @@ export function createFindMatch<TEnv = any>(
         const entryStart = performance.now();
         let entry: RouteEntry<TEnv> | undefined;
         let fallbackEntry: RouteEntry<TEnv> | undefined;
+        let candidateError: unknown;
+        let candidateFailed = false;
 
         for (const e of deps.routesEntries) {
           if (e.staticPrefix !== trieResult.sp) continue;
           if (!fallbackEntry) fallbackEntry = e;
-          deps.evaluateLazyEntry(e);
+          try {
+            const ev = deps.evaluateLazyEntry(e);
+            if (ev) await ev;
+          } catch (err) {
+            // Multiple async includes can share one collapsed static prefix, so
+            // this loop may evaluate a candidate that is NOT the route's owner.
+            // Remember the failure and keep scanning: if another candidate owns
+            // the route, this sibling's failure is correctly isolated (its
+            // _lazyInflight was cleared, so a later request retries). But if NO
+            // candidate ends up owning it, the failing one WAS the owner — a
+            // real, trie-matched route whose module failed to import — and we
+            // rethrow below as a 5xx rather than silently 404ing (see finding 3:
+            // owner failure must stay loud).
+            candidateError = err;
+            candidateFailed = true;
+            console.error(
+              `[@rangojs/router] include at "${e.staticPrefix}" failed to load: ` +
+                `${(err as Error)?.message ?? String(err)}`,
+            );
+            continue;
+          }
           if (
             e.routes &&
             trieResult.routeKey in (e.routes as Record<string, unknown>)
@@ -83,12 +122,16 @@ export function createFindMatch<TEnv = any>(
           }
         }
 
-        // If no entry had the route in its routes map, use the first matching
-        // entry as fallback (handles main entry with inline routes not yet
-        // reflected in its routes object).
+        // The trie matched this route, so it EXISTS. If no same-prefix candidate
+        // could own it AND one failed to load, the owning module is the one that
+        // threw — surface the module failure as a 5xx, not the misleading 404 a
+        // fallthrough would give.
+        if (!entry && candidateFailed) {
+          throw candidateError;
+        }
+
         if (!entry) entry = fallbackEntry;
 
-        // If entry not found (nested include not yet discovered), evaluate parent
         if (!entry) {
           const parent = deps.routesEntries.find(
             (e) =>
@@ -97,7 +140,8 @@ export function createFindMatch<TEnv = any>(
           );
           if (parent) {
             const lazyStart = performance.now();
-            deps.evaluateLazyEntry(parent);
+            const ev = deps.evaluateLazyEntry(parent);
+            if (ev) await ev;
             pushMetric?.("match:lazy-eval", lazyStart);
           }
           entry = deps.routesEntries.find(
@@ -112,9 +156,7 @@ export function createFindMatch<TEnv = any>(
             entry,
             routeKey: trieResult.routeKey,
             params: trieResult.params,
-            optionalParams: new Set(trieResult.optionalParams || []),
             redirectTo: trieResult.redirectTo,
-            ancestry: trieResult.ancestry,
             ...(trieResult.pr ? { pr: true } : {}),
             ...(trieResult.pt ? { pt: true } : {}),
             ...(trieResult.responseType
@@ -125,17 +167,25 @@ export function createFindMatch<TEnv = any>(
               : {}),
             ...(trieResult.rscFirst ? { rscFirst: true } : {}),
           };
-          return lastFindMatchResult;
+          return cloneMatchResult(lastFindMatchResult);
         }
+      } else if (isRouterTrieAuthoritative(deps.routerId)) {
+        // Authoritative miss (#664): this trie was deserialized from the
+        // COMPLETE build manifest, so trailing-slash redirects are already
+        // trie-native hits and a miss means no route exists. Skip the regex
+        // fallback — the only route-count-proportional match path — and do
+        // not evaluate lazy includes for unmatched (bot-probe) traffic.
+        // Trie hits that need lazy splicing keep the fallback loop below
+        // (trieMatched === true never reaches this branch).
+        lastFindMatchPathname = pathname;
+        lastFindMatchResult = null;
+        return null;
       }
     }
 
-    // Phase 2: Fall back to existing matching (regex iteration)
     const regexStart = performance.now();
     let result = findRouteMatch(pathname, deps.routesEntries);
 
-    // If we hit a lazy entry that needs evaluation, evaluate and retry.
-    // Cap iterations to prevent infinite loops from pathological nesting.
     const MAX_LAZY_ITERATIONS = 100;
     let iterations = 0;
     while (isLazyEvaluationNeeded(result)) {
@@ -148,13 +198,62 @@ export function createFindMatch<TEnv = any>(
         lastFindMatchResult = null;
         return null;
       }
-      deps.evaluateLazyEntry(result.lazyEntry);
+      try {
+        const ev = deps.evaluateLazyEntry(result.lazyEntry);
+        if (ev) await ev;
+      } catch (err) {
+        // If the trie matched this pathname, the route is REAL and this lazy
+        // entry owns (part of) it — a module-load failure is a genuine error, so
+        // propagate it as a 5xx. If the trie did NOT match, this is a
+        // genuinely-unmatched pathname (a typo, a bot probe): its 404 must not be
+        // upgraded to a 500 just because some lazy include — e.g. a failing root
+        // `include("/")` — happened to need evaluating while we probed. Isolate
+        // and fall through to the 404 (finding 4: the two match phases agree —
+        // owner failure is loud, unmatched stays 404).
+        if (trieMatched) throw err;
+        console.error(
+          `[@rangojs/router] include at "${result.lazyEntry.staticPrefix}" ` +
+            `failed to load while resolving unmatched path "${pathname}": ` +
+            `${(err as Error)?.message ?? String(err)}`,
+        );
+        lastFindMatchPathname = pathname;
+        lastFindMatchResult = null;
+        return null;
+      }
       result = findRouteMatch(pathname, deps.routesEntries);
     }
     pushMetric?.("match:regex-fallback", regexStart);
 
+    // The trie is the single source of truth and is built before findMatch in
+    // both dev (handler rebuild) and production (ensureRouterManifest). If the
+    // trie was present yet the regex fallback resolved a real match, the trie
+    // has a gap (e.g. a route shape it cannot represent) and dev/prod could
+    // diverge if the trie were ever absent. Surface it in dev; folded out in
+    // production builds.
+    //
+    // Suppress when the trie DID match (`trieMatched`): that path falls through
+    // to the regex fallback only on the first request to a not-yet-spliced lazy
+    // entry (e.g. a 2+-level nested include whose deeper parent has not been
+    // evaluated). The trie knew the route; runtime lazy discovery simply lagged.
+    // That is the supported lazy-include flow, not a trie gap, so warning on it
+    // is a false positive (it manufactures bug reports and erodes the signal).
+    if (
+      process.env.NODE_ENV !== "production" &&
+      routeTrie &&
+      !trieMatched &&
+      result &&
+      !isLazyEvaluationNeeded(result)
+    ) {
+      console.warn(
+        `[@rangojs/router] Route "${pathname}" resolved via the regex fallback ` +
+          `even though the route trie was present. The trie should be the single ` +
+          `matching source of truth; this indicates a trie gap. Please report this ` +
+          `with your route configuration.`,
+      );
+    }
+
     lastFindMatchPathname = pathname;
     lastFindMatchResult = result;
-    return result;
+    return cloneMatchResult(result);
   };
 }

package/src/router/handler-context.ts

@@ -21,6 +21,11 @@ import { PRERENDER_PASSTHROUGH } from "../prerender.js";
 import { substitutePatternParams } from "./substitute-pattern-params.js";
 import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 
+// Mutating Headers methods guarded so they throw inside "use cache" / cache()
+// scope. Module-level constant (read-only, .has() lookups) so it is allocated
+// once at module load instead of per createHandlerContext (per-request) call.
+const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
+
 /**
  * Strip internal _rsc* query params from a URL.
  * Returns a new URL with only user-facing params.
@@ -212,7 +217,7 @@ export function createHandlerContext<TEnv>(
   // Guard mutating Headers methods so they throw inside "use cache" or cache() scope.
   // Uses lazy `ctx` reference (assigned below) — only the specific handler ctx
   // is stamped by cache-runtime, not the shared request context.
-  const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
+  // MUTATING_HEADERS_METHODS is hoisted to module scope (constant, read-only).
   let ctx: InternalHandlerContext<any, TEnv>;
   const guardedHeaders = new Proxy(stubResponse.headers, {
     get(target, prop, receiver) {

package/src/router/instrument.ts

@@ -0,0 +1,355 @@
+/**
+ * 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,
+} from "./tracing.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>;
+  /**
+   * Span attributes resolved AFTER the wrapped work runs (so they can read state
+   * that only exists once the work is underway, e.g. the matched route name).
+   * Applied for streaming phases once fn has constructed its value. Return
+   * undefined to add nothing.
+   */
+  lazyAttributes?: () => Record<string, string | number | boolean> | undefined;
+}
+
+/**
+ * The matched route name for the current request, or undefined when there is no
+ * named route (unmatched / auto-generated). Shared by the render phase's metric
+ * label and its rango.route span attribute so the two can't disagree.
+ */
+function currentRouteName(): string | undefined {
+  const routeName = _getRequestContext()?._routeName;
+  return routeName && !isAutoGeneratedRouteName(routeName)
+    ? routeName
+    : undefined;
+}
+
+/**
+ * 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 },
+  }),
+
+  /** One segment route/layout handler execution (the component/handler that
+   * produces a segment). Span only — the perf metric (handler:<id>) is owned by
+   * the legacy track() at the same call site, so observePhase here adds the
+   * rango.handler span without double-recording. `id` is the HANDLER id (the
+   * entry.id used in the handler:<id> perf row), carried as rango.handler_id —
+   * NOT the emitted segment's id (shortCode), which differs; the *_id naming
+   * mirrors rango.loader_id / rango.action_id. */
+  handler: (id: string): PhaseSpec => ({
+    metric: false,
+    tracePhase: "handler",
+    spanName: "rango.handler",
+    attributes: { "rango.handler_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 = currentRouteName();
+        return routeName ? `render:total:${routeName}` : "render:total";
+      },
+    },
+    tracePhase: "render",
+    spanName: "rango.render",
+    // Tag the render span with the matched route so the Cloudflare/OTel waterfall
+    // shows WHICH route rendered (rango.render + rango.route=index), resolved
+    // after match has run. Kept an attribute (not baked into the span name) so the
+    // span name stays low-cardinality and aggregatable across routes.
+    lazyAttributes: () => {
+      const routeName = currentRouteName();
+      return routeName ? { "rango.route": routeName } : undefined;
+    },
+  } 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 ONLY phase primitive: every phase (request/middleware/action/
+ * loader/handler/render/ssr) is construction-bound — the span and metric settle
+ * when fn's own work completes (for the streaming phases, when the RSC/HTML
+ * stream is constructed, NOT when the body drains). Instrumentation is strictly
+ * best-effort: it never wraps or buffers the response and adds no work on the
+ * streaming path, so it cannot regress response latency or streaming. A loader
+ * that resolves while the body streams therefore keeps a rango.loader span that
+ * may extend past its render parent — overlapping spans are valid; the loader
+ * really did take that long.
+ *
+ * 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. Build the attribute/lazy wrapper only
+  // when this phase's span is actually enabled (not toggled off via `spans`), and
+  // short-circuit inside when the runner hands back the no-op span (tracing
+  // configured but off at runtime — e.g. no executionContext.tracing). That keeps
+  // the "configured but effectively off" path free of per-call attribute loops
+  // and lazy `.then()` allocations. `lazyAttributes` resolve AFTER fn runs (e.g.
+  // rango.route, known post-match) and apply on BOTH success and failure so an
+  // errored phase span is still tagged.
+  const attributes = spec.attributes;
+  const lazy = spec.lazyAttributes;
+  const spanEnabled =
+    tracing !== undefined && tracing.phases[spec.tracePhase] !== false;
+  const wrapped: (span: TraceSpan) => T =
+    (attributes || lazy) && spanEnabled
+      ? (span) => {
+          if (span === NOOP_TRACE_SPAN) return fn(span);
+          if (attributes) applyAttributes(span, attributes);
+          // A SYNCHRONOUS throw from fn skips applyLate — fine by design: the only
+          // lazyAttributes phase (render) is always async, so any internal throw
+          // surfaces as a rejection that the onReject branch below DOES tag. If a
+          // sync lazyAttributes phase is ever added, wrap this in try/catch.
+          const out = fn(span);
+          if (!lazy) return out;
+          const applyLate = () => {
+            const late = lazy();
+            if (late) applyAttributes(span, late);
+          };
+          if (out instanceof Promise) {
+            return out.then(
+              (value) => {
+                applyLate();
+                return value;
+              },
+              (error) => {
+                applyLate();
+                throw error;
+              },
+            ) as T;
+          }
+          applyLate();
+          return out;
+        }
+      : 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));
+}
+
+/**
+ * Open a rango.handler span around one segment route/layout handler call. The
+ * segment-resolution hot path runs this PER SEGMENT, so it gates on the SPAN
+ * surface alone and calls the handler directly otherwise — building neither the
+ * PhaseSpec (PHASES.handler allocates) nor the wrapper closure on the off path.
+ * The handler:<id> perf metric is owned by the track() at the call site, so the
+ * span is the only surface this adds (metric:false); a debugPerformance-only
+ * request (no tracing) or a disabled handler phase (spans:{handler:false}) has
+ * nothing to record here and short-circuits.
+ */
+export function observeHandler<C, R>(
+  id: string,
+  handler: (ctx: C) => R,
+  ctx: C,
+): R {
+  const tracing = _getRequestContext()?._tracing;
+  if (!tracing || tracing.phases.handler === false) return handler(ctx);
+  return observePhase(PHASES.handler(id), () => handler(ctx));
+}
+
+/**
+ * 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 (revalidation decisions, cache-lookup 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.
+ *   - rsc/handler.ts handleTimeoutResponse (request.timeout), the origin guard
+ *     (request.origin-rejected), and handleStore.onError (late-handle
+ *     handler.error) emit via router.telemetry directly — they run outside the
+ *     RouterContext ALS (only match()/matchPartial() enter it), so a
+ *     getRouterContext() read there throws and the event would vanish.
+ */
+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);
+}