@rangojs/router 0.0.0-experimental.142 → 0.0.0-experimental.143

package/dist/vite/index.js

@@ -2393,7 +2393,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.142",
+  version: "0.0.0-experimental.143",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2583,6 +2583,8 @@ var package_default = {
   },
   devDependencies: {
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^2.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@playwright/test": "^1.49.1",
     "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.142",
+  "version": "0.0.0-experimental.143",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -190,6 +190,8 @@
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^2.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@playwright/test": "^1.49.1",
     "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",

package/skills/caching/SKILL.md

@@ -91,6 +91,24 @@ cache(
 );
 ```
 
+## When cache() does not pay
+
+A cache hit is not free: it still runs middleware, the store read, and the
+document render AROUND the cached segment. The win is proportional to what
+the cached render itself costs — measured on a deployed Cloudflare worker
+(2026-07), a trivial page inside `cache()` served hits at p50 36 ms while
+misses (render + store) served at 35 ms: indistinguishable. The same
+boundary around an expensive render (slow data, big trees) is where the TTL
+pays for itself.
+
+Rule of thumb: reach for `cache()` when the segment's own render cost is
+meaningfully above your latency floor — expensive render-embedded data work,
+large component trees, third-party calls captured in the render. Do not wrap cheap
+pages "just in case": you add store traffic and invalidation surface for no
+latency win. If the data is what's expensive and it changes per-request,
+prefer a loader with `cache()` on the loader DATA (see "Loader-Level
+Caching") over caching the rendered segment.
+
 ## Tag-Based Invalidation
 
 Tag cached entries, then invalidate them on demand. Tags can be attached three ways:

package/skills/composability/SKILL.md

@@ -210,6 +210,38 @@ in the group — including nested `include()`s inside the split module. Only the
 module's runtime evaluation defers. `rango generate` resolves the `() => import()`
 the same way, so a code-split group is still fully typed.
 
+### Sizing async include groups (measured)
+
+The first request into an async group pays that group's chunk import; every
+request after that is flat. Measured on a deployed Cloudflare worker with
+26k routes (2026-07, warm RTT floor ~23 ms):
+
+| Group size                 | First-hit latency                    |
+| -------------------------- | ------------------------------------ |
+| ~240 routes                | ~75 ms (≈ RTT + eval)                |
+| ~5,000 routes              | ~137 ms                              |
+| ~9,000 routes              | ~188 ms                              |
+| 3-level nested async chain | ~464 ms (levels import sequentially) |
+
+Three rules fall out of those numbers:
+
+1. **Prefer more, smaller groups over few giant ones.** First-hit cost scales
+   with routes-per-chunk; fifty 250-route groups each cost a fraction of one
+   9k-route group, and only the group actually visited pays anything.
+2. **Keep async-include chains shallow on latency-sensitive paths.** Each
+   nested `() => import()` level awaits in sequence, so depth multiplies the
+   first hit. Nesting eager includes inside one async module costs one chunk;
+   nesting async inside async costs one chunk per level.
+3. **Give sibling groups distinct static prefixes.** Siblings that share a
+   static prefix (`include("/x/:a", …)` next to `include("/x/:b", …)`) all
+   import on the first hit to that prefix — the router cannot tell which one
+   matches before loading them.
+
+Warm-path matching is O(path segments) via the precomputed trie regardless of
+group layout — this sizing only shapes cold/first-hit behavior. For
+latency-critical prefixes, a post-deploy warmup ping (one request per prefix)
+erases first-hit cost for the isolate entirely.
+
 ## Composition Types
 
 For typed factories, import the composition types:

package/skills/observability/SKILL.md

@@ -58,6 +58,14 @@ Read the timeline as intervals:
 - Cache, route matching, middleware pre/post, RSC serialization, and SSR phases
   appear as separate spans, so the slow phase is visible without guessing.
 
+**Deployed Cloudflare caveat**: on production Workers, timers are frozen
+during request execution (Spectre mitigation), so `Server-Timing` durations
+read as ~0 on the deployed edge — they only advance across genuine awaited
+I/O. The waterfall is a LOCAL diagnostic (dev, `vite preview`,
+`wrangler dev`); for deployed workers, measure from the client
+(`PerformanceResourceTiming`, TTFB) and use structured telemetry below for
+server-side events.
+
 ## Structured telemetry
 
 Use telemetry when you want durable production events rather than a one-request

package/skills/parallel/SKILL.md

@@ -271,6 +271,8 @@ parallel(
 
 Per-slot merge order is **handler.use → shared use → slot-local use**. Slot-local is the narrowest scope, so it wins for last-write-wins items. See [skills/handler-use § `loading()` is a single-assignment item — scope it correctly](../handler-use/SKILL.md#loading-is-a-single-assignment-item--scope-it-correctly) for the full reasoning.
 
+Typing note: a BARE arrow slot handler infers its ctx (`"@cart": (ctx) => ...`), but an arrow inside a DESCRIPTOR needs an explicit annotation — `handler: (ctx: HandlerContext) => ...` — because `StaticHandlerDefinition` in the slot union contributes a second callable to the contextual type and TS declines to pick a signature.
+
 ## Slot Override Semantics
 
 When multiple `parallel()` calls define the same slot name, **the last

package/skills/ppr/SKILL.md

@@ -169,6 +169,31 @@ On a document GET to a ppr route the router runs:
 point is after the chain, an unauthorized request NEVER sees shell bytes — put
 auth middleware anywhere (global or route DSL) and it guards PPR for free.
 
+## Verifying it works
+
+The header exists on DOCUMENT responses only. A bare `curl` (no `Accept`)
+content-negotiates a Flight payload (`text/x-component`) with NO
+`x-rango-shell` header at all — which reads as "PPR is off" but is only the
+wrong request shape:
+
+```
+curl -s -D - -o /dev/null -H "Accept: text/html" https://app.example.com/products/1 | grep -i x-rango-shell
+```
+
+- First document GET: `MISS`, plus a background capture.
+- Production (workerd/node): the SECOND request is a `HIT`.
+- Dev: expect a few extra MISSes — cold module transforms abort the capture
+  window (per-attempt breadcrumbs: start the server with
+  `INTERNAL_RANGO_DEBUG=1`). This self-heals; only a route that NEVER flips
+  has a real hole/eligibility problem (the once-per-key warning tells the two
+  apart).
+- A HIT is one ordinary document: the frozen prelude first (view-source shows
+  your baked shell, with hole fallbacks in place), then
+  `<div hidden id="S:0">…` segments as the holes resume, per request.
+- A ppr-declared route that CANNOT be honored (missing shell store family,
+  per-request nonce) serves plain axis 1 with NO header and warns once per
+  key — no header + a declared `ppr` means look for that warning.
+
 ## The hole doctrine (encode this in your head)
 
 Holes are **render-defined**, decided by the shape of the tree, on three rules:
@@ -230,7 +255,14 @@ The physics caveat in one line: promise holes are holes because the I/O is
 genuinely pending at capture. If the value can resolve near-instantly (memory
 read, warmed cache), it may bake into the shell — when liveness must be
 guaranteed rather than probable, use the live lane (`loading()`). The same
-physics governs bake-lane nested promises.
+physics governs bake-lane nested promises, with one shape guarantee: a nested
+promise that settles inside the window pins its VALUE, but the container key
+KEEPS its promise shape on HITs (the snapshot rehydrates a
+`Promise.resolve(pinned)`), so an unconditional `use(data.x)` consumer never
+breaks — it just reads the pinned value. Note the timing consequence: whether
+such a value is pinned or live can vary per capture (concurrent loader traffic
+extends the quiet window), so treat "fast-resolving promise on the bake lane"
+as PINNED for correctness purposes.
 
 ### Handles: "nesting = liveness"
 
@@ -278,7 +310,10 @@ Three hard edges (each e2e/unit-pinned):
   throws during capture and the capture REFUSES (deterministic, once-per-key
   warned) — identity can never bake into the shared shell. Give that loader's
   entry `loading()` (the live lane is exempt) or move the identity-dependent
-  part into a nested promise.
+  part into a nested promise. The guard's scope is EXACTLY those two calls:
+  per-user state read from a middleware-provided object (`ctx.get("session")`)
+  does NOT refuse — it bakes silently as the capturing user's data (see
+  Pitfalls: the session-object bake trap).
 - **A rejecting bake-lane loader refuses.** Error UI never bakes.
 - **Baked containers show CAPTURE-time data** for the shell's lifetime on
   document GETs (client navigations stay fresh — axis 1). That IS the bake
@@ -316,10 +351,16 @@ stay live. Your levers, in order of preference:
        loader(BasketLoader),
        loading(<BadgeSkeleton />), // hole the size of a badge, not a page
      ]),
-     parallel({ "@wishlist": WishlistBadge }, () => [
-       loader(WishlistLoader),
-       loading(<BadgeSkeleton />),
-     ]),
+     // Descriptor form when the slot handler needs ctx (annotate it —
+     // StaticHandlerDefinition in the union blocks inference there):
+     parallel({
+       "@wishlist": {
+         handler: (ctx: HandlerContext) => (
+           <WishlistBadge listUrl={ctx.reverse("wishlist")} />
+         ),
+         use: () => [loader(WishlistLoader), loading(<BadgeSkeleton />)],
+       },
+     }),
      path("/", HomePage, { name: "home", ppr: true }),
    ]),
    ```
@@ -387,9 +428,14 @@ PPR-ineligible by construction; the live lane (`loading()`) stays exempt.
 **(c) Residual hazard — middleware-derived per-user state.** A `ctx` variable
 set by an upstream auth middleware and rendered by shell material is
 photographed into the SHARED shell (the capture inherits post-middleware
-state). That is scope fidelity working as designed — for shared values. If the
-value is per-user: shell-cache only public/shared pages, put per-user content
-in loaders, or key per variant at the CDN tier.
+state). That is scope fidelity working as designed — for shared values. The
+same hazard reaches BAKE-LANE LOADERS: a loader reading a middleware-provided
+session object (`ctx.get("session")`) never calls `cookies()` itself, so the
+guard cannot see it — whatever it returns as settled container data is
+photographed as the CAPTURING user's state. If the
+value is per-user: shell-cache only public/shared pages, keep per-user content
+in nested pending promises or live-lane (`loading()`) loaders — NOT in a
+bake-lane container — or key per variant at the CDN tier.
 
 ## What always stays on axis 1
 
