apple-mail-mcp 2.10.33 → 2.11.0

package/README.md

@@ -1319,14 +1319,26 @@ returns the comparison in `structuredContent`:
 }
 ```
 
-`status` is deliberately four-valued rather than a pass/fail flag:
+`status` is deliberately not a pass/fail flag:
 
 | `status` | Meaning | Warns? |
 |----------|---------|--------|
 | `match` | Exactly as many messages left the mailbox as the operation acted on. | No |
 | `over` | **More** left than were operated on. Messages are unaccounted for. | **Yes** |
-| `under` | **Fewer** left than expected. | No |
-| `unknown` | No comparison was possible: either Mail would not report a count (`before`/`after` null) or there is no predictable expectation (`expected` null — see the self-move rule below). | No |
+| `unknown` | No comparison this server is willing to assert. `unknownReason` says which of four situations produced it. | No |
+
+`unknownReason` distinguishes four cases that are *not* interchangeable:
+
+| `unknownReason` | Meaning |
+|-----------------|---------|
+| `count-unreadable` | Mail would not report a count at all (`before`/`after` null). |
+| `no-expectation` | No expectation is predictable, so no comparison exists — a move whose destination **is** the source mailbox. |
+| `count-did-not-move` | The count did not move. On a store that flags deletions instead of removing them this is the **ordinary, correct** reading for an operation that fully succeeded. |
+| `count-partial` | The count moved, but by less than the operation accounted for. A flag-only store cannot produce this, which is why it is worth telling apart. |
+
+> **`under` was removed in 2.11.0.** It used to mean "fewer left than expected"
+> and was documented as routine. Field evidence retired it — see
+> [Why `observed` is a lower bound](#why-observed-is-a-lower-bound-155).
 
 #### What an `over` warning does and does not tell you
 
@@ -1346,7 +1358,7 @@ trusted:
 **Concurrent departure is the benign cause to rule out first**, and the warning
 text says so. What the asymmetry argument actually buys is the other half:
 concurrent *arrivals* cannot produce `over`, because a message arriving
-mid-operation *raises* the after-count and biases the reading toward `under`.
+mid-operation *raises* the after-count and biases the reading short.
 That is why `over` is the interesting direction — a strong signal, not a proof.
 
 Setting `APPLE_MAIL_MCP_AUDIT_LOG` is what settles which one you have: the
@@ -1354,12 +1366,42 @@ collateral diff below **names** the messages that disappeared, and "the
 newsletter my rule files every morning" is a very different report from a message
 nothing should have touched.
 
-`under`, by contrast, is routine: an account that flags deletions rather than
-removing them leaves the message in place and the count does not move, and a
-Gmail label mailbox can behave the same way while the delete genuinely succeeded.
-A warning that fires on every ordinary Gmail delete would be ignored exactly when
-it matters, so `under` is **reported** in `countDelta` (with a `note` explaining
-it) and never warned about.
+#### Why `observed` is a lower bound (#155)
+
+**`observed` is the movement of Mail's count. It is a lower bound on how many
+messages left, not a count of how many left.**
+
+On iCloud, @scottstern0325 ran the check that settled this: for two batches
+reporting `observed: 0`, the messages were located **in Trash**, matched by
+`date received` + sender against the audit log's pre-image. The deletes had
+happened. Mail's count had not caught up. Across four readings — 0 of 4, 0 of 1
+(a *single-id* delete), 15 of 16, and 14 of 15 — the shortfall bore no relation
+to batch size, which is what a lagging count looks like and not what a
+store-behaviour rule looks like.
+
+So a short reading is not evidence about your operation. **The per-id outcomes
+are what report success; this number is not. Do not retry on the strength of
+it** — that is how a message gets deleted twice.
+
+Two things follow:
+
+- A count that does not move at all is still the ordinary reading on a store that
+  flags deletions instead of removing them (Gmail label mailboxes, IMAP accounts
+  with "move deleted messages to Trash" off). It reports
+  `unknownReason: "count-did-not-move"` and says so, and it is never warned about
+  — a warning that fires on every ordinary Gmail delete would be ignored exactly
+  when it matters.
+- **To confirm where messages went, match them at the destination by `date
+  received` plus sender — not by the numeric ids you passed.** Ids are renumbered
+  by the move and do not survive it.
+
+**Removed in 2.11.0: the "reported success with no observed effect" warning.**
+Shipped in 2.10.30, it fired when the count was flat, the snapshot read cleanly
+and nothing had disappeared. Its premise was that the snapshot corroborated the
+count — but both are read back-to-back in the same script, and the record that
+prompted it turns out to have had *both* instruments stale at once. It therefore
+fired on stores that had done exactly what they were asked. It is gone rather
+than narrowed; `over` is the only surviving assertion.
 
 Three more honesty rules:
 
@@ -1489,8 +1531,15 @@ a hole, because a wrong name here is worse than a missing one:
 | both | withheld | withheld |
 
 **An absent field means "not computable", never "empty".** Check
-`"snapshot": "ok"` before reading `disappeared` as a clean bill of health — the
-false-ok warning does exactly that, so a `partial` snapshot never triggers it.
+`"snapshot": "ok"` before reading `disappeared` as a clean bill of health.
+
+> ⚠️ **`"ok"` is necessary, not sufficient.** The enumeration's range is bounded
+> by Mail's own message count, and #155 established that count can lag the
+> mutation. A count reading **low** truncates the enumeration silently — the
+> unread tail is never requested, so it never registers as a failed slice and the
+> status still says `"ok"` — and messages past that bound would then look like
+> they disappeared. Until that is fixed, treat a `disappeared` entry as a lead to
+> check, not a proof.
 
 ### Privacy, and what the file costs you
 

package/build/index.js

@@ -78854,17 +78854,8 @@ function countDeltaWarning(d) {
   const where = d.account ? `"${d.mailbox}" in account "${d.account}"` : `"${d.mailbox}"`;
   return `\u26A0\uFE0F Effect mismatch in ${where}: ${d.observed} message(s) left the mailbox but only ${d.expected} were operated on (count ${d.before} \u2192 ${d.after}). ${extra} message(s) are unaccounted for. Anything else removing mail from this mailbox at the same moment \u2014 a Mail rule, a server-side filter, another client, an IMAP expunge \u2014 reads the same way, so rule that out first. If nothing else was touching it, this is the signature of https://github.com/sweetrb/apple-mail-mcp/issues/155 \u2014 please report it there, and set ${AUDIT_LOG_ENV}=/path/to/audit.ndjson to capture which messages disappeared.`;
 }
