HT-7: mail-behavior acceptance fixtures

fixtures/mail/README.md

@@ -0,0 +1,31 @@
+# Mail-behavior acceptance fixtures
+
+These fixtures define the **mail behavior Helpthread's engine must exhibit** —
+they are the acceptance criteria the mail engine (and its threading logic, per
+[`specs/mail/threading.md`](../../specs/mail/threading.md)) is tested against.
+Each records an input scenario and the expected conversation/threading outcome.
+
+## What they assert
+
+- `new-conversation` — a fresh inbound email opens a new conversation.
+- `reply-with-reference` — a reply carrying a valid signed reply token threads
+  into the same conversation.
+- `token-authority` — a valid token threads even when the subject is unrelated;
+  the token, not the subject, is the threading authority.
+- `forged-reply-token` — a tampered token is rejected and opens a new
+  conversation; the token is verified, not merely pattern-matched.
+- `reply-subject-only` / `same-subject-different-customer` — a matching subject
+  with no valid token never threads; subject is never a threading signal.
+- `auto-submitted` — auto-submitted mail still creates a conversation.
+- `html-body` — an inbound HTML body (including a `<script>` tag) is captured
+  verbatim, establishing that the engine — not the reader — must sanitize.
+
+## Provenance
+
+These outcomes were captured by **black-box observation** of a running
+reference helpdesk (facts about behavior, recorded via its API), used to
+validate the threading spec and surface real-world edge cases. Token values and
+personal data are redacted to deterministic placeholders. This is behavioral
+ground truth only — Helpthread's implementation is its own (see the charter's
+provenance section). The observation tooling itself is not part of this repo;
+Helpthread's own end-to-end mail tests will point at a Helpthread instance.

fixtures/mail/observed/auto-submitted.json

@@ -0,0 +1,122 @@
+{
+  "scenario": "auto-submitted",
+  "title": "Auto-Submitted: auto-replied message handling",
+  "expectation": "An email marked Auto-Submitted: auto-replied may be suppressed (no conversation) or ingested normally — observed, not assumed.",
+  "runId": "23ad1ec4",
+  "recordedAt": "2026-07-10T04:18:57.805Z",
+  "sent": [
+    {
+      "from": "customer-23ad1ec4-d@example.test",
+      "to": "support@example.test",
+      "subject": "Harness auto-submitted [HT7-23ad1ec4-auto-submitted]",
+      "text": "Auto-submitted probe. [HT7-23ad1ec4-auto-submitted]",
+      "headers": {
+        "Auto-Submitted": "auto-replied"
+      },
+      "messageId": "<7bfcf2e0-8a77-93fd-4f0a-8c4daef47ec3@example.test>",
+      "envelope": {
+        "from": "customer-23ad1ec4-d@example.test",
+        "to": [
+          "support@example.test"
+        ]
+      }
+    }
+  ],
+  "observed": {
+    "outcome": "created",
+    "conversation": {
+      "id": 18,
+      "number": 18,
+      "threadsCount": 1,
+      "type": "email",
+      "folderId": 1,
+      "status": "active",
+      "state": "published",
+      "subject": "Harness auto-submitted [HT7-23ad1ec4-auto-submitted]",
+      "preview": "Auto-submitted probe. [HT7-23ad1ec4-auto-submitted]",
+      "mailboxId": 1,
+      "assignee": null,
+      "createdBy": {
+        "id": 3,
+        "type": "customer",
+        "firstName": "Redacted",
+        "lastName": "Person",
+        "photoUrl": "https://helpdesk.example.test/avatar.jpg",
+        "email": "customer@example.test"
+      },
+      "createdAt": "2026-07-10T04:18:54Z",
+      "updatedAt": "2026-07-10T04:18:54Z",
+      "closedBy": null,
+      "closedByUser": null,
+      "closedAt": null,
+      "userUpdatedAt": null,
+      "customerWaitingSince": {
+        "time": "2026-07-10T04:18:54Z",
+        "friendly": "Just now",
+        "latestReplyFrom": "customer"
+      },
+      "source": {
+        "type": "email",
+        "via": "customer"
+      },
+      "cc": [],
+      "bcc": [],
+      "customer": {
+        "id": 3,
+        "type": "customer",
+        "firstName": "Redacted",
+        "lastName": "Person",
+        "photoUrl": "https://helpdesk.example.test/avatar.jpg",
+        "email": "customer@example.test"
+      },
+      "_embedded": {
+        "threads": [
+          {
+            "id": 34,
+            "type": "customer",
+            "status": "active",
+            "state": "published",
+            "action": {
+              "type": "",
+              "text": "Redacted Person started a new conversation #18",
+              "associatedEntities": []
+            },
+            "body": "Auto-submitted probe. [HT7-23ad1ec4-auto-submitted]",
+            "source": {
+              "type": "email",
+              "via": "customer"
+            },
+            "customer": {
+              "id": 3,
+              "type": "customer",
+              "firstName": "Redacted",
+              "lastName": "Person",
+              "photoUrl": "https://helpdesk.example.test/avatar.jpg",
+              "email": "customer@example.test"
+            },
+            "createdBy": {
+              "id": 3,
+              "type": "customer",
+              "firstName": "Redacted",
+              "lastName": "Person",
+              "photoUrl": "https://helpdesk.example.test/avatar.jpg",
+              "email": "customer@example.test"
+            },
+            "assignedTo": null,
+            "to": [
+              "support@example.test"
+            ],
+            "cc": [],
+            "bcc": [],
+            "createdAt": "2026-07-10T04:18:54Z",
+            "openedAt": null,
+            "_embedded": {
+              "attachments": []
+            }
+          }
+        ]
+      }
+    }
+  },
+  "notes": "A conversation WAS created for an \"Auto-Submitted: auto-replied\" message (id 18)."
+}

