@jsenv/navi 0.29.98 → 0.29.100

package/dist/jsenv_navi.js

@@ -11938,6 +11938,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 +12009,7 @@ const getActionDispatcher = () => dispatchActions;
 const rerunActions = async (actionSet, options) => {
   return dispatchActions({
     rerunSet: actionSet,
-    reason: "rerunActions was calle",
+    reason: "rerunActions was called",
     ...options,
   });
 };
@@ -11995,7 +12028,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 +12042,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 +12062,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 +12401,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 +12448,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 +12461,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 +12494,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 +12520,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 +12534,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 +12555,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 +12573,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 +12626,6 @@ const createAction = (callback, rootOptions = {}) => {
       return childAction;
     };
 
-    // ✅ Implement matchAllSelfOrDescendant
     const matchAllSelfOrDescendant = (predicate, { includeProxies } = {}) => {
       const matches = [];
 
@@ -12648,32 +12660,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 +12706,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 +12734,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 +12749,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 +12776,6 @@ const createAction = (callback, rootOptions = {}) => {
       });
     }
 
-    // Propriétés privées
     {
       const ui = {
         renderLoaded: null,
@@ -13043,8 +13054,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 +13149,7 @@ const createActionProxyFromSignal = (
       currentAction = actionTarget;
       currentActionPrivateProperties = getActionPrivateProperties(actionTarget);
     }
+
     actionTargetPreviousWeakRef = actionTarget
       ? new WeakRef(actionTarget)
       : null;
@@ -13163,25 +13175,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 +13393,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 +13414,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 +13445,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 +13461,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);
   }
@@ -34602,7 +34616,7 @@ const describeRangeAsked = (rangeParams) => {
 };
 
 const resourceLifecycleManager = createResourceLifecycleManager();
-const debug$2 = (args) => {
+const debug$2 = (...args) => {
   {
     return;
   }
@@ -34667,6 +34681,7 @@ const resource = (
     DELETE_MANY,
   } = {},
 ) => {
+  const declarationSite = getDeclarationSite();
   if (idKey === undefined) {
     idKey = uniqueKeys.length === 0 ? "id" : uniqueKeys[0];
   }
@@ -34715,6 +34730,7 @@ const resource = (
   const createRestActionForRoot = createRestActionFactoryForRoot(name, {
     idKey,
     store,
+    declarationSite,
   });
   return createResource(name, {
     idKey,
@@ -34753,11 +34769,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 +34791,6 @@ const createResource = (
     store,
     addItemSetup,
   };
-  const lifecycleCtx = { onComplete: null };
 
   resourceLifecycleManager.registerResource(stateFacade, {
     rerunOn,
@@ -34786,7 +34798,7 @@ const createResource = (
     dependencies,
     uniqueKeys,
   });
-  lifecycleCtx.onComplete = (actionCompleted) => {
+  const onActionComplete = (actionCompleted) => {
     resourceLifecycleManager.onActionComplete(actionCompleted, {
       resourceScope: stateFacade,
     });
@@ -34823,6 +34835,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 +34846,7 @@ const createResource = (
     const createRestActionWithParams = createRestActionFactoryForRoot(name, {
       idKey,
       store,
+      declarationSite,
     });
     return createResource(name, {
       idKey,
@@ -34885,40 +34899,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 +34960,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 +34972,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 +34991,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 +35071,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 +35098,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 +35127,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 +35142,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 +35327,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 +35354,7 @@ ${originalActionName} source location: ${locationInfo}`,
           childSignal.value = childItem; // first activation: null → childItem
         }
       };
+      applyPropsMap.set(ownerId, applyProps);
 
       applyProps(ownerItem[propertyName]);
 
@@ -35439,9 +35363,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 +35386,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 +35415,6 @@ ${originalActionName} source location: ${locationInfo}`,
       rerunOn: scopedOneRerunOn ?? rerunOn,
       dependencies: scopedOneDependencies ?? dependencies,
     });
-    return childResource;
   };
 
   /**
@@ -35554,108 +35468,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 +35555,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 +35575,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 +35613,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 +35651,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 +35689,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 +35709,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 +35777,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 +35814,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 +35937,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 +35946,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 +35958,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.