-function falseOkWarning(d, collateral) {
-  if (d.status !== "under" || d.expected === null) return null;
-  if (d.observed !== 0 || d.expected <= 0) return null;
-  if (!collateral || collateral.snapshot !== "ok") return null;
-  if ((collateral.disappeared?.length ?? 0) !== 0) return null;
-  const where = d.account ? `"${d.mailbox}" in account "${d.account}"` : `"${d.mailbox}"`;
-  return `\u26A0\uFE0F Reported success with no observed effect in ${where}: ${d.expected} message(s) were operated on and reported ok, but the mailbox count did not move (${d.before} \u2192 ${d.after}) and the collateral snapshot \u2014 which read this mailbox successfully \u2014 shows no message left it. Either the operation silently did nothing, or Mail's count and listing are both stale and the messages did move. Check the destination (Trash for a delete) before assuming either: if they are there, this is a measurement-timing bug; if they are still in the source mailbox minutes later, the operation failed while reporting success. Please report at https://github.com/sweetrb/apple-mail-mcp/issues/155 with ${AUDIT_LOG_ENV}=/path/to/audit.ndjson set.`;
-}
 function reconciliationWarnings(report) {
-  const collateralFor = (d) => report.collateral.find((c) => c.account === d.account && c.mailbox === d.mailbox);
-  return report.countDeltas.flatMap((d) => [countDeltaWarning(d), falseOkWarning(d, collateralFor(d))]).filter((w) => w !== null);
+  return report.countDeltas.map((d) => countDeltaWarning(d)).filter((w) => w !== null);
 }
 
 // src/services/appleMailManager.ts