fixtures/mail/observed/forged-reply-token.json

@@ -0,0 +1,115 @@
+{
+  "scenario": "forged-reply-token",
+  "title": "Reply whose In-Reply-To carries a tampered FS_reply token",
+  "expectation": "A forged token must not thread into the real conversation — new conversation or rejection, observed.",
+  "sent": [
+    {
+      "subject": "Re: Harness reply-with-reference [HT7-23ad1ec4x-forged-reply-token]",
+      "headers": {
+        "In-Reply-To": "<FS_reply-36-3333333333333333@helpdesk.example.test>",
+        "References": "<FS_reply-36-3333333333333333@helpdesk.example.test>"
+      }
+    }
+  ],
+  "observed": {
+    "newConversation": {
+      "id": 20,
+      "number": 20,
+      "threadsCount": 1,
+      "type": "email",
+      "folderId": 1,
+      "status": "active",
+      "state": "published",
+      "subject": "Re: Harness reply-with-reference [HT7-23ad1ec4x-forged-reply-token]",
+      "preview": "Reply carrying a FORGED token. [HT7-23ad1ec4x-forged-reply-token]",
+      "mailboxId": 1,
+      "assignee": null,
+      "createdBy": {
+        "id": 3,
+        "type": "customer",
+        "firstName": "Redacted",
+        "lastName": "Person",
+        "photoUrl": "https://helpdesk.example.test/avatar.jpg",
+        "email": "customer@example.test"
+      },
+      "createdAt": "2026-07-10T04:58:53Z",
+      "updatedAt": "2026-07-10T04:58:53Z",
+      "closedBy": null,
+      "closedByUser": null,
+      "closedAt": null,
+      "userUpdatedAt": null,
+      "customerWaitingSince": {
+        "time": "2026-07-10T04:58:53Z",
+        "friendly": "Just now",
+        "latestReplyFrom": "customer"
+      },
+      "source": {
+        "type": "email",
+        "via": "customer"
+      },
+      "cc": [],
+      "bcc": [],
+      "customer": {
+        "id": 3,
+        "type": "customer",
+        "firstName": "Redacted",
+        "lastName": "Person",
+        "photoUrl": "https://helpdesk.example.test/avatar.jpg",
+        "email": "customer@example.test"
+      },
+      "_embedded": {
+        "threads": [
+          {
+            "id": 38,
+            "type": "customer",
+            "status": "active",
+            "state": "published",
+            "action": {
+              "type": "",
+              "text": "Redacted Person started a new conversation #20",
+              "associatedEntities": []
+            },
+            "body": "Reply carrying a FORGED token. [HT7-23ad1ec4x-forged-reply-token]",
+            "source": {
+              "type": "email",
+              "via": "customer"
+            },
+            "customer": {
+              "id": 3,
+              "type": "customer",
+              "firstName": "Redacted",
+              "lastName": "Person",
+              "photoUrl": "https://helpdesk.example.test/avatar.jpg",
+              "email": "customer@example.test"
+            },
+            "createdBy": {
+              "id": 3,
+              "type": "customer",
+              "firstName": "Redacted",
+              "lastName": "Person",
+              "photoUrl": "https://helpdesk.example.test/avatar.jpg",
+              "email": "customer@example.test"
+            },
+            "assignedTo": null,
+            "to": [
+              "support@example.test"
+            ],
+            "cc": [],
+            "bcc": [],
+            "createdAt": "2026-07-10T04:58:53Z",
+            "openedAt": null,
+            "_embedded": {
+              "attachments": []
+            }
+          }
+        ]
+      }
+    },
+    "appendedToRealConversation": false,
+    "conv15ThreadsBefore": 4,
+    "conv15ThreadsAfter": 4
+  },
+  "notes": "Forgery = token segment character-reversed inside a real FS_reply Message-ID from the base run.",
+  "runId": "23ad1ec4x",
+  "recordedAt": "2026-07-10T05:01:08.938Z"
+}

