Address review: harden target watchdog and clarify helper docstrings

Watchdog (pr-tests.yml): require two consecutive low container-count
readings before aborting. A single reading of the resource-heavy suite's
`docker compose ps` can transiently error and read as 0, which would
false-abort a healthy run; a real crash stays low across polls, so this
rules out the false abort while adding at most one poll interval to a
genuine fast-fail.

Helper docstrings (utils.py): the insert+aggregate form leaves the input
row with an auto-generated `_id` rather than the field-less row
`$documents: [{}]` produced, so note that an expression reading `$_id`,
`$$ROOT`, or `$$CURRENT` sees that id and diverges (references to any other
missing field are still identical). Documentation only; no behavior change.

Signed-off-by: Yunxuan Shi <yunxuan@amazon.com>

Author: eerxuan

.github/workflows/pr-tests.yml

@@ -92,7 +92,7 @@ jobs:
           PROFILE='${{ matrix.target.profile }}'
           watch_target() {
             set +e
-            local pid=$1 expected
+            local pid=$1 expected running low=0
             expected=$(docker compose -f dev/compose.yaml --profile "$PROFILE" config --services | grep -c .)
             # Sanity-check the probe once. The stack is already up (compose
             # --wait), so every service should read as running; if it does not,
@@ -103,11 +103,22 @@ jobs:
               return
             fi
             while kill -0 "$pid" 2>/dev/null; do
-              if [ "$(docker compose -f dev/compose.yaml --profile "$PROFILE" ps --status running -q 2>/dev/null | grep -c .)" -lt "$expected" ]; then
-                echo "::error::A $PROFILE target container exited mid-run (likely a server crash). Aborting the test run so the job fails fast instead of timing out every remaining test against a dead target."
-                docker compose -f dev/compose.yaml --profile "$PROFILE" ps -a
-                kill -TERM "$pid" 2>/dev/null; sleep 10; kill -KILL "$pid" 2>/dev/null
-                return
+              running=$(docker compose -f dev/compose.yaml --profile "$PROFILE" ps --status running -q 2>/dev/null | grep -c .)
+              # Require two consecutive low readings before aborting. A single
+              # low count can be a transient docker-CLI hiccup on this
+              # resource-heavy runner (a failed query reads as 0); a real crash
+              # stays low, so demanding two polls in a row rules out a false
+              # abort while adding only one poll interval to a genuine one.
+              if [ "$running" -lt "$expected" ]; then
+                low=$((low + 1))
+                if [ "$low" -ge 2 ]; then
+                  echo "::error::A $PROFILE target container exited mid-run (likely a server crash). Aborting the test run so the job fails fast instead of timing out every remaining test against a dead target."
+                  docker compose -f dev/compose.yaml --profile "$PROFILE" ps -a
+                  kill -TERM "$pid" 2>/dev/null; sleep 10; kill -KILL "$pid" 2>/dev/null
+                  return
+                fi
+              else
+                low=0
               fi
               sleep 15
             done

documentdb_tests/compatibility/tests/core/operator/expressions/utils/utils.py

@@ -45,12 +45,14 @@ def execute_project(collection, project):
     helper free of any dependency on ``$documents`` support while producing the
     same single-row input the projection sees.
 
-    Note: the inserted document carries an auto-generated ``_id`` and the helper
-    aggregates over the whole collection. The output projection excludes ``_id``,
-    so literal expressions and missing-field references behave identically to a
-    ``$documents: [{}]`` row. Callers that need a truly field-less input (e.g.
-    ``$$ROOT`` must be ``{}``) or exactly one row over a pre-populated collection
-    must shape their own pipeline instead of using this helper.
+    Note: the inserted document carries an auto-generated ``_id``, so the input
+    row is ``{_id: <ObjectId>}`` rather than the field-less row ``$documents:
+    [{}]`` produces. Literal expressions and references to any other (missing)
+    field behave identically, and the output projection excludes ``_id``; but an
+    expression that reads ``$_id``, ``$$ROOT``, or ``$$CURRENT`` sees that id and
+    will diverge. Callers that need a truly field-less input (e.g. ``$$ROOT`` must
+    be ``{}``) or exactly one row over a pre-populated collection must shape their
+    own pipeline instead of using this helper.
 
     Args:
         collection: MongoDB collection object
@@ -120,15 +122,17 @@ def execute_expression(collection, expression):
     synthesizing the row with a ``$documents`` stage. This keeps the helper free
     of any dependency on ``$documents`` support while producing the same
     single-row input the expression is evaluated against. Useful for testing
-    expressions with literal values; field references resolve to missing, just
-    as they would against a ``$documents: [{}]`` row.
-
-    Note: the inserted document carries an auto-generated ``_id`` and the helper
-    aggregates over the whole collection. The output projection excludes ``_id``,
-    so literal expressions and missing-field references are unaffected. Callers
-    that need a truly field-less input (e.g. ``$$ROOT`` must be ``{}``) or exactly
-    one row over a pre-populated collection must shape their own pipeline instead
-    of using this helper.
+    expressions with literal values; references to fields other than ``_id``
+    resolve to missing, just as they would against a ``$documents: [{}]`` row.
+
+    Note: the inserted document carries an auto-generated ``_id``, so the input
+    row is ``{_id: <ObjectId>}`` rather than the field-less row ``$documents:
+    [{}]`` produces. Literal expressions and references to any other (missing)
+    field are unaffected, and the output projection excludes ``_id``; but an
+    expression that reads ``$_id``, ``$$ROOT``, or ``$$CURRENT`` sees that id and
+    will diverge. Callers that need a truly field-less input (e.g. ``$$ROOT`` must
+    be ``{}``) or exactly one row over a pre-populated collection must shape their
+    own pipeline instead of using this helper.
 
     Args:
         collection: MongoDB collection object