@@ -483,7 +529,27 @@ know (a tenant id, a deploy marker).
 - **Per-user value in shell material**: baked into the shared shell —
   deterministically, not by race (handler promises deep-settle at the ring-3
   write on cached chains; awaited/resolved values bake everywhere). Put
-  per-user data in a loader.
+  per-user data in a nested pending promise or a live-lane (`loading()`)
+  loader — a BAKE-lane loader container bakes just like handler material.
+- **The session-object bake trap (the guard cannot save you here)**: the
+  capture guard sees `cookies()`/`headers()` calls ONLY. A bake-lane loader
+  reading a middleware-provided session object (`ctx.get("session")`) refuses
+  nothing — and its FAST-RESOLVE branch is the killer:
+
+  ```typescript
+  const CartLoader = createLoader(async (ctx) => {
+    const basketId = ctx.get("session")!.get("basketId");
+    if (!basketId) return { cart: Promise.resolve(null) }; // SETTLED → BAKES
+    return { cart: fetchBasket(basketId) }; // pending → hole
+  });
+  ```
+
+  If the capturing request is anonymous (it usually is), `cart: null` bakes
+  and is snapshot-pinned: every logged-in user gets the anonymous badge on
+  every HIT. The branch asymmetry makes it nondeterministic per capture. Any
+  loader whose data is per-user belongs on the live lane — for a header
+  widget, a parallel slot with its own `loading()` (playbook lever 3).
+
 - **Theme on a HIT is capture-then-corrected**: the resume tree replays the
   CAPTURE's `initialTheme` (resume requires it to match the frozen prelude);
   the visitor's cookie theme is applied pre-paint by the FOUC script and

