@jsenv/navi 0.29.98 → 0.29.101

package/dist/jsenv_navi.js

@@ -2819,7 +2819,10 @@ const readSignalForUrlBuild = (connection) => {
 /**
  * Creates a custom route pattern matcher
  */
-const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
+const createRoutePattern = (
+  pattern,
+  { searchParams = {}, params: paramConstraints = {} } = {},
+) => {
   // Detect and process path signals in the pattern
   const [cleanPattern, pathConnections] = detectSignals(pattern);
 
@@ -2844,9 +2847,11 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
   // All connections (path + query) for ancestor/descendant signal resolution
   const connections = [...pathConnections, ...queryConnectionMap.values()];
 
+  const paramConstraintMap = createParamConstraintMap(paramConstraints);
   const parsedPattern = parsePattern(cleanPattern, {
     pathConnectionMap,
     queryConnectionMap,
+    paramConstraintMap,
   });
 
   debug$3(`[CustomPattern] Created pattern:`, parsedPattern);
@@ -2854,11 +2859,21 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
   debug$3(`[CustomPattern] Path connections:`, pathConnectionMap.size);
   debug$3(`[CustomPattern] Query connections:`, queryConnectionMap.size);
 
-  const applyOn = (url) => {
+  /**
+   * @param {string} url
+   * @param {object} [options]
+   * @param {boolean} [options.exact] - Only match the url this pattern is the
+   *   address of: a trailing slash or a wildcard stops catching what lies below
+   *   it. What "/" means for a container ("everything under me") and what it
+   *   means for a redirection ("that very address") are not the same question.
+   */
+  const applyOn = (url, { exact = false } = {}) => {
     const result = matchUrl(parsedPattern, url, {
       baseUrl,
       baseFileUrl,
       queryConnectionMap,
+      paramConstraintMap,
+      exact,
       patternObj: patternObject,
     });
 
@@ -3524,7 +3539,9 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
     const entryIsMeaningful = (conn) => {
       const entry = intended.get(conn.paramName);
       return (
-        Boolean(entry) && entry.value !== undefined && conn.isCustomValue(entry.value)
+        Boolean(entry) &&
+        entry.value !== undefined &&
+        conn.isCustomValue(entry.value)
       );
     };
     if (ancestorPattern !== patternObject.parent) {
@@ -3714,6 +3731,7 @@ const createRoutePattern = (pattern, { searchParams = {} } = {}) => {
     connections,
     pathConnectionMap, // Separate map for path parameters
     queryConnectionMap, // Separate map for query parameters
+    paramConstraintMap, // Which values each param accepts (Map<paramName, test>)
     parsedPattern,
     children: [],
     parent: null,
@@ -3821,10 +3839,60 @@ const detectSignals = (routePattern) => {
   return [updatedPattern, signalConnections];
 };
 
+const EMPTY_PARAM_CONSTRAINT_MAP = new Map();
+
+/**
+ * Turns `{ gameId: /^W-[A-Z0-9]{8}$/i }` into `Map<paramName, (value) => boolean>`.
+ * A constraint is a regexp, a list of accepted values, or a predicate.
+ * A constraint decides which url segments the param accepts; a segment it
+ * declines makes the whole route a non-match, so only path params can carry
+ * one — a search param is extracted from a url the path already matched.
+ */
+const createParamConstraintMap = (paramConstraints) => {
+  const entries = Object.entries(paramConstraints);
+  if (entries.length === 0) {
+    return EMPTY_PARAM_CONSTRAINT_MAP;
+  }
+  const paramConstraintMap = new Map();
+  for (const [paramName, constraint] of entries) {
+    if (constraint instanceof RegExp) {
+      paramConstraintMap.set(paramName, (value) => {
+        constraint.lastIndex = 0; // a /g or /y regexp would otherwise resume where the previous test stopped
+        return constraint.test(value);
+      });
+      continue;
+    }
+    if (Array.isArray(constraint)) {
+      // a url segment is a string, so the list is compared as strings:
+      // `oneOf: [1, 2, 3]` accepts "/2"
+      const acceptedValueSet = new Set(
+        constraint.map((value) => String(value)),
+      );
+      paramConstraintMap.set(paramName, (value) => acceptedValueSet.has(value));
+      continue;
+    }
+    if (typeof constraint === "function") {
+      paramConstraintMap.set(paramName, (value) => Boolean(constraint(value)));
+      continue;
+    }
+    throw new TypeError(
+      `params.${paramName} must be a regexp, an array of values or a function, got ${constraint}`,
+    );
+  }
+  return paramConstraintMap;
+};
+
 /**
  * Parse a route pattern string into structured segments
  */
-const parsePattern = (pattern, { pathConnectionMap, queryConnectionMap }) => {
+const parsePattern = (
+  pattern,
+  {
+    pathConnectionMap,
+    queryConnectionMap,
+    paramConstraintMap = EMPTY_PARAM_CONSTRAINT_MAP,
+  },
+) => {
   // Build queryParams from queryConnectionMap
   const queryParams = [];
   for (const [paramName, connection] of queryConnectionMap) {
@@ -3878,13 +3946,14 @@ const parsePattern = (pattern, { pathConnectionMap, queryConnectionMap }) => {
       // 1. Explicitly marked with ?
       // 2. Has a default value
       // 3. Connected signal has undefined value and no explicit default (allows /map to match /map/:panel)
+      //    — unless the param is constrained: "no segment" is not one of the values it accepts
       const connection =
         pathConnectionMap.get(paramName) || queryConnectionMap.get(paramName);
       const hasDefault =
         connection && connection.getDefaultValue() !== undefined;
       let isOptional = seg.endsWith("?") || hasDefault;
 
-      if (!isOptional) {
+      if (!isOptional && !paramConstraintMap.has(paramName)) {
         // Check if connected signal has undefined value (making parameter optional for index routes)
         if (
           connection &&
@@ -3995,7 +4064,14 @@ const tryExtractChildParameters = (
       // We need to verify that this parameter isn't already captured by parent
       if (!(segment.name in existingParams)) {
         const urlSegment = remainingSegments[remainingIndex];
-        childParams[segment.name] = decodeURIComponent(urlSegment);
+        const paramValue = decodeURIComponent(urlSegment);
+        const paramConstraint = childPattern.paramConstraintMap.get(
+          segment.name,
+        );
+        if (paramConstraint && !paramConstraint(paramValue)) {
+          return null; // the child declines this value, it cannot explain these segments
+        }
+        childParams[segment.name] = paramValue;
         remainingIndex++;
       }
     } else if (
@@ -4022,7 +4098,14 @@ const tryExtractChildParameters = (
 const matchUrl = (
   parsedPattern,
   url,
-  { baseUrl, baseFileUrl, queryConnectionMap, patternObj = null },
+  {
+    baseUrl,
+    baseFileUrl,
+    queryConnectionMap,
+    paramConstraintMap = EMPTY_PARAM_CONSTRAINT_MAP,
+    exact = false,
+    patternObj = null,
+  },
 ) => {
   // Parse the URL
   const urlObj = new URL(url, baseUrl);
@@ -4064,7 +4147,7 @@ const matchUrl = (
     }
 
     // Root route with trailing slash matches all sub-paths (prefix matching, like other trailing-slash routes)
-    if (parsedPattern.trailingSlash) {
+    if (parsedPattern.trailingSlash && !exact) {
       return extractSearchParams(urlObj, queryConnectionMap);
     }
 
@@ -4133,7 +4216,12 @@ const matchUrl = (
 
       // Capture URL segment as parameter value
       const urlSeg = urlSegments[urlSegmentIndex];
-      params[patternSeg.name] = decodeURIComponent(urlSeg);
+      const paramValue = decodeURIComponent(urlSeg);
+      const paramConstraint = paramConstraintMap.get(patternSeg.name);
+      if (paramConstraint && !paramConstraint(paramValue)) {
+        return null; // the param declines this value: the route does not match
+      }
+      params[patternSeg.name] = paramValue;
       urlSegmentIndex++;
     }
   }
@@ -4142,8 +4230,7 @@ const matchUrl = (
   // Patterns with trailing slashes can match additional URL segments (like wildcards)
   // Patterns without trailing slashes should match exactly (unless they're wildcards)
   if (
-    !parsedPattern.wildcard &&
-    !parsedPattern.trailingSlash &&
+    (exact || (!parsedPattern.wildcard && !parsedPattern.trailingSlash)) &&
     urlSegmentIndex < urlSegments.length
   ) {
     return null; // Pattern without trailing slash/wildcard should not match extra segments
@@ -4862,8 +4949,61 @@ const getRoutePrivateProperties = (route) => {
 const ROUTE_NOT_MATCHING_PARAMS = {};
 // Flag to prevent signal-to-URL synchronization during URL-to-signal synchronization
 let isUpdatingRoutesFromUrl = false;
-const route = (pattern, { searchParams } = {}) => {
-  const routePattern = createRoutePattern(pattern, { searchParams });
+/**
+ * Declares a route from an url pattern.
+ *
+ * @param {string} pattern - The url pattern, where `:name` is a path param and
+ *   `:name=${signal}` binds that param to a signal.
+ * @param {object} [options]
+ * @param {Object<string, import("@preact/signals").Signal>} [options.searchParams]
+ *   Search params this route two-way syncs with, by name.
+ * @param {Object<string, RegExp | Array | ((value: string) => boolean)>} [options.params]
+ *   Which values a path param accepts, by param name: a regexp tested against the
+ *   decoded segment, the list of accepted values (compared as strings, so it can
+ *   be the `oneOf` of the signal bound to that param), or a predicate. A route
+ *   whose param declines the segment does not match at all: no signal is
+ *   written, `<Route fallback>` is reachable, and `/:gameId` can sit at the root
+ *   without swallowing `/cgu`. A constrained param is also required — no segment
+ *   is not one of the values it accepts — so `/:gameId` does not match `/`.
+ *
+ *   Constrain the shape, not the existence: whether that game exists is for the
+ *   route action and the page to answer, on a route that did match.
+ *
+ *   ```js
+ *   route(`/:gameId=${gamePageIdSignal}`, { params: { gameId: /^W-[A-Z0-9]{8}$/i } });
+ *   route(`/games/:section=${sectionSignal}`, { params: { section: SECTIONS } });
+ *   ```
+ * @param {object} [options.redirectRoute]
+ *   This address only sends elsewhere: the route it resolves to. The
+ *   redirection happens at the door of the navigation, so this address is never
+ *   displayed, never enters the history, runs no route action and writes no
+ *   signal — going back lands on the page before it, not on the redirection
+ *   again. It fires on this route's own address only: a trailing slash still
+ *   catches what lies below it for rendering, never for redirecting.
+ *
+ *   The params found in the url carry over to the ones the target route
+ *   declares under the same name; what it cannot place is left behind.
+ *
+ *   ```js
+ *   route("/", { redirectRoute: MY_GAMES_PAGE });
+ *   // gameId carries over on its own, shareState is not a param of GAME_PAGE
+ *   route("/:gameId/:shareState", { redirectRoute: GAME_PAGE });
+ *   ```
+ * @param {object|Function|null} [options.redirectRouteParams]
+ *   What to change about the params carried over: an object, or a function of
+ *   the params found in the url returning one. Written params win over inherited
+ *   ones, `undefined` drops one, and `null` carries nothing over at all.
+ *
+ *   ```js
+ *   route("/legacy/:id", { redirectRoute: GAME_PAGE, redirectRouteParams: ({ id }) => ({ gameId: id }) });
+ *   route("/:gameId/invite", { redirectRoute: HOME_PAGE, redirectRouteParams: null });
+ *   ```
+ */
+const route = (
+  pattern,
+  { searchParams, params, redirectRoute, redirectRouteParams } = {},
+) => {
+  const routePattern = createRoutePattern(pattern, { searchParams, params });
   const { cleanPattern } = routePattern;
   const [publishStatus, subscribeStatus] = createPubSub();
 
@@ -4906,6 +5046,8 @@ const route = (pattern, { searchParams } = {}) => {
   {
     const routePrivateProperties = {
       routePattern,
+      redirectRoute,
+      redirectRouteParams,
       setup: null,
       updateStatus: null,
       cleanup: null,
@@ -5229,6 +5371,113 @@ const route = (pattern, { searchParams } = {}) => {
 
 const [publishRouteMutations, observeRouteMutations] = createPubSub();
 
+let redirectingRouteSet = null;
+/**
+ * Where does this url really lead?
+ *
+ * Asked at the door of every navigation, before the url is written anywhere —
+ * an address that only sends elsewhere must not become a page, an entry in the
+ * history, or a route anything can see matching. Answered without reading a
+ * single signal: the url alone says it.
+ *
+ * The chain is followed here rather than by letting each redirection navigate
+ * in turn, so one navigation happens and the addresses in between leave no
+ * trace at all.
+ *
+ * @param {string} url
+ * @returns {string|null} The url to go to instead, or null.
+ */
+const resolveRouteRedirection = (url) => {
+  if (!redirectingRouteSet || redirectingRouteSet.size === 0) {
+    return null;
+  }
+  let urlToResolve = url;
+  let redirectionUrl = null;
+  const urlChain = [url];
+  while (true) {
+    const nextUrl = resolveRedirectionOnce(urlToResolve);
+    if (!nextUrl || nextUrl === urlToResolve) {
+      break;
+    }
+    if (urlChain.includes(nextUrl)) {
+      throw new Error(
+        `Redirection cycle: ${[...urlChain, nextUrl].join(" -> ")}`,
+      );
+    }
+    urlChain.push(nextUrl);
+    redirectionUrl = nextUrl;
+    urlToResolve = nextUrl;
+  }
+  return redirectionUrl;
+};
+const resolveRedirectionOnce = (url) => {
+  let redirectingRoute = null;
+  let redirectingRouteParams = null;
+  let maxDepth = -1;
+  for (const route of redirectingRouteSet) {
+    const { routePattern } = getRoutePrivateProperties(route);
+    // exact: what a trailing slash catches is what a container renders, not
+    // what an address redirects — "/" redirecting must not take "/cgu" with it
+    const urlParams = routePattern.applyOn(url, { exact: true });
+    if (!urlParams) {
+      continue;
+    }
+    // Deeper = more specific, the reading the whole router shares (see
+    // replaceParams): "/:gameId/invite" is a child of "/:gameId/:shareState",
+    // so it answers for an url both of them match.
+    if (routePattern.depth > maxDepth) {
+      maxDepth = routePattern.depth;
+      redirectingRoute = route;
+      redirectingRouteParams = urlParams;
+    }
+  }
+  if (!redirectingRoute) {
+    return null;
+  }
+  return buildRedirectionUrl(redirectingRoute, redirectingRouteParams);
+};
+const buildRedirectionUrl = (route, urlParams) => {
+  const { redirectRoute, redirectRouteParams } =
+    getRoutePrivateProperties(route);
+  const paramsCarriedOver =
+    redirectRouteParams === null
+      ? {}
+      : paramsTargetCanPlace(redirectRoute, urlParams);
+  if (!redirectRouteParams) {
+    return redirectRoute.buildUrl(paramsCarriedOver);
+  }
+  const paramsWritten =
+    typeof redirectRouteParams === "function"
+      ? redirectRouteParams(urlParams)
+      : redirectRouteParams;
+  // A param written as undefined is a param dropped: `paramName in params` is
+  // what tells a url build "this one is decided", value included (resolveParams)
+  return redirectRoute.buildUrl({ ...paramsCarriedOver, ...paramsWritten });
+};
+
+/**
+ * The params of the url being left that the target route can put somewhere:
+ * its own path segments and the search params it declares. What it cannot
+ * place would otherwise be appended to the url as a query param, and a share
+ * link resolving to "/W-ABC234PQ?shareState=1" is not the address anyone meant.
+ */
+const paramsTargetCanPlace = (redirectRoute, urlParams) => {
+  const { routePattern } = getRoutePrivateProperties(redirectRoute);
+  const { parsedPattern, queryConnectionMap } = routePattern;
+  const paramsCarriedOver = {};
+  for (const paramName of Object.keys(urlParams)) {
+    const canPlace =
+      queryConnectionMap.has(paramName) ||
+      parsedPattern.segments.some(
+        (segment) => segment.type === "param" && segment.name === paramName,
+      );
+    if (canPlace) {
+      paramsCarriedOver[paramName] = urlParams[paramName];
+    }
+  }
+  return paramsCarriedOver;
+};
+
 let setupRoutesCalled = false;
 const setupRoutes = (routes) => {
   if (setupRoutesCalled) {
@@ -5258,6 +5507,22 @@ This prevents cross-test pollution and ensures clean state.`,
     setup({ routeSet, getUrl });
   }
 
+  // Checked here rather than at declaration: a route may redirect to one
+  // declared after it, and reading the target then would forbid that order.
+  redirectingRouteSet = new Set();
+  for (const route of routeSet) {
+    const { redirectRoute } = getRoutePrivateProperties(route);
+    if (!redirectRoute) {
+      continue;
+    }
+    if (!redirectRoute.isRoute) {
+      throw new TypeError(
+        `${route} redirects to ${redirectRoute}, expecting a route object`,
+      );
+    }
+    redirectingRouteSet.add(route);
+  }
+
   // Store previous route states to detect changes
   const routePreviousStateMap = new WeakMap();
   const updateRoutes = (
@@ -5501,6 +5766,7 @@ This prevents cross-test pollution and ensures clean state.`,
       routePrivatePropertiesMap.delete(route);
     }
     routeSet.clear();
+    redirectingRouteSet = null;
     setupRoutesCalled = false;
   };
   return {
@@ -11938,6 +12204,39 @@ const reportErrorIfNobodyDisplaysIt = (error, { action } = {}) => {
 
 const SYMBOL_OBJECT_SIGNAL = Symbol.for("navi_object_signal");
 
+/*
+ * Actions: async callbacks wrapped in reactive state.
+ *
+ * An action owns a set of signals (params, runningState, error, value, data)
+ * and moves through IDLE → RUNNING → COMPLETED / FAILED / ABORTED (see
+ * action_run_states.js). `createAction(callback)` returns the root action;
+ * `.bindParams(params)` derives child actions (one per params value, cached),
+ * and binding a signal (or an object containing signals) returns an action
+ * *proxy* that retargets itself to the right child action as the signal
+ * changes (see createActionProxyFromSignal).
+ *
+ * How things run: prerun/run/rerun/reset never execute the action directly —
+ * they go through `dispatchActions`, which the navigation integration can
+ * replace via `setActionDispatcher` so that every action update participates
+ * in the browser navigation lifecycle (abort signals, navigation events).
+ * The default dispatcher calls `updateActions`, the single entry point that
+ * resolves priorities between the four operation sets (reset > rerun > run >
+ * prerun) and performs them.
+ *
+ * Memory design (the surprising part): nothing here keeps actions alive.
+ * Child actions are held through ephemerons (createJsValueWeakMap) so a child
+ * and its params are garbage-collected together, running actions live in
+ * iterable *weak* sets, and property/signal mirroring uses weakEffect. Two
+ * consequences to be aware of:
+ * - an action can exist in several places only if everyone shares the same
+ *   instance (the caches above are what makes lookups return it);
+ * - prerun actions may have no other reference yet, so
+ *   prerunProtectionRegistry pins them for a few minutes.
+ *
+ * An action run never throws: failures land in errorSignal and are reported
+ * once, by one rule, in action_error_report.js (see the comment in onRunError).
+ */
+
 let DEBUG$1 = false;
 const enableDebugActions = () => {
   DEBUG$1 = true;
@@ -11976,7 +12275,7 @@ const getActionDispatcher = () => dispatchActions;
 const rerunActions = async (actionSet, options) => {
   return dispatchActions({
     rerunSet: actionSet,
-    reason: "rerunActions was calle",
+    reason: "rerunActions was called",
     ...options,
   });
 };
@@ -11995,7 +12294,7 @@ const rerunActions = async (actionSet, options) => {
  */
 const prerunProtectionRegistry = (() => {
   const protectedActionMap = new Map(); // action -> { timeoutId, timestamp }
-  const PROTECTION_DURATION = 5 * 60 * 1000; // 5 minutes en millisecondes
+  const PROTECTION_DURATION = 5 * 60 * 1000; // 5 minutes
 
   const unprotect = (action) => {
     const protection = protectedActionMap.get(action);
@@ -12009,7 +12308,7 @@ const prerunProtectionRegistry = (() => {
 
   return {
     protect(action) {
-      // Si déjà protégée, étendre la protection
+      // already protected: extend the protection
       if (protectedActionMap.has(action)) {
         const existing = protectedActionMap.get(action);
         clearTimeout(existing.timeoutId);
@@ -12029,29 +12328,11 @@ const prerunProtectionRegistry = (() => {
     },
 
     unprotect,
-
-    isProtected(action) {
-      return protectedActionMap.has(action);
-    },
-
-    // Pour debugging
-    getProtectedActions() {
-      return Array.from(protectedActionMap.keys());
-    },
-
-    // Nettoyage manuel si nécessaire
-    clear() {
-      for (const [, protection] of protectedActionMap) {
-        clearTimeout(protection.timeoutId);
-      }
-      protectedActionMap.clear();
-    },
   };
 })();
 
 const formatActionSet = (actionSet, prefix = "") => {
-  let message = "";
-  message += `${prefix}`;
+  let message = prefix;
   for (const action of actionSet) {
     message += "\n";
     message += prefixFirstAndIndentRemainingLines(String(action), {
@@ -12386,7 +12667,6 @@ ${lines.join("\n")}`);
 };
 
 const NO_PARAMS = { __no_params__: true };
-const initialParamsDefault = NO_PARAMS;
 const mergeActionParams = (currentParams, newParams) => {
   if (currentParams === NO_PARAMS) {
     return newParams;
@@ -12434,7 +12714,7 @@ const createAction = (callback, rootOptions = {}) => {
     } = options;
     if (!Object.hasOwn(options, "params")) {
       // even undefined should be respected it's only when not provided at all we use default
-      params = initialParamsDefault;
+      params = NO_PARAMS;
     }
     if (value === undefined && data !== undefined) {
       value = data;
@@ -12447,11 +12727,7 @@ const createAction = (callback, rootOptions = {}) => {
     const errorSignal = signal(error);
     const valueSignal = signal(valueInitial);
     const dataSignal = valueToData
-      ? computed(() => {
-          const value = valueSignal.value;
-          const data = valueToData(value);
-          return data;
-        })
+      ? computed(() => valueToData(valueSignal.value))
       : valueSignal;
 
     const prerun = (options) => {
@@ -12484,7 +12760,7 @@ const createAction = (callback, rootOptions = {}) => {
       return dispatchSingleAction(action, "reset", options);
     };
     const abort = (reason) => {
-      if (runningState !== RUNNING) {
+      if (runningStateSignal.peek() !== RUNNING) {
         return false;
       }
       const actionAbort = actionAbortMap.get(action);
@@ -12510,7 +12786,7 @@ const createAction = (callback, rootOptions = {}) => {
      */
     const childActionWeakMap = createJsValueWeakMap();
     const _bindParams = (newParamsOrSignal, options = {}) => {
-      // ✅ CAS 1: Signal direct -> proxy
+      // Case 1: a signal → proxy that retargets as the signal changes
       if (isSignal(newParamsOrSignal)) {
         const combinedParamsSignal = computed(() => {
           const newParams = newParamsOrSignal.value;
@@ -12524,7 +12800,7 @@ const createAction = (callback, rootOptions = {}) => {
         );
       }
 
-      // ✅ CAS 2: Objet -> vérifier s'il contient des signals
+      // Case 2: a plain object → child action, or proxy when it contains signals
       if (isPlainObject$1(newParamsOrSignal)) {
         const staticParams = {};
         const signalMap = new Map();
@@ -12545,7 +12821,7 @@ const createAction = (callback, rootOptions = {}) => {
         }
 
         if (signalMap.size === 0) {
-          // Pas de signals, merge statique normal
+          // no signals: plain static merge
           if (
             params === null ||
             typeof params !== "object" ||
@@ -12563,24 +12839,27 @@ const createAction = (callback, rootOptions = {}) => {
           });
         }
 
-        // Combiner avec les params existants pour les valeurs statiques
-        const paramsSignal = computed(() => {
-          const params = {};
+        const combinedParamsSignal = computed(() => {
+          const combinedParams = {};
           for (const key of keyArray) {
             const signalForThisKey = signalMap.get(key);
             if (signalForThisKey) {
               // eslint-disable-next-line signals/no-conditional-value-read
-              params[key] = signalForThisKey.value;
+              combinedParams[key] = signalForThisKey.value;
             } else {
-              params[key] = staticParams[key];
+              combinedParams[key] = staticParams[key];
             }
           }
-          return params;
+          return combinedParams;
         });
-        return createActionProxyFromSignal(action, paramsSignal, options);
+        return createActionProxyFromSignal(
+          action,
+          combinedParamsSignal,
+          options,
+        );
       }
 
-      // ✅ CAS 3: Primitive or objects like DOMEvents etc -> action enfant
+      // Case 3: a primitive or non-plain object (DOM event, …) → child action
       return createChildAction({
         params: newParamsOrSignal,
         ...options,
@@ -12613,7 +12892,6 @@ const createAction = (callback, rootOptions = {}) => {
       return childAction;
     };
 
-    // ✅ Implement matchAllSelfOrDescendant
     const matchAllSelfOrDescendant = (predicate, { includeProxies } = {}) => {
       const matches = [];
 
@@ -12648,32 +12926,31 @@ const createAction = (callback, rootOptions = {}) => {
       generateActionCallSource(name, params),
     );
 
-    {
-      // Create the action as a function that can be called directly
-      action = function actionFunction(...args) {
-        if (args.length === 0) {
-          return action.rerun();
-        }
-        const boundAction = bindParams(...args);
-        return boundAction.rerun();
-      };
-      Object.defineProperty(action, "name", {
-        configurable: true,
-        get() {
-          return actionNameSignal.value;
-        },
-      });
-      Object.defineProperty(action, "callSource", {
-        configurable: true,
-        get() {
-          return actionCallSourceSignal.value;
-        },
-        set(v) {
-          actionCallSourceSignal.value = v;
-        },
-      });
-      actionWeakMap.set(action, action);
-    }
+    // The action is a callable: `ACTION(params)` is `ACTION.bindParams(params).rerun()`
+    action = function actionFunction(...args) {
+      if (args.length === 0) {
+        return action.rerun();
+      }
+      const boundAction = bindParams(...args);
+      return boundAction.rerun();
+    };
+    Object.defineProperty(action, "name", {
+      configurable: true,
+      get() {
+        return actionNameSignal.value;
+      },
+    });
+    Object.defineProperty(action, "callSource", {
+      configurable: true,
+      get() {
+        return actionCallSourceSignal.value;
+      },
+      set(v) {
+        actionCallSourceSignal.value = v;
+      },
+    });
+    // makes createAction(anAction) return the action itself
+    actionWeakMap.set(action, action);
 
     // Assign all the action properties and methods to the function
     Object.assign(action, {
@@ -12695,7 +12972,7 @@ const createAction = (callback, rootOptions = {}) => {
       reset,
       abort,
       bindParams,
-      matchAllSelfOrDescendant, // ✅ Add the new method
+      matchAllSelfOrDescendant,
       replaceParams: (newParams) => {
         const currentParams = paramsSignal.value;
         const nextParams = mergeActionParams(currentParams, newParams);
@@ -12723,7 +13000,7 @@ const createAction = (callback, rootOptions = {}) => {
       toString: () => action.callSource,
       meta,
       debug: (...args) => {
-        if (!meta.debug || DEBUG$1) {
+        if (!meta.debug && !DEBUG$1) {
           return;
         }
         console.debug(...args);
@@ -12738,7 +13015,8 @@ const createAction = (callback, rootOptions = {}) => {
     });
     Object.preventExtensions(action);
 
-    // Effects pour synchroniser les propriétés
+    // Mirror signals into plain properties (action.error, action.data, …)
+    // so non-reactive code can read them without subscribing.
     {
       weakEffect([action], (actionRef) => {
         isPrerun = isPrerunSignal.value;
@@ -12764,7 +13042,6 @@ const createAction = (callback, rootOptions = {}) => {
       });
     }
 
-    // Propriétés privées
     {
       const ui = {
         renderLoaded: null,
@@ -13043,8 +13320,8 @@ const createAction = (callback, rootOptions = {}) => {
  * @param {boolean} options.rerunOnChange - Ensures the action is rerun every time a signal value is modified.
  *   This enables live updates - for example, performing an HTTP GET request every time
  *   a list of filters changes, providing real-time results without user interaction.
- * @param {boolean} options.inheritData - When true, each new target action starts fresh with no inherited state.
- *   By default (false), the proxy carries over the previous target's value and error into the new action.
+ * @param {boolean} options.inheritData - When false, each new target action starts fresh with no inherited state.
+ *   By default (true), the proxy carries over the previous target's value and error into the new action.
  *   This keeps the facade in sync with the latest known data: `action.dataSignal.value` only changes when a
  *   new action completes, not when it starts loading. Code that needs to distinguish loading state can still
  *   check `action.runningState`, while code that just reads `action.data` always sees the most recent
@@ -13138,6 +13415,7 @@ const createActionProxyFromSignal = (
       currentAction = actionTarget;
       currentActionPrivateProperties = getActionPrivateProperties(actionTarget);
     }
+
     actionTargetPreviousWeakRef = actionTarget
       ? new WeakRef(actionTarget)
       : null;
@@ -13163,25 +13441,22 @@ const createActionProxyFromSignal = (
 
   const nameSignal = signal(action.name);
   const callSourceSignal = signal(`[Proxy] ${action.callSource}`);
-  let actionProxy;
-  {
-    actionProxy = function actionProxyFunction() {
-      return actionProxy.rerun();
-    };
-    Object.defineProperty(actionProxy, "name", {
-      configurable: true,
-      get() {
-        return nameSignal.value;
-      },
-    });
-    Object.defineProperty(actionProxy, "callSource", {
-      configurable: true,
-      get() {
-        return callSourceSignal.value;
-      },
-    });
-    actionWeakMap.set(actionProxy, actionProxy);
-  }
+  const actionProxy = function actionProxyFunction() {
+    return actionProxy.rerun();
+  };
+  Object.defineProperty(actionProxy, "name", {
+    configurable: true,
+    get() {
+      return nameSignal.value;
+    },
+  });
+  Object.defineProperty(actionProxy, "callSource", {
+    configurable: true,
+    get() {
+      return callSourceSignal.value;
+    },
+  });
+  actionWeakMap.set(actionProxy, actionProxy);
 
   // Create our own signal for params that we control completely
   const proxyParamsSignal = signal(paramsSignal.value);
@@ -13384,11 +13659,6 @@ const isPlainObject$1 = (obj) => {
   );
 };
 
-const COMPLETED_ACTION = createAction(() => undefined, {
-  name: "ACTION.COMPLETED",
-});
-getActionPrivateProperties(COMPLETED_ACTION).performRun({});
-
 // used by form elements such as <input>, <select>, <textarea> to have their own action bound to a single parameter
 // when inside a <form> the form params are updated when the form element single param is updated
 const useActionBoundToOneParam = (action, paramsSignal) => {
@@ -13410,19 +13680,27 @@ const useAction = (action, paramsSignal) => {
 };
 
 const useBoundAction = (action, actionParamsSignal) => {
-  const actionRef = useRef();
+  // The cache gives an inline function a stable action identity across renders.
+  // That identity is only wanted while `action` stays the same kind
+  // (function to function); when the kind changes — none ↔ function ↔ action
+  // object — each branch clears the other kind's refs so the control picks up
+  // its new role instead of the action it was born with.
+  const noopActionRef = useRef();
+  const actionFromFunctionRef = useRef();
   const actionCallbackRef = useRef();
 
   if (!action) {
-    const existingAction = actionRef.current;
-    if (existingAction) {
-      return existingAction;
+    actionFromFunctionRef.current = undefined;
+    actionCallbackRef.current = undefined;
+    const existingNoopAction = noopActionRef.current;
+    if (existingNoopAction) {
+      return existingNoopAction;
     }
     const noopAction = createAction(() => {}, { params: undefined });
     const noopActionBound = actionParamsSignal
       ? noopAction.bindParams(actionParamsSignal)
       : noopAction;
-    actionRef.current = noopActionBound;
+    noopActionRef.current = noopActionBound;
     return noopActionBound;
   }
   const isFunction = typeof action === "function";
@@ -13433,7 +13711,7 @@ const useBoundAction = (action, actionParamsSignal) => {
   }
   if (isFunctionButNotAnActionFunction(action)) {
     actionCallbackRef.current = action;
-    const existingAction = actionRef.current;
+    const existingAction = actionFromFunctionRef.current;
     if (existingAction) {
       return existingAction;
     }
@@ -13449,14 +13727,16 @@ const useBoundAction = (action, actionParamsSignal) => {
       },
     );
     if (!actionParamsSignal) {
-      actionRef.current = actionFromFunction;
+      actionFromFunctionRef.current = actionFromFunction;
       return actionFromFunction;
     }
     const actionBoundToParams =
       actionFromFunction.bindParams(actionParamsSignal);
-    actionRef.current = actionBoundToParams;
+    actionFromFunctionRef.current = actionBoundToParams;
     return actionBoundToParams;
   }
+  actionFromFunctionRef.current = undefined;
+  actionCallbackRef.current = undefined;
   if (actionParamsSignal) {
     return action.bindParams(actionParamsSignal);
   }
@@ -21508,6 +21788,24 @@ const setupBrowserIntegrationViaHistory = ({
     // the single door every navigation goes through, rather than by each caller
     // (navBack's fallback in particular arrives here raw).
     const url = new URL(target, window.location.href).href;
+    // An address that only sends elsewhere never becomes anything here: asked
+    // before the announcement, before the history write and before the routes,
+    // so that what follows is entirely about where the reader is going (see
+    // resolveRouteRedirection).
+    const redirectionUrl = resolveRouteRedirection(url);
+    if (redirectionUrl) {
+      if (redirectionUrl === window.location.href) {
+        // Asked to go where we already are: an address that redirects is never
+        // the one being displayed, so there is nothing to go to and nothing to
+        // stack on the history.
+        return undefined;
+      }
+      return handleRoutingTask(redirectionUrl, {
+        ...options,
+        reason: `${options.reason} (redirected from ${url})`,
+        redirected: true,
+      });
+    }
     // Decided before anything is announced: an elided push IS the traversal it
     // becomes, and the traversal will make its own announcements when the
     // browser answers — a before/after cycle here would be about a navigation
@@ -21556,6 +21854,7 @@ const setupBrowserIntegrationViaHistory = ({
       reason,
       navigationType, // "load", "reload", "replace", "push", "traverse"
       state,
+      redirected,
     } = options;
 
     // Where the entry being reached stands in this document's own stack —
@@ -21598,6 +21897,14 @@ const setupBrowserIntegrationViaHistory = ({
     } else {
       // traverse / reload: state comes from the history entry, no push/replace needed.
       markUrlAsVisited(url);
+      if (redirected) {
+        // The entry the browser is on names an address that only sends
+        // elsewhere — a cold load on it, or a back into it. Written over where
+        // it stands (the entry keeps its place in the stack, hence its state
+        // and the depth in it): pressing back must not walk into it again.
+        window.history.replaceState(state, null, url);
+        rememberEntryIsOfThisDocument();
+      }
       updateDocumentUrl(url);
       updateDocumentState(state);
     }
@@ -34602,7 +34909,7 @@ const describeRangeAsked = (rangeParams) => {
 };
 
 const resourceLifecycleManager = createResourceLifecycleManager();
-const debug$2 = (args) => {
+const debug$2 = (...args) => {
   {
     return;
   }
@@ -34667,6 +34974,7 @@ const resource = (
     DELETE_MANY,
   } = {},
 ) => {
+  const declarationSite = getDeclarationSite();
   if (idKey === undefined) {
     idKey = uniqueKeys.length === 0 ? "id" : uniqueKeys[0];
   }
@@ -34715,6 +35023,7 @@ const resource = (
   const createRestActionForRoot = createRestActionFactoryForRoot(name, {
     idKey,
     store,
+    declarationSite,
   });
   return createResource(name, {
     idKey,
@@ -34753,11 +35062,8 @@ const createResource = (
     paramScope,
     rerunOn,
     dependencies,
-  } = {},
+  },
 ) => {
-  if (idKey === undefined) {
-    idKey = uniqueKeys.length === 0 ? "id" : uniqueKeys[0];
-  }
   const params = paramScope.params;
   const stateFacade = {
     // public
@@ -34778,7 +35084,6 @@ const createResource = (
     store,
     addItemSetup,
   };
-  const lifecycleCtx = { onComplete: null };
 
   resourceLifecycleManager.registerResource(stateFacade, {
     rerunOn,
@@ -34786,7 +35091,7 @@ const createResource = (
     dependencies,
     uniqueKeys,
   });
-  lifecycleCtx.onComplete = (actionCompleted) => {
+  const onActionComplete = (actionCompleted) => {
     resourceLifecycleManager.onActionComplete(actionCompleted, {
       resourceScope: stateFacade,
     });
@@ -34823,6 +35128,7 @@ const createResource = (
     paramsToInject,
     { dependencies: withParamsDeps, rerunOn: withParamsRerunOn } = {},
   ) => {
+    const declarationSite = getDeclarationSite();
     if (!paramsToInject || Object.keys(paramsToInject).length === 0) {
       throw new Error(`resource(${name}).withParams() requires parameters`);
     }
@@ -34833,6 +35139,7 @@ const createResource = (
     const createRestActionWithParams = createRestActionFactoryForRoot(name, {
       idKey,
       store,
+      declarationSite,
     });
     return createResource(name, {
       idKey,
@@ -34885,40 +35192,37 @@ const createResource = (
       DELETE,
     } = {},
   ) => {
+    const declarationSite = getDeclarationSite();
     const childName = `${name}.${propertyName}`;
+    const childIdKey = childResource.idKey;
+    const childStore = childResource.store;
     addItemSetup((item) => {
-      const childIdKeyForSetup = childResource.idKey;
       const childItemIdSignal = signal();
       const updateChildItemId = (value) => {
         const currentChildItemId = childItemIdSignal.peek();
+        let childItemProps;
         if (isProps(value)) {
-          const childItem = childResource.store.upsert(value);
-          const childItemId = childItem[childIdKeyForSetup];
-          if (currentChildItemId === childItemId) {
-            return false;
-          }
-          childItemIdSignal.value = childItemId;
-          return true;
-        }
-        if (primitiveCanBeId(value)) {
-          const childItemProps = { [childIdKeyForSetup]: value };
-          const childItem = childResource.store.upsert(childItemProps);
-          const childItemId = childItem[childIdKeyForSetup];
-          if (currentChildItemId === childItemId) {
+          childItemProps = value;
+        } else if (primitiveCanBeId(value)) {
+          childItemProps = { [childIdKey]: value };
+        } else {
+          if (currentChildItemId === undefined) {
             return false;
           }
-          childItemIdSignal.value = childItemId;
+          childItemIdSignal.value = undefined;
           return true;
         }
-        if (currentChildItemId === undefined) {
+        const childItem = childStore.upsert(childItemProps);
+        const childItemId = childItem[childIdKey];
+        if (currentChildItemId === childItemId) {
           return false;
         }
-        childItemIdSignal.value = undefined;
+        childItemIdSignal.value = childItemId;
         return true;
       };
       updateChildItemId(item[propertyName]);
       const childItemSignal = computed(() =>
-        childResource.store.select(childItemIdSignal.value),
+        childStore.select(childItemIdSignal.value),
       );
       const childItemFacadeSignal = computed(() => {
         const childItem = childItemSignal.value;
@@ -34949,9 +35253,7 @@ const createResource = (
       );
     });
 
-    const childIdKey = childResource.idKey;
-    const childStore = childResource.store;
-    const createRestActionForOne = (verb, callback, { lifecycleCtx }) => {
+    const createRestActionForOne = (verb, callback, { onActionComplete }) => {
       const applyResultToValue =
         verb === "DELETE"
           ? (itemId) => {
@@ -34963,33 +35265,18 @@ const createResource = (
               });
               return childItemId;
             }
-          : // callback must return object with the following format:
-            // {
-            //   [idKey]: 123,
-            //   [propertyName]: {
-            //     [childIdKey]: 456, ...childProps
-            //   }
-            // }
-            // the following could happen too if there is no relationship
-            // {
-            //   [idKey]: 123,
-            //   [propertyName]: null
-            // }
+          : // GET/PUT contract (see .one() JSDoc): the parent object with the
+            // relationship nested inside, or null for no relationship.
             (result) => {
               const item = store.upsert(result);
               const childItem = item[propertyName];
-              const childItemId = childItem ? childItem[childIdKey] : undefined;
-              return childItemId;
+              return childItem ? childItem[childIdKey] : undefined;
             };
-
-      const callerInfo = getCallerInfo(null, 2);
-      const locationInfo =
-        callerInfo.file && callerInfo.line && callerInfo.column
-          ? `${callerInfo.file}:${callerInfo.line}:${callerInfo.column}`
-          : callerInfo.raw || "unknown location";
-      const originalActionName = `${name}.${verb}`;
-
-      const actionAffectingOneItem = createAction(callback, {
+      const throwInvalidResult = createInvalidResultThrower(
+        `${name}.${verb}`,
+        declarationSite,
+      );
+      return createAction(callback, {
         meta: {
           verb,
           isMany: false,
@@ -34997,35 +35284,30 @@ const createResource = (
         },
         name: `${name}.${verb}`,
         resultToValue: (result, action) => {
-          const actionLabel = action.name;
-
           if (verb === "DELETE") {
             if (!isProps(result) && !primitiveCanBeId(result)) {
-              throw new TypeError(
-                `${actionLabel} must return an object (that will be used to drop "${name}" resource), received ${result}.
-${originalActionName} source location: ${locationInfo}`,
+              throwInvalidResult(
+                action.name,
+                `an object (that will be used to drop "${name}" resource)`,
+                result,
               );
             }
-            return applyResultToValue(result);
-          }
-          if (!isProps(result)) {
-            throw new TypeError(
-              `${actionLabel} must return an object (that will be used to upsert "${name}" resource), received ${result}.
-   ${originalActionName} source location: ${locationInfo}`,
+          } else if (!isProps(result)) {
+            throwInvalidResult(
+              action.name,
+              `an object (that will be used to upsert "${name}" resource)`,
+              result,
             );
           }
           return applyResultToValue(result);
         },
         valueToData: (childItemId) => childStore.select(childItemId),
-        completeSideEffect: (actionCompleted) => {
-          lifecycleCtx.onComplete(actionCompleted);
-        },
+        completeSideEffect: onActionComplete,
       });
-      return actionAffectingOneItem;
     };
 
     return createResource(childName, {
-      idKey: childResource.idKey,
+      idKey: childIdKey,
       restCallbacks: {
         GET,
         PUT,
@@ -35082,49 +35364,21 @@ ${originalActionName} source location: ${locationInfo}`,
       DELETE_MANY,
     } = {},
   ) => {
+    const declarationSite = getDeclarationSite();
     const childStore = childResource.store;
     const childIdKey = childResource.idKey;
     const childName = `${name}.${propertyName}`;
     addItemSetup((item) => {
       const childItemIdArraySignal = signal([]);
-      const updateChildItemIdArray = (valueArray) => {
-        const currentIdArray = childItemIdArraySignal.peek();
-        if (!Array.isArray(valueArray)) {
-          if (currentIdArray.length === 0) return;
-          childItemIdArraySignal.value = [];
-          return;
-        }
-        let i = 0;
-        const idArray = [];
-        let modified = false;
-        while (i < valueArray.length) {
-          const value = valueArray[i];
-          const currentIdAtIndex = currentIdArray[idArray.length];
-          i++;
-          if (isProps(value)) {
-            const childItem = childResource.store.upsert(value);
-            const childItemId = childItem[childIdKey];
-            if (currentIdAtIndex !== childItemId) modified = true;
-            idArray.push(childItemId);
-            continue;
-          }
-          if (primitiveCanBeId(value)) {
-            const childItemProps = { [childIdKey]: value };
-            const childItem = childResource.store.upsert(childItemProps);
-            const childItemId = childItem[childIdKey];
-            if (currentIdAtIndex !== childItemId) modified = true;
-            idArray.push(childItemId);
-            continue;
-          }
-        }
-        if (modified || currentIdArray.length !== idArray.length) {
-          childItemIdArraySignal.value = idArray;
-        }
-      };
+      const updateChildItemIdArray = createChildIdArrayUpdater(
+        childStore,
+        childIdKey,
+        childItemIdArraySignal,
+      );
       updateChildItemIdArray(item[propertyName]);
       const childItemArraySignal = computed(() => {
         const idArray = childItemIdArraySignal.value;
-        const arr = childResource.store.selectAll(idArray);
+        const arr = childStore.selectAll(idArray);
         Object.defineProperty(arr, SYMBOL_OBJECT_SIGNAL, {
           value: childItemArraySignal,
           writable: false,
@@ -35137,23 +35391,27 @@ ${originalActionName} source location: ${locationInfo}`,
         get: () => childItemArraySignal.value,
         set: updateChildItemIdArray,
       });
-      syncIdArrayOnRename(
-        childResource.store,
-        childIdKey,
-        childItemIdArraySignal,
-      );
+      syncIdArrayOnRename(childStore, childIdKey, childItemIdArraySignal);
     });
     const createRestActionForMany = (
       verb,
       callback,
-      { isMany, lifecycleCtx },
+      { isMany, onActionComplete },
     ) => {
       if (!isMany) {
-        return createRestActionAffectingOneItem(verb, callback, lifecycleCtx);
+        return createRestActionAffectingOneItem(verb, callback, {
+          onActionComplete,
+        });
       }
-      return createRestActionAffectingManyItems(verb, callback, lifecycleCtx);
+      return createRestActionAffectingManyItems(verb, callback, {
+        onActionComplete,
+      });
     };
-    const createRestActionAffectingOneItem = (verb, callback, lifecycleCtx) => {
+    const createRestActionAffectingOneItem = (
+      verb,
+      callback,
+      { onActionComplete },
+    ) => {
       const applyResultToValue =
         verb === "DELETE"
           ? ([itemId, childItemId]) => {
@@ -35162,8 +35420,7 @@ ${originalActionName} source location: ${locationInfo}`,
               const childItemArrayWithoutThisOne = [];
               let found = false;
               for (const childItemCandidate of childItemArray) {
-                const childItemCandidateId = childItemCandidate[childIdKey];
-                if (childItemCandidateId === childItemId) {
+                if (childItemCandidate[childIdKey] === childItemId) {
                   found = true;
                 } else {
                   childItemArrayWithoutThisOne.push(childItemCandidate);
@@ -35178,162 +35435,127 @@ ${originalActionName} source location: ${locationInfo}`,
               return childItemId;
             }
           : (childData) => {
+              // an array is [property, value, props], used to rename the child id
               const childItem = Array.isArray(childData)
                 ? childStore.upsert(...childData)
                 : childStore.upsert(childData);
-              const childItemId = childItem[childIdKey];
-              return childItemId;
+              return childItem[childIdKey];
             };
-
-      const callerInfo = getCallerInfo(null, 2);
-      const locationInfo =
-        callerInfo.file && callerInfo.line && callerInfo.column
-          ? `${callerInfo.file}:${callerInfo.line}:${callerInfo.column}`
-          : callerInfo.raw || "unknown location";
-      const originalActionName = `${name}.${verb}`;
-
-      const actionAffectingOneItem = createAction(callback, {
+      const throwInvalidResult = createInvalidResultThrower(
+        `${name}.${verb}`,
+        declarationSite,
+      );
+      return createAction(callback, {
         meta: { verb, isMany: false, paramScope },
         name: `${name}.${verb}`,
         resultToValue: (result, action) => {
-          const actionLabel = action.name;
-
           if (verb === "DELETE") {
             if (!Array.isArray(result) || result.length !== 2) {
-              throw new TypeError(
-                `${actionLabel} must return an array [itemId, childItemId] (that will be used to remove relationship), received ${result}.
-${originalActionName} source location: ${locationInfo}`,
+              throwInvalidResult(
+                action.name,
+                `an array [itemId, childItemId] (that will be used to remove relationship)`,
+                result,
               );
             }
-            return applyResultToValue(result);
-          }
-          if (!isProps(result)) {
-            throw new TypeError(
-              `${actionLabel} must return an object (that will be used to upsert child item), received ${result}.
-${originalActionName} source location: ${locationInfo}`,
+          } else if (!isProps(result)) {
+            throwInvalidResult(
+              action.name,
+              `an object (that will be used to upsert child item)`,
+              result,
             );
           }
           return applyResultToValue(result);
         },
         valueToData: (childItemId) => childStore.select(childItemId),
-        completeSideEffect: (actionCompleted) => {
-          lifecycleCtx.onComplete(actionCompleted);
-        },
+        completeSideEffect: onActionComplete,
       });
-      return actionAffectingOneItem;
     };
     const createRestActionAffectingManyItems = (
       verb,
       callback,
-      lifecycleCtx,
+      { onActionComplete },
     ) => {
       const applyResultToValue =
         verb === "GET"
           ? (result) => {
-              // callback must return object with the following format:
-              // {
-              //   [idKey]: 123,
-              //   [propertyName]: [
-              //      { [childIdKey]: 456, ...childProps },
-              //      { [childIdKey]: 789, ...childProps },
-              //      ...
-              //   ]
-              // }
-              // the array can be empty
+              // GET_MANY contract (see .many() JSDoc): the parent object with
+              // the child array nested inside; the array replaces the relationship.
               const item = store.upsert(result);
               const childItemArray = item[propertyName];
-              const childItemIdArray = childItemArray.map(
-                (childItem) => childItem[childIdKey],
-              );
-              return childItemIdArray;
+              return childItemArray.map((childItem) => childItem[childIdKey]);
             }
           : verb === "DELETE"
             ? ([itemIdOrMutableId, childItemIdOrMutableIdArray]) => {
                 const item = store.select(itemIdOrMutableId);
                 const childItemArray = item[propertyName];
-                const deletedChildItemIdArray = [];
-                const childItemArrayWithoutThoose = [];
-                let someFound = false;
-                const deletedChildItemArray = childStore.select(
-                  childItemIdOrMutableIdArray,
+                const deletedChildItemSet = new Set(
+                  childStore.selectAll(childItemIdOrMutableIdArray),
                 );
+                const deletedChildItemIdArray = [];
+                const childItemArrayWithoutThose = [];
                 for (const childItemCandidate of childItemArray) {
-                  if (deletedChildItemArray.includes(childItemCandidate)) {
-                    someFound = true;
+                  if (deletedChildItemSet.has(childItemCandidate)) {
                     deletedChildItemIdArray.push(
                       childItemCandidate[childIdKey],
                     );
                   } else {
-                    childItemArrayWithoutThoose.push(childItemCandidate);
+                    childItemArrayWithoutThose.push(childItemCandidate);
                   }
                 }
-                if (someFound) {
+                if (deletedChildItemIdArray.length > 0) {
                   store.upsert({
                     [idKey]: item[idKey],
-                    [propertyName]: childItemArrayWithoutThoose,
+                    [propertyName]: childItemArrayWithoutThose,
                   });
                 }
                 return deletedChildItemIdArray;
               }
             : (childDataArray) => {
                 const childItemArray = childStore.upsert(childDataArray);
-                const childItemIdArray = childItemArray.map(
-                  (childItem) => childItem[childIdKey],
-                );
-                return childItemIdArray;
+                return childItemArray.map((childItem) => childItem[childIdKey]);
               };
-
-      const callerInfo = getCallerInfo(null, 2);
-      const locationInfo =
-        callerInfo.file && callerInfo.line && callerInfo.column
-          ? `${callerInfo.file}:${callerInfo.line}:${callerInfo.column}`
-          : callerInfo.raw || "unknown location";
-      const originalActionName = `${name}.${verb}[many]`;
-
-      const actionAffectingManyItem = createAction(callback, {
+      const throwInvalidResult = createInvalidResultThrower(
+        `${name}.${verb}[many]`,
+        declarationSite,
+      );
+      return createAction(callback, {
         meta: { verb, isMany: true, paramScope },
         name: `${name}.${verb}[many]`,
         dataDefault: [],
         resultToValue: (result, action) => {
-          const actionLabel = action.name;
-
           if (verb === "GET") {
             if (!isProps(result)) {
-              throw new TypeError(
-                `${actionLabel} must return an object (that will be used to upsert "${name}" resource with many relationships), received ${result}.
-${originalActionName} source location: ${locationInfo}`,
+              throwInvalidResult(
+                action.name,
+                `an object (that will be used to upsert "${name}" resource with many relationships)`,
+                result,
               );
             }
-            return applyResultToValue(result);
-          }
-          if (verb === "DELETE") {
+          } else if (verb === "DELETE") {
             if (
               !Array.isArray(result) ||
               result.length !== 2 ||
               !Array.isArray(result[1])
             ) {
-              throw new TypeError(
-                `${actionLabel} must return an array [itemId, childItemIdArray] (that will be used to remove relationships), received ${result}.
-${originalActionName} source location: ${locationInfo}`,
+              throwInvalidResult(
+                action.name,
+                `an array [itemId, childItemIdArray] (that will be used to remove relationships)`,
+                result,
               );
             }
-            return applyResultToValue(result);
-          }
-          if (!Array.isArray(result)) {
-            throw new TypeError(
-              `${actionLabel} must return an array of objects (that will be used to upsert child items), received ${result}.
-${originalActionName} source location: ${locationInfo}`,
+          } else if (!Array.isArray(result)) {
+            throwInvalidResult(
+              action.name,
+              `an array of objects (that will be used to upsert child items)`,
+              result,
             );
           }
           return applyResultToValue(result);
         },
         valueToData: (childItemIdArray) =>
           childStore.selectAll(childItemIdArray),
-        completeSideEffect: (actionCompleted) => {
-          lifecycleCtx.onComplete(actionCompleted);
-        },
+        completeSideEffect: onActionComplete,
       });
-      return actionAffectingManyItem;
     };
 
     return createResource(childName, {
@@ -35398,26 +35620,20 @@ ${originalActionName} source location: ${locationInfo}`,
   ) => {
     const childName = `${name}.${propertyName}`;
 
-    // setupCallbackSet: callbacks added by chained .one()/.many()
-    // Applied to each per-scope child item object when it is first created.
-    const childItemSetupCallbackSet = new Set();
-    const childAddItemSetup = (callback) =>
-      childItemSetupCallbackSet.add(callback);
-    const scopedItemMap = new Map(); // ownerId → stable child item object
-    const scopedSignalMap = new Map(); // ownerId → signal<childItem | null>
+    // Callbacks added by chained .one()/.many() on the child resource,
+    // applied to each per-owner child object when it is first created.
+    const childSetupCallbackSet = new Set();
+    const childAddItemSetup = (callback) => childSetupCallbackSet.add(callback);
+    const applyPropsMap = new Map(); // ownerId → applyProps(props | null)
     addItemSetup((ownerItem) => {
       const ownerId = ownerItem[idKey];
-      // Create a stable child item — mutated in place via applyProps.
-      // Reactive getters/setters from chained .one() etc. are defined on this object now
-      // so they survive across multiple prop updates.
+      // A stable child object, mutated in place: reactive getters/setters from
+      // chained .one() etc. are defined on it once and survive prop updates.
       const childItem = {};
-      for (const childSetup of childItemSetupCallbackSet) {
+      for (const childSetup of childSetupCallbackSet) {
         childSetup(childItem);
       }
-      scopedItemMap.set(ownerId, childItem);
       const childSignal = signal(null);
-      scopedSignalMap.set(ownerId, childSignal);
-
       const applyProps = (props) => {
         if (!props) {
           childSignal.value = null;
@@ -35431,6 +35647,7 @@ ${originalActionName} source location: ${locationInfo}`,
           childSignal.value = childItem; // first activation: null → childItem
         }
       };
+      applyPropsMap.set(ownerId, applyProps);
 
       applyProps(ownerItem[propertyName]);
 
@@ -35439,9 +35656,13 @@ ${originalActionName} source location: ${locationInfo}`,
         set: applyProps,
       });
     });
-    const createRestActionForScopedOne = (verb, callback, { lifecycleCtx }) => {
+    const createRestActionForScopedOne = (
+      verb,
+      callback,
+      { onActionComplete },
+    ) => {
       const childActionName = `${childName}.${verb}`;
-      const restAction = createAction(callback, {
+      return createAction(callback, {
         name: childActionName,
         meta: { verb, isMany: false, paramScope },
         resultToValue: (result) => {
@@ -35458,33 +35679,20 @@ ${originalActionName} source location: ${locationInfo}`,
             uniqueKeys,
             childActionName,
           );
-          const childItem = scopedItemMap.get(ownerId);
-          if (!childItem) {
+          const applyProps = applyPropsMap.get(ownerId);
+          if (!applyProps) {
             throw new Error(
               `${childActionName}: no item found for scope id "${ownerId}"`,
             );
           }
-          const childSignal = scopedSignalMap.get(ownerId);
-          if (props) {
-            for (const [key, value] of Object.entries(props)) {
-              childItem[key] = value;
-            }
-            if (childSignal.peek() !== childItem) {
-              childSignal.value = childItem;
-            }
-          } else {
-            childSignal.value = null;
-          }
+          applyProps(props);
           return [ownerId, props];
         },
-        completeSideEffect: (actionCompleted) => {
-          lifecycleCtx.onComplete(actionCompleted);
-        },
+        completeSideEffect: onActionComplete,
       });
-      return restAction;
     };
 
-    const childResource = createResource(childName, {
+    return createResource(childName, {
       idKey: childIdKey,
       restCallbacks: {
         GET,
@@ -35500,7 +35708,6 @@ ${originalActionName} source location: ${locationInfo}`,
       rerunOn: scopedOneRerunOn ?? rerunOn,
       dependencies: scopedOneDependencies ?? dependencies,
     });
-    return childResource;
   };
 
   /**
@@ -35554,108 +35761,76 @@ ${originalActionName} source location: ${locationInfo}`,
   ) => {
     const childName = `${name}.${propertyName}`;
 
-    // setupCallbackSet: callbacks added by chained .one()/.many()
-    // Applied to each child item when it is created in a per-scope store.
+    // Callbacks added by chained .one()/.many() on the child resource,
+    // applied to each child item created in a per-owner store.
     const childSetupCallbackSet = new Set();
     const childAddItemSetup = (callback) => childSetupCallbackSet.add(callback);
-    const scopedStoreMap = new Map(); // ownerId → childStore
-    const scopedIdArraySignalMap = new Map(); // ownerId → childItemIdArraySignal
+    // ownerKey (id or any uniqueKey value) → { childStore, idArraySignal }
+    // One owner can be registered under several keys, all pointing to the same scope.
+    const scopeMap = new Map();
+    const createScope = (ownerKey) => {
+      const childStore = arraySignalStore([], childIdKey, {
+        name: `${childName}#${ownerKey} store`,
+        createItem: (props) => {
+          const childItem = {};
+          Object.assign(childItem, props);
+          for (const childSetup of childSetupCallbackSet) {
+            childSetup(childItem);
+          }
+          return childItem;
+        },
+      });
+      const scope = { childStore, idArraySignal: signal([]) };
+      scopeMap.set(ownerKey, scope);
+      return scope;
+    };
     addItemSetup((item) => {
       const ownerId = item[idKey];
 
-      // Reuse an existing scoped store if one was already created via a uniqueKey
-      // (e.g. rows were fetched by tablename before the full table was loaded).
-      let childStore = scopedStoreMap.get(ownerId);
-      let childItemIdArraySignal = scopedIdArraySignalMap.get(ownerId);
-      if (!childStore) {
+      // Reuse an existing scope if one was already created under a uniqueKey
+      // value (e.g. rows were fetched by tablename before the full table was loaded).
+      let scope = scopeMap.get(ownerId);
+      if (!scope) {
         for (const uniqueKey of uniqueKeys) {
           const uniqueKeyValue = item[uniqueKey];
-          if (uniqueKeyValue !== undefined) {
-            const existing = scopedStoreMap.get(uniqueKeyValue);
-            if (existing) {
-              childStore = existing;
-              childItemIdArraySignal =
-                scopedIdArraySignalMap.get(uniqueKeyValue);
-              break;
-            }
+          if (uniqueKeyValue !== undefined && scopeMap.has(uniqueKeyValue)) {
+            scope = scopeMap.get(uniqueKeyValue);
+            break;
           }
         }
       }
-      if (!childStore) {
-        childStore = arraySignalStore([], childIdKey, {
-          name: `${childName}#${ownerId} store`,
-          createItem: (props) => {
-            const childItem = {};
-            Object.assign(childItem, props);
-            for (const childSetup of childSetupCallbackSet) {
-              childSetup(childItem);
-            }
-            return childItem;
-          },
-        });
-        childItemIdArraySignal = signal([]);
+      if (!scope) {
+        scope = createScope(ownerId);
       }
-      scopedStoreMap.set(ownerId, childStore);
-      // Also register by each uniqueKey value so that resolveOwnerId works
-      // when a callback returns { [uniqueKey]: value } before the full item is loaded.
+      // Register the scope under the id and every uniqueKey value so that
+      // resolveOwnerId can address it whichever key a callback returns.
+      scopeMap.set(ownerId, scope);
       for (const uniqueKey of uniqueKeys) {
         const uniqueKeyValue = item[uniqueKey];
         if (uniqueKeyValue !== undefined) {
-          scopedStoreMap.set(uniqueKeyValue, childStore);
+          scopeMap.set(uniqueKeyValue, scope);
         }
       }
 
-      scopedIdArraySignalMap.set(ownerId, childItemIdArraySignal);
-      for (const uniqueKey of uniqueKeys) {
-        const uniqueKeyValue = item[uniqueKey];
-        if (uniqueKeyValue !== undefined) {
-          scopedIdArraySignalMap.set(uniqueKeyValue, childItemIdArraySignal);
-        }
+      const { childStore, idArraySignal } = scope;
+      const updateChildItemIdArray = createChildIdArrayUpdater(
+        childStore,
+        childIdKey,
+        idArraySignal,
+      );
+      // The parent may not carry the property at all (e.g. created by a POST
+      // that does not embed it): leave the collection of a reused scope
+      // untouched — children may have been fetched by uniqueKey before the
+      // parent was loaded. Only an explicit value replaces the collection.
+      if (item[propertyName] !== undefined) {
+        updateChildItemIdArray(item[propertyName]);
       }
 
-      const updateChildItemIdArray = (valueArray) => {
-        const currentIdArray = childItemIdArraySignal.peek();
-        if (!Array.isArray(valueArray)) {
-          if (currentIdArray.length === 0) return;
-          childItemIdArraySignal.value = [];
-          return;
-        }
-        let i = 0;
-        const idArray = [];
-        let modified = false;
-        while (i < valueArray.length) {
-          const value = valueArray[i];
-          const currentIdAtIndex = currentIdArray[idArray.length];
-          i++;
-          if (isProps(value)) {
-            const childItem = childStore.upsert(value);
-            const childItemId = childItem[childIdKey];
-            if (currentIdAtIndex !== childItemId) modified = true;
-            idArray.push(childItemId);
-            continue;
-          }
-          if (primitiveCanBeId(value)) {
-            const childItemProps = { [childIdKey]: value };
-            const childItem = childStore.upsert(childItemProps);
-            const childItemId = childItem[childIdKey];
-            if (currentIdAtIndex !== childItemId) modified = true;
-            idArray.push(childItemId);
-            continue;
-          }
-        }
-        if (modified || currentIdArray.length !== idArray.length) {
-          childItemIdArraySignal.value = idArray;
-        }
-      };
-
-      updateChildItemIdArray(item[propertyName]);
-
       // When an id is renamed (PUT/PATCH changes the idKey), patch the id array.
-      syncIdArrayOnRename(childStore, childIdKey, childItemIdArraySignal);
+      syncIdArrayOnRename(childStore, childIdKey, idArraySignal);
 
       const childItemArraySignal = computed(() => {
-        const childItemIdArray = childItemIdArraySignal.value;
-        const childItemArray = childStore.selectAll(childItemIdArray);
+        const childItemArray = childStore.selectAll(idArraySignal.value);
         Object.defineProperty(childItemArray, SYMBOL_OBJECT_SIGNAL, {
           value: childItemArraySignal,
           writable: false,
@@ -35673,13 +35848,10 @@ ${originalActionName} source location: ${locationInfo}`,
     const createRestActionForScopedMany = (
       verb,
       callback,
-      { isMany, lifecycleCtx },
+      { isMany, onActionComplete },
     ) => {
-      if (!callback) {
-        return undefined;
-      }
       const childActionName = `${childName}.${verb}`;
-      const childAction = createAction(callback, {
+      return createAction(callback, {
         name: childActionName,
         meta: { verb, isMany, paramScope },
         resultToValue: (result) => {
@@ -35696,48 +35868,33 @@ ${originalActionName} source location: ${locationInfo}`,
             uniqueKeys,
             childActionName,
           );
-          let childStore = scopedStoreMap.get(ownerId);
-          if (!childStore) {
-            // Owner not yet in store — lazily create scoped store so actions can run
-            // before the parent item has been fully loaded (e.g. rows fetched before table).
-            childStore = arraySignalStore([], childIdKey, {
-              name: `${childName}#${ownerId} store`,
-              createItem: (props) => {
-                const childItem = {};
-                Object.assign(childItem, props);
-                for (const childSetup of childSetupCallbackSet) {
-                  childSetup(childItem);
-                }
-                return childItem;
-              },
-            });
-            scopedStoreMap.set(ownerId, childStore);
-            const newIdArraySignal = signal([]);
-            scopedIdArraySignalMap.set(ownerId, newIdArraySignal);
-          }
-          const childItemIdArraySignal = scopedIdArraySignalMap.get(ownerId);
+          // Owner not in store yet: create the scope so actions can run before
+          // the parent item has been loaded (e.g. rows fetched before their table).
+          const scope = scopeMap.get(ownerId) || createScope(ownerId);
+          const { childStore, idArraySignal } = scope;
 
           if (verb === "DELETE") {
             if (isMany) {
               const idArray = childStore.drop(rest[0]);
               const toRemoveSet = new Set(idArray);
-              childItemIdArraySignal.value = childItemIdArraySignal
+              idArraySignal.value = idArraySignal
                 .peek()
                 .filter((id) => !toRemoveSet.has(id));
               return [ownerId, idArray];
             }
             const childId = childStore.drop(rest[0]);
-            childItemIdArraySignal.value = childItemIdArraySignal
+            idArraySignal.value = idArraySignal
               .peek()
               .filter((id) => id !== childId);
             return [ownerId, childId];
           }
 
           if (isMany) {
-            // GET_MANY, POST_MANY, PUT_MANY etc: rest[0] is the array of items
+            // GET_MANY, POST_MANY, PUT_MANY etc: rest[0] is the array of items,
+            // and it replaces the whole collection.
             const itemArray = childStore.upsert(rest[0]);
-            const idArray = itemArray.map((i) => i[childIdKey]);
-            childItemIdArraySignal.value = idArray;
+            const idArray = itemArray.map((childItem) => childItem[childIdKey]);
+            idArraySignal.value = idArray;
             return [ownerId, idArray];
           }
 
@@ -35749,25 +35906,23 @@ ${originalActionName} source location: ${locationInfo}`,
           return [ownerId, childItem[childIdKey]];
         },
         valueToData: (value) => {
-          if (!value) return isMany ? [] : undefined;
+          if (!value) {
+            return isMany ? [] : undefined;
+          }
           const [ownerId, idOrIdArray] = value;
-          const childStore = scopedStoreMap.get(ownerId);
-          if (!childStore) return isMany ? [] : undefined;
-          if (isMany) return childStore.selectAll(idOrIdArray);
-          return childStore.select(idOrIdArray);
-        },
-        completeSideEffect: (actionCompleted) => {
-          lifecycleCtx.onComplete(actionCompleted);
+          const scope = scopeMap.get(ownerId);
+          if (!scope) {
+            return isMany ? [] : undefined;
+          }
+          if (isMany) {
+            return scope.childStore.selectAll(idOrIdArray);
+          }
+          return scope.childStore.select(idOrIdArray);
         },
+        completeSideEffect: onActionComplete,
       });
-      return childAction;
     };
 
-    // When a child (scopedMany) item is mutated via POST, the parent GET must
-    // re-fetch because the parent embeds the child array and we cannot know the
-    // new ordering without asking the backend again.
-    // (scopedOne does NOT need this: the mutation result contains the updated
-    // item directly, so no parent re-fetch is necessary.)
     const childResource = createResource(childName, {
       idKey: childIdKey,
       restCallbacks: {
@@ -35789,19 +35944,23 @@ ${originalActionName} source location: ${locationInfo}`,
       rerunOn: scopedManyRerunOn ?? rerunOn,
       dependencies: scopedManyDependencies ?? dependencies,
     });
-    // Register: when childResource fires, rerun parent (stateFacade) GETs.
+    // When a scoped child collection is mutated (POST etc.), the parent GET must
+    // re-fetch: the parent embeds the child array and only the backend knows the
+    // new ordering. (scopedOne does not need this: the mutation result contains
+    // the updated object directly.)
     resourceLifecycleManager.addDependency(
       childResource,
       stateFacade,
       propertyName,
     );
-    childResource.getChildStore = (ownerKey) => scopedStoreMap.get(ownerKey);
+    childResource.getChildStore = (ownerKey) =>
+      scopeMap.get(ownerKey)?.childStore;
     return childResource;
   };
 
-  // expose rest actions on the stateFacade
+  // expose one action (or range reader) per provided rest callback
   for (const [restCallbackKey, restCallback] of Object.entries(restCallbacks)) {
-    if (restCallback === undefined) {
+    if (!restCallback) {
       continue;
     }
     if (restCallbackKey === "GET_RANGE") {
@@ -35823,25 +35982,16 @@ ${originalActionName} source location: ${locationInfo}`,
     const verb = isMany
       ? restCallbackKey.replace("_MANY", "")
       : restCallbackKey;
-    const restAction = createRestAction(verb, restCallback, {
+    let restAction = createRestAction(verb, restCallback, {
       isMany,
-      lifecycleCtx,
+      onActionComplete,
       paramScope,
     });
-    if (!restAction) {
-      console.error("no action returned (here to see when it happens)");
-      continue;
-    }
-    let actionToRegister;
     if (params) {
-      const restActionBound = restAction.bindParams(params);
-      stateFacade[restCallbackKey] = restActionBound;
-      actionToRegister = restActionBound;
-    } else {
-      stateFacade[restCallbackKey] = restAction;
-      actionToRegister = restAction;
+      restAction = restAction.bindParams(params);
     }
-    resourceLifecycleManager.registerAction(stateFacade, actionToRegister);
+    stateFacade[restCallbackKey] = restAction;
+    resourceLifecycleManager.registerAction(stateFacade, restAction);
   }
 
   return stateFacade;
@@ -35852,76 +36002,64 @@ const createRestActionFactoryForRoot = (
   {
     idKey,
     store, // see array_signal_store.js
+    declarationSite,
   },
 ) => {
   const createActionForRoot = (
     verb,
     restCallback,
-    { isMany, lifecycleCtx, paramScope },
+    { isMany, onActionComplete, paramScope },
   ) => {
     if (!isMany) {
       return createActionAffectingOneItem(verb, restCallback, {
-        lifecycleCtx,
+        onActionComplete,
         paramScope,
       });
     }
     return createActionAffectingManyItems(verb, restCallback, {
-      lifecycleCtx,
+      onActionComplete,
       paramScope,
     });
   };
   const createActionAffectingOneItem = (
     verb,
     callback,
-    { lifecycleCtx, paramScope },
+    { onActionComplete, paramScope },
   ) => {
     const applyResultToValue =
       verb === "DELETE"
-        ? (itemIdOrItemProps) => {
-            const itemId = store.drop(itemIdOrItemProps);
-            return itemId;
-          }
+        ? (itemIdOrItemProps) => store.drop(itemIdOrItemProps)
         : (result) => {
-            let item;
-            if (Array.isArray(result)) {
-              // the callback is returning something like [property, value, props]
-              // this is to support a case like:
-              // store.upsert("name", "currentName", { name: "newName" })
-              // where we want to update the idKey of an item
-              item = store.upsert(...result);
-            } else {
-              item = store.upsert(result);
-            }
-            const itemId = item[idKey];
-            return itemId;
+            // An array result is [property, value, props] — used to rename the
+            // idKey of an item: store.upsert("name", "currentName", { name: "newName" })
+            const item = Array.isArray(result)
+              ? store.upsert(...result)
+              : store.upsert(result);
+            return item[idKey];
           };
-
-    const callerInfo = getCallerInfo(null, 2);
-    // Provide more fallback options for better debugging
-    const locationInfo =
-      callerInfo.file && callerInfo.line && callerInfo.column
-        ? `${callerInfo.file}:${callerInfo.line}:${callerInfo.column}`
-        : callerInfo.raw || "unknown location";
-    const originalActionName = `${name}.${verb}`;
-    const actionAffectingOneItem = createAction(callback, {
+    const throwInvalidResult = createInvalidResultThrower(
+      `${name}.${verb}`,
+      declarationSite,
+    );
+    return createAction(callback, {
       name: `${name}.${verb}`,
       meta: { verb, isMany: false, paramScope },
       resultToValue: (result, action) => {
-        const actionLabel = action.name;
-
         if (verb === "DELETE") {
           if (!isProps(result) && !primitiveCanBeId(result)) {
-            throw new TypeError(
-              `${actionLabel} must return an object (that will be used to drop "${name}" resource), received ${result}.
-${originalActionName} source location: ${locationInfo}`,
+            throwInvalidResult(
+              action.name,
+              `an object (that will be used to drop "${name}" resource)`,
+              result,
             );
           }
           return applyResultToValue(result);
         }
         if (!isProps(result)) {
-          throw new TypeError(
-            `${actionLabel} must return an object (that will be used to upsert "${name}" resource), received ${result}.
-${originalActionName} source location: ${locationInfo}`,
+          throwInvalidResult(
+            action.name,
+            `an object (that will be used to upsert "${name}" resource)`,
+            result,
           );
         }
         // Track which top-level properties the GET response contained so that
@@ -35932,40 +36070,30 @@ ${originalActionName} source location: ${locationInfo}`,
         return applyResultToValue(result);
       },
       valueToData: (itemId) => store.select(itemId),
-      completeSideEffect: (actionCompleted) => {
-        lifecycleCtx.onComplete(actionCompleted);
-      },
+      completeSideEffect: onActionComplete,
     });
-    return actionAffectingOneItem;
   };
   const createActionAffectingManyItems = (
     verb,
     callback,
-    { lifecycleCtx, paramScope },
+    { onActionComplete, paramScope },
   ) => {
     const applyResultToValue =
       verb === "DELETE"
-        ? (idOrMutableIdArray) => {
-            const idArray = store.drop(idOrMutableIdArray);
-            return idArray;
-          }
+        ? (idOrMutableIdArray) => store.drop(idOrMutableIdArray)
         : (dataArray) => {
             const itemArray = store.upsert(dataArray);
-            const idArray = itemArray.map((item) => item[idKey]);
-            return idArray;
+            return itemArray.map((item) => item[idKey]);
           };
 
-    const actionAffectingManyItems = createAction(callback, {
+    return createAction(callback, {
       meta: { verb, isMany: true, paramScope },
       name: `${name}.${verb}_MANY`,
       dataDefault: [],
       resultToValue: applyResultToValue,
-      valueToData: (idArray) => {
-        const items = store.selectAll(idArray);
-        return items;
-      },
+      valueToData: (idArray) => store.selectAll(idArray),
       completeSideEffect: (actionCompleted) => {
-        lifecycleCtx.onComplete(actionCompleted);
+        onActionComplete(actionCompleted);
         if (
           verb === "DELETE" ||
           actionCompleted.valueSignal.peek().length === 0
@@ -35979,12 +36107,70 @@ ${originalActionName} source location: ${locationInfo}`,
         return syncIdArrayOnRename(store, idKey, actionCompleted.valueSignal);
       },
     });
-    return actionAffectingManyItems;
   };
 
   return createActionForRoot;
 };
 
+// Captures the "file:line:column" of the user code that invoked the public
+// function (resource(), .one(), .many(), withParams, …), so invalid-result
+// errors can point at where the callbacks were declared, not at this file.
+// Must be called directly from the public function: the stack offset accounts
+// for exactly two frames (getCallerInfo → getDeclarationSite → public fn → user code).
+const getDeclarationSite = () => {
+  const callerInfo = getCallerInfo(null, 1);
+  if (callerInfo.file && callerInfo.line && callerInfo.column) {
+    return `${callerInfo.file}:${callerInfo.line}:${callerInfo.column}`;
+  }
+  return callerInfo.raw || "unknown location";
+};
+
+const createInvalidResultThrower = (originalActionName, declarationSite) => {
+  return (actionLabel, expected, result) => {
+    throw new TypeError(
+      `${actionLabel} must return ${expected}, received ${result}.
+${originalActionName} source location: ${declarationSite}`,
+    );
+  };
+};
+
+// Shared by .many() and .scopedMany(): converts a raw relationship value (an
+// array of child props/ids, or anything else meaning "empty") into an array of
+// child ids, upserting each entry into the child store. The id array signal is
+// only touched when the resulting ids actually differ.
+const createChildIdArrayUpdater = (childStore, childIdKey, idArraySignal) => {
+  return (valueArray) => {
+    const currentIdArray = idArraySignal.peek();
+    if (!Array.isArray(valueArray)) {
+      if (currentIdArray.length > 0) {
+        idArraySignal.value = [];
+      }
+      return;
+    }
+    const idArray = [];
+    let modified = false;
+    for (const value of valueArray) {
+      let childItemProps;
+      if (isProps(value)) {
+        childItemProps = value;
+      } else if (primitiveCanBeId(value)) {
+        childItemProps = { [childIdKey]: value };
+      } else {
+        continue;
+      }
+      const childItem = childStore.upsert(childItemProps);
+      const childItemId = childItem[childIdKey];
+      if (currentIdArray[idArray.length] !== childItemId) {
+        modified = true;
+      }
+      idArray.push(childItemId);
+    }
+    if (modified || currentIdArray.length !== idArray.length) {
+      idArraySignal.value = idArray;
+    }
+  };
+};
+
 const syncIdArrayOnRename = (store, idKey, idArraySignal) => {
   return store.observeProperties((mutations) => {
     const idArray = idArraySignal.peek();
@@ -36044,7 +36230,7 @@ const resolveOwnerId = (rawOwnerId, store, idKey, uniqueKeys, actionName) => {
       return item[idKey];
     }
     throw new TypeError(
-      `${actionName}: the first element of the returned array is { ${propName}: "${propValue}" } but "${propName}" is neither the idKey ("${idKey}") nor a declared uniqueKey (${uniqueKeys.length ? uniqueKeys.join(", ") : "none"}). 
+      `${actionName}: the first element of the returned array is { ${propName}: "${propValue}" } but "${propName}" is neither the idKey ("${idKey}") nor a declared uniqueKey (${uniqueKeys.length ? uniqueKeys.join(", ") : "none"}).
 Return a primitive id or a single-property object whose key is the idKey or a uniqueKey.`,
     );
   }
@@ -36053,7 +36239,7 @@ Return a primitive id or a single-property object whose key is the idKey or a un
   if (idKey in rawOwnerId) {
     const resolvedId = rawOwnerId[idKey];
     console.warn(
-      `${actionName}: the first element of the returned array is an object with multiple properties. 
+      `${actionName}: the first element of the returned array is an object with multiple properties.
 Only "${idKey}" is needed. Consider returning a primitive id or { ${idKey}: value } instead.`,
     );
     return resolvedId;
@@ -36065,8 +36251,10 @@ Received an object with keys: ${keys.join(", ")}.`,
   );
 };
 
-/** so that when a tracked property changes
- * on an item the corresponding signal is updated automatically.
+/**
+ * Keeps external signals in sync with properties of the resource's store items:
+ * when a tracked property changes on an item, the corresponding signal is
+ * updated automatically.
  *
  * Since signals are typically connected to route parameters via the route template
  * syntax, this keeps the URL in sync when a store item's mutable key is renamed.