feat(data_store): finalize V3 cascading lookup with limit override

- Update GET /v3/data_store/code/{code} to support 'limit' query parameter.
- Refactor return logic: returns single object if limit=1, otherwise returns a list.
- Clean up formatting in GUIDE__V3_FRONTEND_API.md and sync to agents_sync.
- Finalize unified E2E test script: tests/e2e/test_e2e_v3_data_store_lookup.py.

app/routers/data_store.py

@@ -141,6 +141,7 @@ async def get_v3_data_store_obj_w_code(
         data_store_code: str = Path(min_length=3, max_length=50),
         for_type: Optional[str] = Query(None, min_length=1, max_length=25),
         for_id: Optional[str] = Query(None, min_length=11, max_length=22),
+        limit: int = Query(1, ge=1, description="Number of results to return (Default: 1)"),
 
         account: AccountContext = Depends(get_account_context),
         serialization: SerializationParams = Depends(),
@@ -149,12 +150,11 @@ async def get_v3_data_store_obj_w_code(
     """
     V3 Standardized Data Store Lookup.
     Uses JWT-based AccountContext and supports cascading fallback logic (Object > Account > Global).
+    Returns a single object if limit=1, otherwise returns a list.
     """
     log.setLevel(logging.INFO)
     
     # Map V3 params to the shared handler
-    # We create a dummy Common_Route_Params object to satisfy the handler's interface 
-    # while using the more secure V3 dependencies.
     v3_commons = Common_Route_Params(
         x_account_id=account.account_id,
         x_account_id_random=account.account_id_random,
@@ -167,6 +167,7 @@ async def get_v3_data_store_obj_w_code(
         for_type = for_type,
         for_id = for_id,
         commons = v3_commons,
+        limit = limit,
     )
 # ### END ### API Data Store ### get_v3_data_store_obj_w_code() ###
 
@@ -184,6 +185,7 @@ async def get_data_store_obj_w_code_path(
         data_store_code: str = Path(min_length=3, max_length=50),
         for_type: Optional[str] = Path(min_length=1, max_length=25),
         for_id: Optional[str] = Path(min_length=11, max_length=22),
+        limit: int = Query(1, ge=1),
 
         commons: Common_Route_Params = Depends(common_route_params),
         ):
@@ -195,8 +197,8 @@ async def get_data_store_obj_w_code_path(
         data_store_code = data_store_code,
         for_type = for_type,
         for_id = for_id,
-
         commons = commons,
+        limit = limit,
         )
 
 
@@ -205,6 +207,7 @@ async def get_data_store_obj_w_code_query(
         data_store_code: str = Path(min_length=3, max_length=50),
         for_type: Optional[str] = Query(None, min_length=1, max_length=25),
         for_id: Optional[str] = Query(None, min_length=11, max_length=22),
+        limit: int = Query(1, ge=1),
 
         commons: Common_Route_Params = Depends(common_route_params),
         ):
@@ -216,8 +219,8 @@ async def get_data_store_obj_w_code_query(
         data_store_code = data_store_code,
         for_type = for_type,
         for_id = for_id,
-
         commons = commons,
+        limit = limit,
         )
 
 
@@ -225,39 +228,35 @@ def handle_get_data_store_obj_w_code(
         data_store_code: str,
         for_type: Optional[str],
         for_id: Optional[str],
-
         commons: Common_Route_Params,
+        limit: int = 1,
         ):
     log.setLevel(logging.INFO) # DEBUG, INFO, WARNING, ERROR, EXCEPTION, CRITICAL
     log.debug(locals())
 
-    log.debug(commons.x_account_id_random)
-    log.debug(commons.x_account_id)
-
-    # NOTE: WARNING NOTE: WARNING NOTE: WARNING NOTE: WARNING NOTE: WARNING NOTE: WARNING NOTE: WARNING
-    # time.sleep(2.5) # NOTE: WARNING NOTE: WARNING NOTE: WARNING NOTE: WARNING NOTE: WARNING NOTE: WARNING
-    # NOTE: WARNING NOTE: WARNING NOTE: WARNING NOTE: WARNING NOTE: WARNING NOTE: WARNING NOTE: WARNING
-
     # ### SECTION ### Secondary data validation
     if for_type and for_id:
         if for_id := redis_lookup_id_random(record_id_random=for_id, table_name=for_type): pass
         else: return mk_resp(data=None, status_code=404, response=commons.response, status_message='The for type and ID was invalid or not found.')
 
-    # NOTE: Currently this returns a list: load_data_store_obj_w_code()
-    # NOTE: Only the first sorted record is needed
+    # NOTE: load_data_store_obj_w_code() returns a list
     if data_store_obj_result := load_data_store_obj_w_code(
             account_id = commons.x_account_id,
             code = data_store_code,
             for_type = for_type,
             for_id = for_id,
-            limit = 1, # commons.limit,
+            limit = limit,
             enabled = commons.enabled,
             ):
         log.setLevel(logging.INFO) # DEBUG, INFO, WARNING, ERROR, EXCEPTION, CRITICAL
-        log.info('Loading successful. Returning result')
-        data_store_obj = data_store_obj_result[0] # Get first record only
-        log.debug(data_store_obj)
-        return mk_resp(data=data_store_obj, response=commons.response)
+        log.info(f'Loading successful. Returning {len(data_store_obj_result)} result(s)')
+        
+        # If limit=1, return the first object directly (standard lookup behavior)
+        # If limit > 1, return the list of results
+        data = data_store_obj_result[0] if limit == 1 else data_store_obj_result
+        
+        log.debug(data)
+        return mk_resp(data=data, response=commons.response)
     elif isinstance(data_store_obj_result, list) or data_store_obj_result is None: # Empty list or None
         log.info('No results')
         return mk_resp(data=None, status_code=404, response=commons.response) # Not Found