package/skills/route/SKILL.md

@@ -479,6 +479,14 @@ urls(({ path, layout }) => [
 ])
 ```
 
+For composing whole route MODULES, reach for `include()` — and prefer the
+code-split form `include("/shop", () => import("./shop-patterns"))` for any
+group that is a natural unit: it keeps the group off the cold-start path, and
+measured first-hit cost scales with routes-per-chunk, so many small groups
+beat one giant one. Sizing rules and the numbers behind them:
+[skills/composability](../composability/SKILL.md) → "Sizing async include
+groups (measured)".
+
 ## View Transitions
 
 A route can configure its own `transition()` — the wrap goes around the route's component itself (routes are leaves; they have no separate default outlet channel). If the route component renders a `<ParallelOutlet />` directly, that slot remains inside the route's VT subtree, so prefer mounting parallel slots in a layout when combining intercept modals with route-level transitions. See [skills/view-transitions](../view-transitions/SKILL.md) for examples and the wrap-location rules across layouts, routes, and slots.

package/skills/typesafety/SKILL.md

@@ -25,6 +25,7 @@ below. Read the one for your case.
 | Typed `search` schemas, `RouteSearchParams`/`RouteParams`, loader return types                                       | Search params & loader typing          | [`./params-and-search.md`](./params-and-search.md)             |
 | Typed `env`/bindings, `Rango.Vars`, `createVar()`, handle typing, loader/handle ref props, location state typing     | Environment, context, and state typing | [`./env-and-bindings.md`](./env-and-bindings.md)               |
 | Multi-app / multi-router tsconfig setup, avoiding `GeneratedRouteMap` collisions                                     | Multi-project setup & full walkthrough | [`./generated-files-and-cli.md`](./generated-files-and-cli.md) |
+| Slow typecheck with many `include()` modules (instantiation blowup), wide `UrlPatterns<any>` annotations             | Typecheck cost at route scale          | [`./generated-files-and-cli.md`](./generated-files-and-cli.md) |
 
 ## Companion files
 

package/skills/typesafety/generated-files-and-cli.md

@@ -120,6 +120,36 @@ Do not document or use a public `router.routeNames` API unless one is
 intentionally added. Today, the public extraction surface is `router.routeMap`;
 the generated file and `$$routeNames` are build machinery.
 
+### Typecheck cost when composing many include modules
+
+`urls()` infers a route registry from everything in its array — including the
+module types behind every `include()` thunk, recursively. In an app composing
+MANY include modules (dozens of groups, or factory-produced groups), that
+inference chain can explode: measured on a 26k-route app with 50 nested
+include modules, root inference hit 4.05M type instantiations / 20 s check
+time; the same app checks at ~140k / 3.6 s after widening.
+
+The fix is to annotate the intermediate modules' exports with the wide
+`UrlPatterns` type, which stops per-route literal types from propagating
+upward:
+
+```typescript
+import { urls, type UrlPatterns } from "@rangojs/router";
+
+export const shopPatterns: UrlPatterns<any> = urls(({ path }) => [
+  // ...hundreds of routes
+]);
+export default shopPatterns;
+```
+
+Nothing is lost: named-route typing (`Handler<"name">`, `ctx.reverse`,
+`href`) comes from the generated `router.named-routes.gen.ts`, not from the
+inferred `urls()` type. Keep full inference on modules whose
+`Rango.PathResponse` payloads you assert (e.g. `path.json` response routes);
+widen the big mechanical groups. Use `UrlPatterns<any>` (not
+`UrlPatterns<unknown>` — `unknown` env breaks handler assignability).
+Diagnose with `tsc --extendedDiagnostics` and watch the Instantiations count.
+
 ## Multi-Project tsconfig Setup
 
 For monorepos or multi-app setups, each app should have its own TypeScript

package/src/cloudflare/tracing.ts

@@ -39,7 +39,7 @@ import { _getRequestContext } from "../server/request-context.js";
 import {
   type RouterTracingConfig,
   type SpanRunner,
-  type TracePhaseToggles,
+  type TracingToggleOptions,
   NOOP_TRACE_SPAN,
 } from "../router/tracing.js";
 
@@ -57,13 +57,12 @@ interface CloudflareTracing {
   enterSpan<T>(name: string, callback: (span: CloudflareSpan) => T): T;
 }
 
-/** Options for createCloudflareTracing. */
-export interface CloudflareTracingOptions {
-  /** Master switch. Defaults to true. */
-  enabled?: boolean;
-  /** Per-phase span toggles. Omitted phases default to enabled. */
-  spans?: TracePhaseToggles;
-}
+/**
+ * Options for createCloudflareTracing. Alias of the shared
+ * {@link TracingToggleOptions} (`enabled` master switch + per-phase `spans`
+ * toggles); the name is public API.
+ */
+export type CloudflareTracingOptions = TracingToggleOptions;
 
 /**
  * Resolve the per-request Cloudflare tracer from the active execution context.

package/src/index.rsc.ts

@@ -308,6 +308,7 @@ export type {
   RouterTracingConfig,
   TracePhase,
   TracePhaseToggles,
+  TracingToggleOptions,
 } from "./router/tracing.js";
 
 // Timeout types and error class

package/src/index.ts

@@ -343,14 +343,17 @@ export {
 // Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
 // `Rango.PathResponse`, declared in href-client.ts) — no import needed.
 
-// Telemetry types only — the createConsoleSink/createOTelSink values are
-// server-only and live in index.rsc.ts (the `react-server` condition of the
-// bare `@rangojs/router` import). Re-exporting them as values from this
-// (default/client) entry would pull telemetry.ts and telemetry-otel.ts into
-// the client module graph; both tree-shake to zero bytes but still appear in
-// bundle analysis output and slow build-time module resolution. Consumers
-// who need the values in non-RSC contexts can import from
-// `@rangojs/router/server`.
+// Telemetry types only — the createConsoleSink / createOTelSink /
+// createOTelTracing VALUES are server-only and live in index.rsc.ts (the
+// `react-server` condition of the bare `@rangojs/router` import). Re-exporting
+// them as values from this (default/client) entry would pull telemetry.ts and
+// telemetry-otel.ts into the client module graph; both tree-shake to zero bytes
+// but still appear in bundle analysis output and slow build-time module
+// resolution. The factory values are NOT re-exported from `@rangojs/router/server`
+// either — that subpath is internal, not user-facing (see server.ts header).
+// Non-RSC server code imports these TYPES from the root and obtains the factory
+// VALUES from its own router definition module, which resolves to index.rsc.ts
+// under the `react-server` condition.
 export type {
   OTelTracer,
   OTelActiveSpanTracer,
@@ -386,6 +389,7 @@ export type {
   RouterTracingConfig,
   TracePhase,
   TracePhaseToggles,
+  TracingToggleOptions,
 } from "./router/tracing.js";
 
 // Timeout types and error class

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

@@ -149,8 +149,11 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *              so they take precedence on `loading()` and other last-write-wins
    *              fields.
    */
-  parallel: <
-    TSlots extends Record<
+  // Not generic over the slots record: an inferred type parameter makes the
+  // object literal an inference site, which suppresses contextual typing of
+  // arrow slot handlers (`(ctx) => ...` was implicit any).
+  parallel: (
+    slots: Record<
       `@${string}`,
       | Handler<any, any, TEnv>
       | ReactNode
@@ -159,8 +162,6 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
           use?: () => UseItems<ParallelUseItem>;
         }
     >,
-  >(
-    slots: TSlots,
     use?: () => UseItems<ParallelUseItem>,
   ) => ParallelItem;
   /**

package/src/route-map-builder.ts

@@ -139,6 +139,7 @@ export function clearAllRouterData(): void {
   perRouterManifestMap.clear();
   perRouterTrieMap.clear();
   perRouterPrecomputedEntriesMap.clear();
+  authoritativeTrieRouters.clear();
 }
 
 export function setRouterManifest(
@@ -162,6 +163,23 @@ export function setRouterTrie(
   perRouterTrieMap.set(routerId, trie);
 }
 
+// Routers whose trie came from the COMPLETE build manifest (deserialized via
+// ensureRouterManifest). For these, a trie miss is a real 404 and findMatch
+// skips the regex fallback scan — the only remaining route-count-proportional
+// match path (#664). Dev rebuilds (manifest-init.ts, router-discovery HMR
+// pushes) deliberately never mark authoritative: the dev-only trie-gap warning
+// in find-match.ts depends on the fallback running on misses, and dev route
+// churn (HMR, dev-time routes) makes a stale-trie 404 unacceptable there.
+const authoritativeTrieRouters: Set<string> = new Set();
+
+export function markRouterTrieAuthoritative(routerId: string): void {
+  authoritativeTrieRouters.add(routerId);
+}
+
+export function isRouterTrieAuthoritative(routerId: string): boolean {
+  return authoritativeTrieRouters.has(routerId);
+}
+
 export function getRouterTrie(
   routerId: string,
 ): import("./build/route-trie.js").TrieNode | undefined {
@@ -204,7 +222,12 @@ export async function ensureRouterManifest(routerId: string): Promise<void> {
   if (loader) {
     const mod = await loader();
     if (mod.manifest) perRouterManifestMap.set(routerId, mod.manifest);
-    if (mod.trie) perRouterTrieMap.set(routerId, mod.trie);
+    if (mod.trie) {
+      perRouterTrieMap.set(routerId, mod.trie);
+      // A trie serialized into the build manifest comes from complete
+      // discovery — misses are authoritative 404s (see find-match.ts).
+      markRouterTrieAuthoritative(routerId);
+    }
     if (mod.precomputedEntries)
       perRouterPrecomputedEntriesMap.set(routerId, mod.precomputedEntries);
     routerManifestLoaders.delete(routerId);

package/src/router/find-match.ts

@@ -1,5 +1,8 @@
 import { tryTrieMatch } from "./trie-matching.js";
-import { getRouterTrie } from "../route-map-builder.js";
+import {
+  getRouterTrie,
+  isRouterTrieAuthoritative,
+} from "../route-map-builder.js";
 import {
   findMatch as findRouteMatch,
   isLazyEvaluationNeeded,
@@ -166,6 +169,17 @@ export function createFindMatch<TEnv = any>(
           };
           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;
       }
     }
 

package/src/router/instrument.ts

@@ -318,10 +318,10 @@ export function observeHandler<C, R>(
  * 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:
+ * 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
@@ -330,6 +330,11 @@ export function observeHandler<C, R>(
  *     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.