@rangojs/router 0.27.0 → 0.29.0

package/src/browser/segment-reconciler.ts

@@ -46,6 +46,60 @@ export interface ReconcileResult {
   interceptSegments: ResolvedSegment[];
 }
 
+/**
+ * A segment the server sent over its cached copy, keeping the cached
+ * structural properties so the React tree keeps its shape. Changing them
+ * between renders alters the element nesting (with/without
+ * RouteContentWrapper, MountContextProvider, etc.), which remounts components
+ * and destroys useActionState.
+ */
+function mergeCached(
+  fromServer: ResolvedSegment,
+  fromCache: ResolvedSegment,
+  actor: ReconcileActor,
+): ResolvedSegment {
+  let merged = fromServer;
+
+  // When server returns component: null for a layout segment, it means
+  // "this segment doesn't need re-rendering" - preserve the cached component
+  // to maintain the outlet chain and prevent React tree changes
+  if (
+    fromServer.component === null &&
+    fromServer.type === "layout" &&
+    fromCache.component != null
+  ) {
+    merged = { ...merged, component: fromCache.component };
+  }
+
+  // Loading preservation is actor-aware:
+  // - action/stale-revalidation: always preserve cached value to prevent
+  //   tree remount (even when cached is undefined, to avoid adding a
+  //   Suspense boundary that wasn't there before)
+  // - navigation: only when cached is defined (building a new tree)
+  if (
+    fromServer.loading !== fromCache.loading &&
+    (actor !== "navigation" || fromCache.loading !== undefined)
+  ) {
+    merged = { ...merged, loading: fromCache.loading };
+  }
+
+  // mountPath: SSR segments may lack mountPath while revalidated segments
+  // include it. The conditional MountContextProvider wrapper changes tree depth.
+  if (fromServer.mountPath !== fromCache.mountPath) {
+    merged = { ...merged, mountPath: fromCache.mountPath };
+  }
+
+  // Dev-mode assertion: warn if the merged result still differs from cache
+  // in tree-structural properties. This catches bugs where the merge code
+  // above fails to preserve a value it should have.
+  assertSegmentStructure(
+    fromCache,
+    merged,
+    actor === "action" ? "action-bridge" : "partial-update",
+  );
+  return merged;
+}
+
 /**
  * Single source of truth for merging server segments with cached segments.
  *
@@ -70,7 +124,6 @@ export interface ReconcileResult {
  */
 export function reconcileSegments(input: ReconcileInput): ReconcileResult {
   const { actor, matched, diff, insertMissingDiff } = input;
-  const context = actor === "action" ? "action-bridge" : "partial-update";
 
   // Build lookup maps from arrays
   const serverSegments = new Map<string, ResolvedSegment>();
@@ -111,59 +164,13 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
 
       if (fromServer) {
         const inDiff = diffSet.has(segId);
-        // Preserve cached structural properties to maintain consistent React tree.
-        // Changing these between renders alters the element nesting
-        // (with/without RouteContentWrapper, MountContextProvider, etc.),
-        // causing React to remount components and destroy useActionState.
         if (fromCache) {
-          let merged = fromServer;
-
-          // When server returns component: null for a layout segment, it means
-          // "this segment doesn't need re-rendering" - preserve the cached component
-          // to maintain the outlet chain and prevent React tree changes
-          if (
-            fromServer.component === null &&
-            fromServer.type === "layout" &&
-            fromCache.component != null
-          ) {
-            merged = { ...merged, component: fromCache.component };
-          }
-
-          // Loading preservation is actor-aware:
-          // - action/stale-revalidation: always preserve cached value to prevent
-          //   tree remount (even when cached is undefined, to avoid adding a
-          //   Suspense boundary that wasn't there before)
-          // - navigation: only when cached is defined (building a new tree)
-          if (actor !== "navigation") {
-            if (fromServer.loading !== fromCache.loading) {
-              merged = { ...merged, loading: fromCache.loading };
-            }
-          } else {
-            if (
-              fromCache.loading !== undefined &&
-              fromServer.loading !== fromCache.loading
-            ) {
-              merged = { ...merged, loading: fromCache.loading };
-            }
-          }
-
-          // mountPath: SSR segments may lack mountPath while revalidated segments
-          // include it. The conditional MountContextProvider wrapper changes tree depth.
-          if (fromServer.mountPath !== fromCache.mountPath) {
-            merged = { ...merged, mountPath: fromCache.mountPath };
-          }
-
-          // Dev-mode assertion: warn if the merged result still differs from cache
-          // in tree-structural properties. This catches bugs where the merge code
-          // above fails to preserve a value it should have.
-          assertSegmentStructure(fromCache, merged, context);
-
           if (IS_BROWSER_DEBUG) {
             debugLog(
               `[reconcile] ${segId}: SERVER+CACHE merge (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, component=${fromServer.component === null ? "null→cached" : "server"})`,
             );
           }
-          return merged;
+          return mergeCached(fromServer, fromCache, actor);
         }
         if (IS_BROWSER_DEBUG) {
           debugLog(
@@ -221,11 +228,13 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
 }
 
 /**
- * Reconcile error segments with cached segments.
+ * Reconcile an error-boundary response with cached segments.
  *
- * For error responses, the server returns the error boundary segment.
- * This function overlays error segments onto the full cached tree,
- * preserving sibling layouts that aren't in the error parent chain.
+ * The server returns the error boundary segment and, above it, what the
+ * action's revalidation re-ran (rsc/server-action.ts). This function overlays
+ * them onto the full cached tree, preserving sibling layouts that aren't in
+ * the error parent chain. The error segment replaces its cached copy; every
+ * other segment merges as an action's does (mergeCached).
  */
 export function reconcileErrorSegments(
   cachedSegments: ResolvedSegment[],
@@ -236,7 +245,11 @@ export function reconcileErrorSegments(
 
   const segments = cachedSegments.map((cached) => {
     const fromServer = errorMap.get(cached.id);
-    return fromServer || cached;
+    return !fromServer
+      ? cached
+      : fromServer.type === "error"
+        ? fromServer
+        : mergeCached(fromServer, cached, "action");
   });
 
   const { main, intercept } = splitInterceptSegments(segments);
@@ -247,3 +260,46 @@ export function reconcileErrorSegments(
     interceptSegments: intercept,
   };
 }
+
+/**
+ * The ids a page holds once an action's error boundary `boundary` shows: the
+ * ones above it. Nothing at or below the boundary ran after the action's
+ * write (its response and the follow-up cut there), so the next request must
+ * not hold it. ShortCodes nest, so those ids start with the boundary's: the
+ * boundary, its loaders (`${id}D…`), its slots and every entry under it. A
+ * sibling with a longer index (`…R10` beside `…R1`) is kept.
+ */
+export function idsAboveBoundary(
+  ids: string[],
+  boundary: string | undefined,
+): string[] {
+  return boundary
+    ? ids.filter(
+        (id) =>
+          !id.startsWith(boundary) || /\d/.test(id.charAt(boundary.length)),
+      )
+    : ids;
+}
+
+/**
+ * The error segment of every action error boundary committed, by identity
+ * (server-action-bridge.ts adds and deletes). An entry shows one while its
+ * cached list still holds that object: a later commit on the entry replaces
+ * the list, and a refetch that holds the boundary keeps it. Weak, so a
+ * replaced boundary is not kept alive. Two routers never share a segment
+ * object. No hook reads it.
+ */
+export const actionBoundaries: WeakSet<ResolvedSegment> = new WeakSet();
+
+/**
+ * The index of the deepest action error boundary in `segments`, -1 for none.
+ * It is that action's outcome, which no GET reproduces: a background refetch
+ * of the page (the follow-up, Back/Forward's stale revalidation, the
+ * cross-tab refresh) holds it and renders what is above it. At 0 nothing is
+ * above it.
+ */
+export function actionBoundaryAt(segments: readonly ResolvedSegment[]): number {
+  let at = segments.length;
+  while (at-- && !actionBoundaries.has(segments[at]));
+  return at;
+}

package/src/browser/server-action-bridge.ts

@@ -15,6 +15,9 @@ import {
 import { KEEP_CACHE_HEADER } from "./cookie-name.js";
 import { createNavigationTransaction } from "./navigation-transaction.js";
 import {
+  actionBoundaries,
+  actionBoundaryAt,
+  idsAboveBoundary,
   reconcileSegments,
   reconcileErrorSegments,
 } from "./segment-reconciler.js";
@@ -52,6 +55,7 @@ import { stampLocationState } from "./react/location-state-shared.js";
 import { classifyActionOutcome } from "./action-coordinator.js";
 import { revalidationErrorOf } from "../decode-loader-results.js";
 import { getAppVersion } from "./app-version.js";
+import { writePartialParams } from "./wire-protocol.js";
 import {
   decideCommitGatedOff,
   findActionFormData,
@@ -205,6 +209,8 @@ export function createServerActionBridge(
     actionId?: string;
     /** transition({ when }) `action` fields for the refetch commit. */
     action?: TransitionWhenActionInput;
+    /** The follow-up's held error boundary (UpdateMode `action`). */
+    boundary?: string;
   };
 
   /** The follow-up's transition({ when }) fields: the last owing action's. */
@@ -254,13 +260,13 @@ export function createServerActionBridge(
   let followUpsStarted = 0;
   /** The newest follow-up, until it ends: leaveFollowUp() aborts it. */
   let followUpRunning: { handle: NavigationHandle; due: FollowUp } | undefined;
-
   /**
    * The follow-up revalidation: the rules are R1-R7 in
    * docs/internal/execution-model.md. Once the batch's last action exited,
    * the page on screen that missed a write is refetched once, whole (no
-   * segments held, so every loader re-runs), in the action lane (storeOnly,
-   * skipLoadingState: useNavigation() stays idle).
+   * segments held, so every loader re-runs; above an action's boundary, see
+   * below), in the action lane (storeOnly, skipLoadingState:
+   * useNavigation() stays idle).
    *
    * - Never over an intercept: a request holding no segments drops the page
    *   under it (match-result.ts buildMatchResult). Checked when it would run,
@@ -270,6 +276,10 @@ export function createServerActionBridge(
    *   keeps its error on screen, and the debt is dropped.
    * - Runs again when it is left before its commit (a navigation, or an action
    *   that started: leaveFollowUp), for the page then on screen.
+   * - Holds the action error boundary the page shows (actionBoundaryAt): it
+   *   is that action's outcome, which no GET reproduces, so the server
+   *   renders every segment above it and nothing at or below it. With
+   *   nothing above it (the page's first segment), the debt is dropped.
    */
   function followUp(): void {
     if (!owed || isActionFenceActive()) return;
@@ -284,8 +294,16 @@ export function createServerActionBridge(
     const due = owed;
     owed = undefined;
     if (store.getInterceptSourceUrl()) return;
+    // The deepest action boundary the page shows: none (-1) refetches the
+    // page whole, the first segment (0) leaves nothing above it.
+    const shown =
+      store.getCachedSegments(store.getHistoryKey())?.segments ?? [];
+    const at = actionBoundaryAt(shown);
+    if (at === 0) return;
+    // Not on `due`: a run owed again (owed ??= due) looks again.
+    const held = { ...due, boundary: shown[at]?.id };
     const generation = ++followUpsStarted;
-    refetchRoute(due, {
+    refetchRoute(held, {
       started: (handle) => (followUpRunning = { handle, due }),
       ended: (left) => {
         if (generation !== followUpsStarted) return;
@@ -358,6 +376,7 @@ export function createServerActionBridge(
           ...(src ? { interceptSourceUrl: src } : {}),
           ...(opts.actionId !== undefined ? { actionId: opts.actionId } : {}),
           ...(opts.action ? { action: opts.action } : {}),
+          boundary: opts.boundary,
         },
       );
       return { started: true, error };
@@ -487,28 +506,16 @@ export function createServerActionBridge(
       // Create temporary references for serialization
       const temporaryReferences = deps.createTemporaryReferenceSet();
 
-      // Build action request URL with current segments
-      const url = new URL(window.location.href);
-      url.searchParams.set("_rsc_action", id);
-      url.searchParams.set(
-        "_rsc_segments",
-        segmentState.currentSegmentIds.join(","),
-      );
-      // Add version param for version mismatch detection
-      const version = getAppVersion();
-      if (version) {
-        url.searchParams.set("_rsc_v", version);
-      }
-      // Add router ID for app switch detection
-      const rid = store.getRouterId?.();
-      if (rid) {
-        url.searchParams.set("_rsc_rid", rid);
-      }
-      // The page's rewrite target: the server diffs the re-render against it.
-      const rewriteTarget = store.getHistoryEntryMemory()?.rewriteTarget;
-      if (rewriteTarget) {
-        url.searchParams.set("_rsc_rt", rewriteTarget);
-      }
+      // Build action request URL with current segments; the server diffs the
+      // re-render against the page's rewrite target.
+      const url = writePartialParams(new URL(window.location.href), {
+        action: id,
+        segmentIds: segmentState.currentSegmentIds,
+        emptySegments: "send",
+        version: getAppVersion(),
+        routerId: store.getRouterId?.(),
+        rewriteTarget: store.getHistoryEntryMemory()?.rewriteTarget,
+      });
 
       // Encode arguments
       const encodedBody = await deps.encodeReply(args, { temporaryReferences });
@@ -740,36 +747,50 @@ export function createServerActionBridge(
       }
 
       // Handle error responses with error boundary UI
-      if (isError && isPartial && segments && diff) {
+      if (isError && isPartial && segments) {
         log("processing error boundary response");
 
-        // Fail current handle BEFORE aborting all actions so the event controller
-        // records the error state (abortAllActions clears inflight entries)
+        // transition({ when }) sees action.error on the boundary commit and on
+        // a dropped one's follow-up.
+        whenAction = {
+          ...whenAction,
+          error: returnValue && !returnValue.ok ? returnValue.data : undefined,
+        };
+
+        // No consolidation: the boundary replaces the page, or the page left.
+        handle.clearConsolidation();
+
+        const currentKey = store.getHistoryKey();
+        const pageLeft = () =>
+          navigatedSince() || store.getHistoryKey() !== currentKey;
+        // The action's page left the screen (during the flight or the error
+        // render): drop the boundary; the call rejects and the exit owes the
+        // follow-up.
+        const dropBoundary = () => {
+          log("user navigated during error render, skipping");
+          if (returnValue && !returnValue.ok) throw returnValue.data;
+          handle.complete(undefined);
+          return undefined;
+        };
+        if (pageLeft()) return dropBoundary();
+
+        // fail() settles once the response's stream ends; the abort below
+        // spares this action, so its entry keeps the error for useAction().
         if (returnValue && !returnValue.ok) {
           handle.fail(returnValue.data);
         }
 
-        // Abort all other pending action requests - error takes precedence
-        // This prevents other actions from completing and overwriting the error UI
-        eventController.abortAllActions();
-
-        // Clear concurrent action tracking - no consolidation needed when showing error
-        handle.clearConsolidation();
+        // Abort the other actions in flight: the error takes precedence, so
+        // none completes over the boundary.
+        eventController.abortAllActions(handle.id);
 
         // Get current page's cached segments
-        const currentKey = store.getHistoryKey();
         const cached = store.getCachedSegments(currentKey);
         const cachedSegments = cached?.segments || [];
 
         // Reconcile error segments with cached tree
         const errorResult = reconcileErrorSegments(cachedSegments, segments);
 
-        // transition({ when }) decides the error-boundary commit too, with
-        // `action.error` set.
-        whenAction = {
-          ...whenAction,
-          error: returnValue && !returnValue.ok ? returnValue.data : undefined,
-        };
         const errorGatedOff = decideActionGatedOff(
           errorResult.segments,
           metadata,
@@ -786,28 +807,22 @@ export function createServerActionBridge(
               : undefined,
         });
 
-        // The page the action was sent from left the screen, during the
-        // flight or while the error tree rendered: the boundary is not shown,
-        // and the action's exit owes the page on screen the follow-up.
-        if (navigatedSince() || store.getHistoryKey() !== currentKey) {
-          log("user navigated during error render, skipping");
-          if (returnValue && !returnValue.ok) {
-            throw returnValue.data;
-          }
-          handle.complete(undefined);
-          return undefined;
-        }
-
-        // Update segment tracking to exclude error segment IDs
-        const errorSegmentIds = new Set(diff);
-        const segmentIdsAfterError = segmentState.currentSegmentIds.filter(
-          (id) => !errorSegmentIds.has(id),
-        );
+        if (pageLeft()) return dropBoundary();
 
         // Cache (and bump the nav instance) BEFORE the UI update so a deferred
         // handle pushed by the error-boundary render still applies — see the
-        // "normal" case below for why caching after onUpdate dropped it.
-        store.setSegmentIds(segmentIdsAfterError);
+        // "normal" case below for why caching after onUpdate dropped it. The
+        // action's boundary is the last error segment: the server's cut stops
+        // there (segment-resolution/revalidation.ts resolveAllSegments). The
+        // page holds what is above it, the loaders the response re-ran
+        // included, and no error segment.
+        const errors = segments.filter((s) => s.type === "error");
+        const boundary = errors[errors.length - 1];
+        store.setSegmentIds(
+          idsAboveBoundary(segmentState.currentSegmentIds, boundary?.id).filter(
+            (id) => !errors.some((s) => s.id === id),
+          ),
+        );
         const currentHandleData = liveHandleDataForCache(
           eventController,
           store,
@@ -819,6 +834,7 @@ export function createServerActionBridge(
           currentHandleData,
         );
         store.rememberDisplayedEntry();
+        if (boundary) actionBoundaries.add(boundary);
 
         // Update UI with error boundary.
         if (process.env.NODE_ENV !== "production") auditTreeCause("action");
@@ -919,6 +935,10 @@ export function createServerActionBridge(
           metadata?.locationState,
           eventController,
         );
+        // A success on the page supersedes the action boundary it shows
+        // (R4): a repair that stands in for this commit, direct or owed to
+        // the batch's end, holds none.
+        for (const s of cachedSegments) actionBoundaries.delete(s);
       }
       whenAction = { ...whenAction, result: returnData };
 

package/src/browser/types.ts

@@ -201,13 +201,27 @@ export interface InflightAction {
  * @internal This type is an implementation detail. Use PublicNavigationState instead.
  */
 export interface NavigationState {
-  /** Navigation lifecycle state (idle or loading during navigation) */
+  /**
+   * Lifecycle state: `"loading"` while a navigation is in flight and while a
+   * server action runs, `"idle"` otherwise
+   */
   state: "idle" | "loading";
 
-  /** Whether RSC data is currently streaming (initial load or navigation) */
+  /**
+   * Whether RSC data is currently streaming: a navigation's response, or a
+   * server action's response (initial load, navigation or action)
+   */
   isStreaming: boolean;
 
-  /** Current location */
+  /**
+   * True while a navigation is in flight (fetching or streaming, before its
+   * commit); false during a server action, whose `state` is still `"loading"`.
+   * Drive a navigation progress bar from this and an action spinner from
+   * `state`.
+   */
+  isNavigating: boolean;
+
+  /** The page on screen; moves when the next page shows (`pendingUrl` is the page being fetched) */
   location: NavigationLocation;
 
   /** URL being navigated to (null when idle) */
@@ -505,6 +519,8 @@ export interface NavigateOptionsInternal extends Omit<
   _skipCache?: boolean;
   /** Server redirects already followed by this navigation chain (0 for a user navigation) */
   _redirectHops?: number;
+  /** The URL a redirected navigation chain started from: a link to it stays pending (useLinkStatus) */
+  _redirectFrom?: string;
 }
 
 /**
@@ -649,7 +665,8 @@ export interface NavigationStore {
         handlesPending?: boolean;
       }
     | undefined;
-  hasHistoryCache(historyKey: string): boolean;
+  /** Whether an intercept entry is cached for the plain `historyKey`, from any source page. */
+  hasInterceptCache(historyKey: string): boolean;
   /**
    * Update only the handleData (and optionally the stale / handlesPending flags)
    * of an existing cache entry. When a flag is omitted the entry's current value
@@ -717,6 +734,8 @@ export interface FetchPartialOptions {
   signal?: AbortSignal;
   /** If true, this is a stale cache revalidation request - server should force revalidators */
   staleRevalidation?: boolean;
+  /** Sent as `_rsc_boundary` (wire-params.ts WIRE.boundary). */
+  boundary?: string;
   interceptSourceUrl?: string;
   /** RSC version for cache invalidation detection */
   version?: string;
@@ -802,7 +821,8 @@ export interface ServerActionBridgeConfig {
  */
 export interface NavigationBridge {
   navigate(url: string, options?: NavigateOptionsInternal): Promise<void>;
-  refresh(): Promise<void>;
+  /** `crossTab`: another tab's write; an action's error boundary stays. */
+  refresh(crossTab?: boolean): Promise<void>;
   /** `event`: the popstate event; a traversal the browser animated itself (hasUAVisualTransition) is not animated again. */
   handlePopstate(event?: PopStateEvent): Promise<void>;
   registerLinkInterception(): () => void;

package/src/browser/wire-protocol.ts

@@ -0,0 +1,43 @@
+import { WIRE } from "../wire-params.js";
+
+/** The parameters of a partial request: a navigation, a prefetch or a JS server action. */
+export interface PartialRequestInit {
+  /** A JS server action's id: written as `_rsc_action` in place of `_rsc_partial`. */
+  action?: string;
+  /** The mounted segment ids the server diffs against. */
+  segmentIds: readonly string[];
+  /**
+   * An empty `segmentIds`: "send" writes `_rsc_segments=` (navigation,
+   * action), "omit" leaves it out (prefetch). The prefetch cache keys carry
+   * the difference.
+   */
+  emptySegments: "send" | "omit";
+  stale?: boolean;
+  boundary?: string;
+  version?: string;
+  routerId?: string;
+  rewriteTarget?: string;
+  fill?: boolean;
+}
+
+/**
+ * Writes the partial-request parameters onto `url` in the one order every
+ * sender uses. Navigation and prefetch cache keys are built from the result
+ * (prefetch/cache.ts), so a navigation adopts a prefetch only while both
+ * write identically: browser/__tests__/wire-urls.test.ts pins the strings.
+ */
+export function writePartialParams(url: URL, init: PartialRequestInit): URL {
+  const params = url.searchParams;
+  if (init.action !== undefined) params.set(WIRE.action, init.action);
+  else params.set(WIRE.partial, "true");
+  if (init.segmentIds.length > 0 || init.emptySegments === "send") {
+    params.set(WIRE.segments, init.segmentIds.join(","));
+  }
+  if (init.stale) params.set(WIRE.stale, "true");
+  if (init.boundary) params.set(WIRE.boundary, init.boundary);
+  if (init.version) params.set(WIRE.version, init.version);
+  if (init.routerId) params.set(WIRE.routerId, init.routerId);
+  if (init.rewriteTarget) params.set(WIRE.rewriteTarget, init.rewriteTarget);
+  if (init.fill) params.set(WIRE.fill, "1");
+  return url;
+}

package/src/cache/cache-key-utils.ts

@@ -187,8 +187,10 @@ export const KEY_PART_PREFIX = "key:";
  * (CacheScope.resolveKeyFrom, CacheScope.resolvePartition): the `key()`
  * results of the scope's cache() chain, outermost first, then its default
  * parts: the keyGenerator results of enclosing scopes on another store
- * (#974) and, for a record key under a scope without its own `key()`, its
- * default key (or its store's keyGenerator result, #970).
+ * (#974) and, for a route record key, the scope's own part: without a
+ * `key()` of its own, its default key (or its store's keyGenerator result,
+ * #970); with one, the default key's request kind (`doc`, `partial` or
+ * `intercept:<intercept>`, routeRecordKind in cache-scope.ts).
  *
  * Key scheme invariant (#975). A `key()` result is often request input,
  * and a record key has no route or scope discriminator (the store reads
@@ -214,9 +216,13 @@ export const KEY_PART_PREFIX = "key:";
  * A namespaced `key()` result starts with `key:` and holds no `|`. A
  * composed key holds a `|` and either starts with `key:` or holds no `:`.
  * Among composed keys, splitting on `|` recovers each part, a part's kind
- * (a `key:` prefix, or no `:` at all) and its value. Pinned by the collision
- * probe in src/cache/__tests__/cache-scope-chain.test.ts. A keyGenerator
- * result is the store's own namespace, as before.
+ * (a `key:` prefix, or no `:` at all) and its value. A request kind part is
+ * a default key's prefix without the URL after it, so it never equals a
+ * default key part; a keyGenerator part can equal it (`doc`) only when the
+ * keyGenerator returns a constant, which already gives every URL one record.
+ * Pinned by the collision probe in
+ * src/cache/__tests__/cache-scope-chain.test.ts. A keyGenerator result is
+ * the store's own namespace, as before.
  *
  * Shared with the testing helper `shellCacheKey`, so a test builds the
  * production partition.