@remit/data-ports 0.0.59 → 0.0.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.59",
+  "version": "0.0.60",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -52,6 +52,10 @@
     "./update-manifest": {
       "types": "./src/update-manifest.ts",
       "default": "./src/update-manifest.ts"
+    },
+    "./message-settlement": {
+      "types": "./src/message-settlement.ts",
+      "default": "./src/message-settlement.ts"
     }
   },
   "scripts": {

package/src/index.ts

@@ -51,6 +51,8 @@ export type {
 	IUnitOfWork,
 	UnitOfWorkRepositories,
 } from "./interfaces/unit-of-work.js";
+export type { MessageSettlementFields } from "./message-settlement.js";
+export { hasAbandonedDelete } from "./message-settlement.js";
 export {
 	FILTER_NO_ACTION,
 	isSenderMuted,

package/src/message-settlement.test.ts

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
+import { hasAbandonedDelete } from "./message-settlement.js";
+
+describe("hasAbandonedDelete", () => {
+	test("the pair abandonDelete writes, its only writer", () => {
+		assert.equal(
+			hasAbandonedDelete({
+				status: MessageStatus.active,
+				syncStatus: MessageSyncStatus.failed,
+			}),
+			true,
+		);
+	});
+
+	test("a move mid-retry is not a give-up, whatever `failed` suggests", () => {
+		assert.equal(
+			hasAbandonedDelete({
+				status: MessageStatus.moving,
+				syncStatus: MessageSyncStatus.failed,
+			}),
+			false,
+		);
+	});
+
+	test("a delete mid-retry keeps `deleting`, so it is not a give-up", () => {
+		assert.equal(
+			hasAbandonedDelete({
+				status: MessageStatus.deleting,
+				syncStatus: MessageSyncStatus.failed,
+			}),
+			false,
+		);
+	});
+
+	test("a copy that gave up hides its row as `deleted` rather than claiming this", () => {
+		assert.equal(
+			hasAbandonedDelete({
+				status: MessageStatus.deleted,
+				syncStatus: MessageSyncStatus.failed,
+			}),
+			false,
+		);
+	});
+
+	/**
+	 * Both a settled move (`updateUid`) and a delete that exhausted its retries
+	 * (#1143 repairs the row to where the message actually is) land on this pair.
+	 * The second is a give-up this predicate deliberately cannot see — pinned so
+	 * the gap is a decision on record, not an oversight.
+	 */
+	test("`active` + `synced` is never a give-up, however it was reached", () => {
+		assert.equal(
+			hasAbandonedDelete({
+				status: MessageStatus.active,
+				syncStatus: MessageSyncStatus.synced,
+			}),
+			false,
+		);
+	});
+
+	test("an ordinary inbound row, `pending` forever, says nothing", () => {
+		assert.equal(
+			hasAbandonedDelete({
+				status: MessageStatus.active,
+				syncStatus: MessageSyncStatus.pending,
+			}),
+			false,
+		);
+	});
+});

package/src/message-settlement.ts

@@ -0,0 +1,48 @@
+import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
+import type { MessageItem } from "./types.js";
+
+export type MessageSettlementFields = Pick<
+	MessageItem,
+	"status" | "syncStatus"
+>;
+
+/**
+ * A delete Remit refused to run, having already removed the message locally.
+ * `abandonDelete` reaches this from four checks, all of them made before any
+ * expunge: the Trash folder the event names is not on the server (TRYCREATE),
+ * the event carries no destination, it names an operation this build does not
+ * recognise, or it was minted under an unknown contract. The row is handed back
+ * to the folder the server still holds the message in.
+ *
+ * `status: active` alongside `syncStatus: failed` is the whole signal, and
+ * `abandonDelete` (`imap-worker/src/handlers/message-delete.ts`) is its ONLY
+ * writer. Every other writer of either value writes the other along with it:
+ *
+ * - `updateUid` (`drizzle-service/src/repos/message.ts`) settles a confirmed
+ *   move by writing `active` and `synced` in the same statement, so a move that
+ *   worked after a failed attempt cannot leave `failed` behind.
+ * - `empty-trash` and `message-copy`'s `settleCopied` both hand a row back as
+ *   `active` + `synced`.
+ * - `upsertWithStatus` leaves an existing row alone, so no inbound sync writes
+ *   either value onto a row that already has them.
+ *
+ * `syncStatus: failed` ON ITS OWN is NOT a give-up marker, whatever
+ * `placement-settled.ts`'s docstring says. `message-move.ts`, `message-delete.ts`
+ * and `message-copy.ts` each write it on an ORDINARY TRANSIENT attempt and then
+ * re-throw for queue redelivery — the row is mid-retry and about to succeed. In
+ * those handlers `status` stays at its in-flight value (`moving`, `deleting`),
+ * which is what separates them from the pair above.
+ *
+ * Three give-ups this cannot see, and must not pretend to:
+ *
+ * - A MOVE that gave up leaves `moving` + `failed`, the same pair a first
+ *   dropped connection writes. Nothing persisted tells the two apart.
+ * - A DELETE that exhausted its retries settles `active` + `synced` (#1143's
+ *   `resolveExhaustedMessageDeleteFailure` repairs the row to where the message
+ *   actually is), so it reads as fully settled here.
+ * - `flag-push` and `placement-move-push` never write either field at all.
+ *   Their give-up state lives on their own marker rows.
+ */
+export const hasAbandonedDelete = (message: MessageSettlementFields): boolean =>
+	message.status === MessageStatus.active &&
+	message.syncStatus === MessageSyncStatus.failed;