fixtures/mail/observed/html-body.json

@@ -0,0 +1,115 @@
+{
+  "scenario": "html-body",
+  "title": "HTML email with formatting, link, image, and a script tag",
+  "expectation": "What survives ingestion/sanitization into the stored thread body — observed.",
+  "sent": [
+    {
+      "subject": "Harness html body [HT7-23ad1ec4x-html-body]",
+      "html": true,
+      "includes": [
+        "strong",
+        "a href",
+        "img",
+        "script"
+      ]
+    }
+  ],
+  "observed": {
+    "conversation": {
+      "id": 21,
+      "number": 21,
+      "threadsCount": 1,
+      "type": "email",
+      "folderId": 1,
+      "status": "active",
+      "state": "published",
+      "subject": "Harness html body [HT7-23ad1ec4x-html-body]",
+      "preview": "HTML body with bold, a link, an inline and a script tag. [HT7-23ad1ec4x-html-body]",
+      "mailboxId": 1,
+      "assignee": null,
+      "createdBy": {
+        "id": 3,
+        "type": "customer",
+        "firstName": "Redacted",
+        "lastName": "Person",
+        "photoUrl": "https://helpdesk.example.test/avatar.jpg",
+        "email": "customer@example.test"
+      },
+      "createdAt": "2026-07-10T05:00:56Z",
+      "updatedAt": "2026-07-10T05:00:56Z",
+      "closedBy": null,
+      "closedByUser": null,
+      "closedAt": null,
+      "userUpdatedAt": null,
+      "customerWaitingSince": {
+        "time": "2026-07-10T05:00:56Z",
+        "friendly": "Just now",
+        "latestReplyFrom": "customer"
+      },
+      "source": {
+        "type": "email",
+        "via": "customer"
+      },
+      "cc": [],
+      "bcc": [],
+      "customer": {
+        "id": 3,
+        "type": "customer",
+        "firstName": "Redacted",
+        "lastName": "Person",
+        "photoUrl": "https://helpdesk.example.test/avatar.jpg",
+        "email": "customer@example.test"
+      },
+      "_embedded": {
+        "threads": [
+          {
+            "id": 40,
+            "type": "customer",
+            "status": "active",
+            "state": "published",
+            "action": {
+              "type": "",
+              "text": "Redacted Person started a new conversation #21",
+              "associatedEntities": []
+            },
+            "body": "<p>HTML body with <strong>bold</strong>, a <a href=\"https://example.com\">link</a>, an inline <img src=\"https://example.com/x.png\" alt=\"img\"> and a <script>alert(1)</script> script tag. [HT7-23ad1ec4x-html-body]</p>",
+            "source": {
+              "type": "email",
+              "via": "customer"
+            },
+            "customer": {
+              "id": 3,
+              "type": "customer",
+              "firstName": "Redacted",
+              "lastName": "Person",
+              "photoUrl": "https://helpdesk.example.test/avatar.jpg",
+              "email": "customer@example.test"
+            },
+            "createdBy": {
+              "id": 3,
+              "type": "customer",
+              "firstName": "Redacted",
+              "lastName": "Person",
+              "photoUrl": "https://helpdesk.example.test/avatar.jpg",
+              "email": "customer@example.test"
+            },
+            "assignedTo": null,
+            "to": [
+              "support@example.test"
+            ],
+            "cc": [],
+            "bcc": [],
+            "createdAt": "2026-07-10T05:00:56Z",
+            "openedAt": null,
+            "_embedded": {
+              "attachments": []
+            }
+          }
+        ]
+      }
+    }
+  },
+  "notes": "Script tag included deliberately to observe sanitization behavior on the stored body.",
+  "runId": "23ad1ec4x",
+  "recordedAt": "2026-07-10T05:01:08.946Z"
+}