@@ -79142,6 +79133,8 @@ function canonicalNumericId(raw) {
   return Number.isFinite(n) ? String(n) : trimmed;
 }
 var SELF_MOVE_NOTE = "Destination is the source mailbox, so no message should leave it. What Mail does to the count when a message is re-filed into the mailbox it already occupies is unspecified, so there is no expected delta to compare against: this mailbox is reported without a comparison and is never warned about.";
+var COUNT_UNMOVED_NOTE = `Mail's count did not move. This is the ordinary reading on a store that flags deletions instead of removing them (Gmail label mailboxes and IMAP accounts with "move deleted messages to Trash" off), where the message stays put and the operation still fully succeeded. It can also mean Mail's count simply had not caught up yet. The per-id outcomes are what report success; this number is not, so do not retry on the strength of it.`;
+var COUNT_PARTIAL_NOTE = `Mail's count moved by less than this operation accounted for. That is a LOWER BOUND on what left, not a count of what left: Mail has been observed reporting a stale count for a delete it had already performed (issue #155), and new mail arriving mid-operation reads the same way. No claim is made either way. To confirm where the messages went, match them at the destination by "date received" plus sender \u2014 NOT by the numeric ids you passed, which are renumbered by the move and do not survive it.`;
 function snapshotKey(entry) {
   return `${entry.id}\0${entry.messageId}`;
 }
@@ -79679,10 +79672,24 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       const observed = readable ? m.before - m.after : null;
       const note = noteFor(m.account, m.mailbox);
       let status;
-      if (!readable || m.expected === null) status = "unknown";
-      else if (observed === m.expected) status = "match";
-      else if ((observed ?? 0) > m.expected) status = "over";
-      else status = "under";
+      let unknownReason;
+      if (!readable) {
+        status = "unknown";
+        unknownReason = "count-unreadable";
+      } else if (m.expected === null) {
+        status = "unknown";
+        unknownReason = "no-expectation";
+      } else if (observed === m.expected) {
+        status = "match";
+      } else if ((observed ?? 0) > m.expected) {
+        status = "over";
+      } else if (observed === 0) {
+        status = "unknown";
+        unknownReason = "count-did-not-move";
+      } else {
+        status = "unknown";
+        unknownReason = "count-partial";
+      }
       return {
         account: m.account,
         mailbox: m.mailbox,
@@ -79691,11 +79698,11 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         expected: m.expected,
         observed,
         status,
+        ...unknownReason ? { unknownReason } : {},
         ...note ? { note } : {},
-        ...status === "unknown" && readable === false ? { note: note ?? "Mail did not report a message count for this mailbox" } : {},
-        ...status === "under" && !note ? {
-          note: "Fewer messages left the mailbox than were operated on. This is normal on a store that flags deletions instead of removing them (and when new mail arrives mid-operation), so it is reported but not warned about."
-        } : {}
+        ...unknownReason === "count-unreadable" ? { note: note ?? "Mail did not report a message count for this mailbox" } : {},
+        ...unknownReason === "count-did-not-move" && !note ? { note: COUNT_UNMOVED_NOTE } : {},
+        ...unknownReason === "count-partial" && !note ? { note: COUNT_PARTIAL_NOTE } : {}
       };
     });
     const preImages = [];
@@ -85303,7 +85310,10 @@ var COUNT_DELTA_OUTPUT_SCHEMA = external_exports.array(
     // `status: "unknown"`, and never with a warning.
     expected: external_exports.number().nullable().optional(),
     observed: external_exports.number().nullable().optional(),
-    status: external_exports.enum(["match", "over", "under", "unknown"]).optional(),
+    status: external_exports.enum(["match", "over", "unknown"]).optional(),
+    // Declared explicitly: the SDK stamps additionalProperties:false on a bare
+    // zod shape, so an undeclared key makes the CLIENT reject the result.
+    unknownReason: external_exports.enum(["count-unreadable", "no-expectation", "count-did-not-move", "count-partial"]).optional(),
     note: external_exports.string().optional()
   })
 ).optional();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.10.33",
+  "version": "2.11.0",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",