From 9ad3458cf932f94f48d0c7becfb43585163d94d4 Mon Sep 17 00:00:00 2001
From: disqualifier <dev@disqualifier.me>
Date: Mon, 29 Jun 2026 20:48:08 -0400
Subject: [PATCH] fix: align push helpers to matched_count for success-contract
 consistency (v0.1.3)

mongo-1: document_push_array and document_push_and_set still returned modified_count>0
while the v0.1.2 wave moved the sibling single-doc update helpers to matched_count>0.
$push always mutates so the two agree in practice (no reachable behavioral change), but
the helpers now match the documented 'True when a document matched' contract uniformly.

sibling-grep: zero consumers of either push helper.
Signed-off-by: disqualifier <dev@disqualifier.me>
---
 README.md          |  6 +++---
 pyproject.toml     |  2 +-
 src/mongo/mongo.py | 17 +++++++++++++----
 3 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 96053cb..ff00f8f 100644
--- a/README.md
+++ b/README.md
@@ -8,18 +8,18 @@ helpers for the common paths, with a raw escape hatch for everything else.
 `requirements.txt`:
 
 ```
-mongo @ git+ssh://git@git.rethinkstudios.io/rethink-public/mongo.git@v0.1.2
+mongo @ git+ssh://git@git.rethinkstudios.io/rethink-public/mongo.git@v0.1.3
 ```
 
 Direct:
 
 ```bash
-pip install "mongo @ git+ssh://git@git.rethinkstudios.io/rethink-public/mongo.git@v0.1.2"
+pip install "mongo @ git+ssh://git@git.rethinkstudios.io/rethink-public/mongo.git@v0.1.3"
 ```
 
 Requires `motor` and `pymongo` (pulled transitively).
 
-Drop the `@v0.1.2` suffix from the line above to install the latest unpinned.
+Drop the `@v0.1.3` suffix from the line above to install the latest unpinned.
 
 ## Usage
 
diff --git a/pyproject.toml b/pyproject.toml
index b9c648c..c1a06ea 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mongo"
-version = "0.1.2"
+version = "0.1.3"
 description = "async mongodb wrapper over motor with a raw escape hatch"
 requires-python = ">=3.10"
 dependencies = [
diff --git a/src/mongo/mongo.py b/src/mongo/mongo.py
index bb01505..294fb3c 100644
--- a/src/mongo/mongo.py
+++ b/src/mongo/mongo.py
@@ -361,10 +361,15 @@ class Mongo:
     async def document_push_array(
         self, collection: str, target: dict, array: str, value: Any
     ) -> bool:
-        """$push a value onto an array field"""
+        """$push a value onto an array field
+
+        returns True when a document matched (consistent with the other single-doc
+        update helpers); $push always mutates, so matched_count and modified_count
+        agree here in practice.
+        """
         try:
             response = await self._db[collection].update_one(target, {"$push": {array: value}})
-            return response.modified_count > 0
+            return response.matched_count > 0
         except Exception:
             log.exception(f"db.document_push_array() on {collection}")
             return False
@@ -373,13 +378,17 @@ class Mongo:
         self, collection: str, target: dict, array: str, value: Any,
         field_to_set: str, set_value: Any,
     ) -> bool:
-        """$push to an array and $set a field in one update"""
+        """$push to an array and $set a field in one update
+
+        returns True when a document matched (consistent with the other single-doc
+        update helpers).
+        """
         try:
             response = await self._db[collection].update_one(
                 target,
                 {"$push": {array: value}, "$set": {field_to_set: set_value}},
             )
-            return response.modified_count > 0
+            return response.matched_count > 0
         except Exception:
             log.exception(f"db.document_push_and_set() on {collection}")
             return False