@snagset/server 0.1.10 → 0.1.12

package/dist/mail/digest.js

@@ -0,0 +1,291 @@
+import { randomUUID } from "node:crypto";
+import { sanitise, sanitiseWithRedactor } from "../vendor/adapters/index.js";
+import { redactText } from "../vendor/widget/predicates.js";
+import { isConfigured } from "./mailer.js";
+import { dashboardUrl, threadUrl } from "./links.js";
+/**
+ * The daily digest — D120, on Eurico's "we don't need to send the email every
+ * time there is a comment, maybe once in a while".
+ *
+ * `SNAGSET_MAIL_NOTIFY=digest` (the default) changes ONE thing: how the
+ * project OWNER hears about `comment.created`. Reviewer mail — a reply on a
+ * thread they took part in, a snag marked resolved — stays per event, because
+ * a reviewer hears about one conversation they are waiting on, not about a
+ * whole studio's day.
+ *
+ * ── NO NEW SCHEDULER, NO NEW TABLE ──
+ *
+ * The owner's row is queued exactly as before, in the comment's transaction,
+ * with the same dedupe key (`notify.ts`). In digest mode the delivery job
+ * simply does not claim it. This job FOLDS those rows: once a day it takes
+ * every pending owner row queued before midnight UTC, writes ONE outbox row
+ * of topic `comment.digest` that lists them, and marks them `done` — in one
+ * transaction, the job engine's. The digest row is then an ordinary outbox
+ * row, delivered by the ordinary delivery job, with its claim-before-send,
+ * its backoff and its per-address rate limit. Nothing about sending is
+ * written twice.
+ *
+ * ── HOW "AT MOST ONE A DAY" IS ACTUALLY ACHIEVED ──
+ *
+ *   1. **The day is in the dedupe key.** `comment.digest:<orgId>:<YYYY-MM-DD>`
+ *      under the outbox's `UNIQUE (provider, dedupe_key)`. A second build on
+ *      the same UTC day — the bin's next hourly tick, an operator forcing the
+ *      cron route, two instances at once — cannot create a second row, and an
+ *      org that already has today's row is not even considered.
+ *   2. **The window is fixed, not "since the last run".** Only rows queued
+ *      BEFORE today's midnight (UTC) are folded. A comment at 09:15 is not
+ *      picked up by a 10:00 tick that finds today's digest unbuilt — it waits
+ *      for tomorrow's, with everything else from today. Without this, a quiet
+ *      night would make the first comment of the morning its own digest and
+ *      push the rest of the day to the next one: the time the mail arrives
+ *      would follow the traffic rather than the clock.
+ *   3. **Fold and record are one transaction.** The digest row's INSERT and
+ *      the `done` on the rows it lists commit together or not at all, so a
+ *      crash cannot fold rows into a digest that does not exist, nor build a
+ *      digest whose rows stay pending to be folded again tomorrow.
+ *
+ * Last-sent is therefore not a separate value anywhere: it IS the newest
+ * `comment.digest` row, and its status says whether it went — the outbox
+ * already holds what "when did we last send, and did it work" needs. The one
+ * schema change is 0008: a digest is the STUDIO's mail, not a site's, so its
+ * row carries no `project_id`, and deleting a site cannot cascade away a
+ * digest that also lists the others.
+ *
+ * Whatever runs the sweep runs this: the platform's daily cron (03:00 UTC in
+ * the scaffold, so the digest arrives then), the bin's hourly ticker (so the
+ * first tick after midnight), or `/api/jobs/run` by hand. NOT the drain a
+ * write starts (D119): a comment is never the reason to send a digest, and the
+ * drain running this would only find the day's window already closed.
+ */
+export const DIGEST_TOPIC = "comment.digest";
+/** The topic the folded rows carry — `notify.ts`'s, restated to avoid a cycle. */
+const COMMENT_TOPIC = "comment.created";
+/**
+ * How many comments the mail LISTS. Every pending row is folded and counted;
+ * past this the mail says how many more there are and links to the
+ * dashboard. The outbox's `CHECK (octet_length(event::text) <= 65536)` is the
+ * hard reason — a digest row over it would fail to insert and take the fold
+ * with it — and a mail of fifty excerpts is also past where anybody reads.
+ * At the clamps below an item is under 1 KB, so fifty fit with room.
+ */
+export const DIGEST_LISTED = 50;
+const EXCERPT_MAX = 140;
+const PAGE_MAX = 300;
+const NAME_MAX = 60;
+/** Midnight UTC at the start of `now`'s day — the close of the digest window. */
+export function digestCutoff(now) {
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+}
+export function digestKey(orgId, cutoff) {
+    return `${DIGEST_TOPIC}:${orgId}:${cutoff.toISOString().slice(0, 10)}`;
+}
+/**
+ * The job. Registered only in `digest` mode and only in the sweep
+ * (`jobs/set.ts`).
+ *
+ * `everyMs` is fifteen minutes and not a day, on purpose: the DAY is enforced
+ * by the dedupe key, not by the engine's schedule. A daily `everyMs` would
+ * make a cron that fires at 03:00:02 today and 03:00:01 tomorrow "not due",
+ * and skip a whole day for a second's jitter.
+ */
+export function buildDigests(mailer) {
+    return {
+        name: "digest-email",
+        everyMs: 15 * 60_000,
+        async run({ sql, now }) {
+            // No transport, no digest: the rows stay pending and are folded the
+            // first day there is a mailer, rather than into a digest nothing sends.
+            if (!isConfigured(mailer))
+                return { did: 0 };
+            const cutoff = digestCutoff(now);
+            const day = cutoff.toISOString().slice(0, 10);
+            // ONE ORG PER PASS, the delivery job's bargain: `more: true` and the
+            // engine drains. The NOT EXISTS is what makes an org that already has
+            // today's digest drop out, so a row that arrives late for a closed
+            // window cannot keep this job spinning on a conflict.
+            const [next] = await sql `
+        SELECT o.org_id
+          FROM outbox o
+         WHERE o.provider = 'email'
+           AND o.topic = ${COMMENT_TOPIC}
+           AND o.status = 'pending'
+           AND o.event->>'toReviewer' IS NULL
+           AND o.created_at < ${cutoff}
+           AND NOT EXISTS (
+             SELECT 1 FROM outbox d
+              WHERE d.provider = 'email'
+                AND d.dedupe_key = ${`${DIGEST_TOPIC}:`}::text || o.org_id::text || ${`:${day}`}::text
+           )
+         ORDER BY o.created_at
+         LIMIT 1`;
+            if (!next)
+                return { did: 0 };
+            const orgId = next.org_id;
+            /**
+             * The rows, LOCKED. `FOR UPDATE OF o` so that a delivery job switched
+             * to `each` mid-fold (an operator changing the variable and restarting
+             * one instance of several) cannot claim a row this digest is about to
+             * list; `SKIP LOCKED` so that the opposite case skips rather than waits.
+             */
+            const rows = await sql `
+        SELECT o.id, o.project_id, o.event,
+               p.name AS site_name, p.uid AS site_uid,
+               t.key AS thread_key, r.number AS round,
+               (p.deleted_at IS NOT NULL OR t.deleted_at IS NOT NULL OR c.deleted_at IS NOT NULL) AS gone
+          FROM outbox o
+          JOIN projects p ON p.id = o.project_id
+          LEFT JOIN threads t ON t.id = o.thread_id
+          LEFT JOIN rounds r ON r.id = t.round_id
+          LEFT JOIN comments c ON c.id = (
+            CASE WHEN o.event->>'commentId' ~ '^[0-9a-fA-F-]{36}$'
+                 THEN (o.event->>'commentId')::uuid END
+          )
+         WHERE o.org_id = ${orgId}
+           AND o.provider = 'email'
+           AND o.topic = ${COMMENT_TOPIC}
+           AND o.status = 'pending'
+           AND o.event->>'toReviewer' IS NULL
+           AND o.created_at < ${cutoff}
+         ORDER BY o.created_at
+         FOR UPDATE OF o SKIP LOCKED`;
+            // Every row locked by somebody else: they are working on it. Stop
+            // rather than ask again, or this pass would repeat until maxPasses.
+            if (rows.length === 0)
+                return { did: 0 };
+            // A comment deleted before its digest is not news. Dropped, with the
+            // status 07 §2.5 has for "nothing to send", rather than listed.
+            const gone = rows.filter((r) => r.gone).map((r) => r.id);
+            const live = rows.filter((r) => !r.gone);
+            if (gone.length) {
+                await sql `
+          UPDATE outbox SET status = 'dropped', last_error = 'deleted before the digest', completed_at = ${now}
+           WHERE id = ANY(${gone}::uuid[])`;
+            }
+            if (live.length === 0)
+                return { did: 0, more: true };
+            const event = fold(live, cutoff);
+            const [made] = await sql `
+        INSERT INTO outbox (id, org_id, project_id, thread_id, provider, topic, dedupe_key, event, next_attempt_at)
+        VALUES (
+          ${randomUUID()}, ${orgId},
+          -- No site: a digest is the STUDIO's mail, and 0008 lets this one
+          -- topic leave project_id empty. Pinning it to one of the sites it
+          -- lists would let deleting that site cascade the digest away, and
+          -- with it every other site's comments.
+          NULL,
+          NULL, 'email', ${DIGEST_TOPIC}, ${digestKey(orgId, cutoff)}, ${sql.json(event)},
+          -- The job's clock, not the database's: the delivery job claims with
+          -- next_attempt_at <= now in the same sweep, on the same clock.
+          ${now}
+        )
+        ON CONFLICT (provider, dedupe_key) DO NOTHING
+        RETURNING id`;
+            // Today's digest exists after all (NOT EXISTS above is a read; this is
+            // the constraint). Leave the rows pending for tomorrow's: folding them
+            // into nothing would be mail that silently never happens.
+            if (!made)
+                return { did: 0 };
+            /**
+             * `done`, because their news now lives in the digest row, which carries
+             * its own status. A digest that fails for good is `failed` and stays on
+             * the list of mail that never sent; marking these rows anything that
+             * the delivery job would pick up again is how one comment reaches the
+             * owner twice.
+             */
+            await sql `
+        UPDATE outbox SET status = 'done', completed_at = ${now}, last_error = NULL
+         WHERE id = ANY(${live.map((r) => r.id)}::uuid[])`;
+            return { did: 1, more: true, note: `digest of ${live.length} comment(s) queued for one owner` };
+        },
+    };
+}
+/**
+ * Pending rows → the digest's event, grouped by site, oldest first.
+ *
+ * The excerpt is REDACTED HERE, before it is clamped — the order matters.
+ * Clamping first can cut an address or a token in half, and half a token is
+ * one the redactor no longer recognises, so the mail would carry the half.
+ */
+function fold(rows, cutoff) {
+    const bySite = new Map();
+    let listed = 0;
+    for (const r of rows) {
+        let site = bySite.get(r.project_id);
+        if (!site) {
+            site = { name: clip(r.site_name, NAME_MAX), uid: r.site_uid, count: 0, items: [] };
+            bySite.set(r.project_id, site);
+        }
+        site.count++;
+        if (listed >= DIGEST_LISTED)
+            continue;
+        listed++;
+        site.items.push({
+            threadKey: clip(r.thread_key ?? r.event.threadKey ?? "a snag", 24),
+            round: r.round,
+            author: clip(r.event.authorName ?? "Someone", NAME_MAX),
+            excerpt: sanitiseWithRedactor(r.event.body ?? "", "plain", redactText, { singleLine: true, max: EXCERPT_MAX }),
+            page: clip(r.event.pageUrl ?? "", PAGE_MAX),
+        });
+    }
+    return { digest: true, through: cutoff.toISOString(), total: rows.length, sites: [...bySite.values()] };
+}
+const clip = (s, max) => (s.length > max ? s.slice(0, max) : s);
+/**
+ * The digest as it should be sent NOW: without the sites deleted since it was
+ * folded. Null when none is left, which the delivery job drops.
+ *
+ * Read at send time because the gap is real — a digest folded at 00:05 can be
+ * waiting on a rate limit or a retry when the owner deletes a site — and a
+ * mail that lists a deleted site's comments links to a page that no longer
+ * opens. A site delete is SOFT (`routes/sites.ts`), so it is `deleted_at` that
+ * removes it here; a site removed outright is simply not found. Its folded
+ * comment rows stay `done`: they were news about a site the owner has since
+ * decided they do not want, and re-queueing them would be mail about nothing.
+ */
+export async function pruneDigest(sql, orgId, event) {
+    const uids = (event.sites ?? []).map((s) => s.uid);
+    if (uids.length === 0)
+        return null;
+    const alive = new Set((await sql `
+        SELECT uid FROM projects
+         WHERE org_id = ${orgId} AND uid = ANY(${uids}::text[]) AND deleted_at IS NULL`).map((r) => r.uid));
+    const sites = event.sites.filter((s) => alive.has(s.uid));
+    if (sites.length === 0)
+        return null;
+    if (sites.length === event.sites.length)
+        return event;
+    return { ...event, sites, total: sites.reduce((n, s) => n + s.count, 0) };
+}
+/**
+ * The digest mail. Text only, like every other mail here, and for the same
+ * reason: who, where, what and a link need no `<div>`.
+ *
+ * Every stored string is sanitised again on the way out, as the per-comment
+ * mail does. The excerpt was already redacted at fold time; sanitising it a
+ * second time is cheap and means this function never has to trust its input.
+ */
+export function renderDigest(event, to, baseUrl) {
+    const plain = (s, max) => sanitise(s, "plain", { singleLine: true, max });
+    const sites = event.sites;
+    const n = event.total;
+    const comments = n === 1 ? "1 new comment" : `${n} new comments`;
+    const subject = sites.length === 1
+        ? `${comments} on ${plain(sites[0].name, NAME_MAX)}`
+        : `${comments} across ${sites.length} sites`;
+    const lines = [`${comments} since the last digest.`, ""];
+    let listed = 0;
+    for (const site of sites) {
+        lines.push(`${plain(site.name, NAME_MAX)} (${site.count})`);
+        for (const item of site.items) {
+            listed++;
+            const key = plain(item.threadKey, 24);
+            lines.push(`  ${key} · ${plain(item.author, NAME_MAX)}: ${plain(item.excerpt, EXCERPT_MAX + 1)}`, ...(item.page ? [`    On the page: ${plain(item.page, PAGE_MAX)}`] : []), `    ${threadUrl(baseUrl, site.uid, item.threadKey, item.round)}`);
+        }
+        lines.push("");
+    }
+    if (n > listed)
+        lines.push(`…and ${n - listed} more not listed here.`, "");
+    lines.push(`Open the dashboard: ${dashboardUrl(baseUrl)}`, "", "— Snagset", "You get this at most once a day. For one email per comment instead, set SNAGSET_MAIL_NOTIFY=each.");
+    return { to, subject, text: lines.join("\n") };
+}
+//# sourceMappingURL=digest.js.map

package/dist/mail/digest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.js","sourceRoot":"","sources":["../../src/mail/digest.ts"],"names":[],"mappings":"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"}

package/dist/mail/links.js

@@ -0,0 +1,41 @@
+/**
+ * Where a notification's link goes: the thread, open, in the dashboard (D120).
+ *
+ * Until D120 every mail linked `<address>/dashboard`, and the dashboard is
+ * served at the ROOT of the address (`app.ts`'s fallback, 08 §3), so that link
+ * landed on a route the SPA does not have. The comments page has always taken
+ * the thread as a search parameter — every view there is a link, D87 — and the
+ * round with it, because the list shows the latest round unless told
+ * otherwise, and a thread from an earlier round would open to nothing.
+ *
+ * One function for both mails, the per-comment one and the digest, so the two
+ * cannot drift into linking different places for the same thread.
+ */
+export function threadUrl(baseUrl, site, key, round) {
+    const q = new URLSearchParams({ thread: key });
+    if (round !== null)
+        q.set("round", String(round));
+    return `${baseUrl}/s/${encodeURIComponent(site)}/comments?${q.toString()}`;
+}
+/** The dashboard itself — what a mail links to when it is about no one thread. */
+export function dashboardUrl(baseUrl) {
+    return `${baseUrl}/`;
+}
+/**
+ * The link for a row that names a thread, read at SEND time: the round and
+ * the site's uid are not in the event, and a row queued before D120 has
+ * neither. A thread that has gone since falls back to the dashboard rather
+ * than to a link that opens nothing.
+ */
+export async function threadLink(sql, threadId, baseUrl) {
+    if (!threadId)
+        return dashboardUrl(baseUrl);
+    const [t] = await sql `
+    SELECT p.uid, t.key, r.number AS round
+      FROM threads t
+      JOIN projects p ON p.id = t.project_id
+      LEFT JOIN rounds r ON r.id = t.round_id
+     WHERE t.id = ${threadId}::uuid AND t.deleted_at IS NULL`;
+    return t ? threadUrl(baseUrl, t.uid, t.key, t.round) : dashboardUrl(baseUrl);
+}
+//# sourceMappingURL=links.js.map

package/dist/mail/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../src/mail/links.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,IAAY,EAAE,GAAW,EAAE,KAAoB;IACxF,MAAM,CAAC,GAAG,IAAI,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IAC/C,IAAI,KAAK,KAAK,IAAI;QAAE,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAClD,OAAO,GAAG,OAAO,MAAM,kBAAkB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC7E,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,GAAG,OAAO,GAAG,CAAC;AACvB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAA2C,EAC3C,QAAuB,EACvB,OAAe;IAEf,IAAI,CAAC,QAAQ;QAAE,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,CAAsD;;;;;oBAKzD,QAAQ,iCAAiC,CAAC;IAC5D,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;AAC/E,CAAC"}

package/dist/mail/notify.js

@@ -4,6 +4,8 @@ import { redactText } from "../vendor/widget/predicates.js";
 import { noteQueued } from "../jobs/soon.js";
 import { isConfigured } from "./mailer.js";
 import { unsubscribeHeaders, unsubscribeToken } from "./unsubscribe.js";
+import { DIGEST_TOPIC, pruneDigest, renderDigest } from "./digest.js";
+import { threadLink } from "./links.js";
 /**
  * Notification email — L1.4, and deliberately ONE event.
  *
@@ -16,6 +18,13 @@ import { unsubscribeHeaders, unsubscribeToken } from "./unsubscribe.js";
  * does not exist yet. The rest lands with full M2-32, behind subscription and
  * unsubscribe.
  *
+ * Since D120 the owner's half arrives as a DAILY DIGEST by default
+ * (`SNAGSET_MAIL_NOTIFY=digest`, 08 §4.8): the rows below are queued exactly
+ * as before, the delivery job leaves them alone, and `digest.ts` folds a day's
+ * worth into one outbox row of its own. `each` restores one mail per comment.
+ * In both modes nobody is mailed about a comment they wrote — see
+ * `queueCommentNotice`.
+ *
  * ── HOW "A RETRY NEVER DOUBLE-SENDS" IS ACTUALLY ACHIEVED ──
  *
  * Two mechanisms, and both are needed:
@@ -58,18 +67,37 @@ export async function queueCommentNotice(tx, notice, id) {
         pageUrl: notice.pageUrl,
         commentId: notice.commentId,
     };
-    // THE OWNER's row. No recipient in the event: the delivery job reads that
-    // absence as "the project owner", which is what every row queued before
-    // this fan-out existed also means. Backward compatibility by shape rather
-    // than by version flag.
-    await tx `
-    INSERT INTO outbox (id, org_id, project_id, thread_id, provider, topic, dedupe_key, event)
-    VALUES (
-      ${id}, ${notice.orgId}, ${notice.projectId}, ${notice.threadId},
-      'email', ${TOPIC}, ${`${TOPIC}:${notice.commentId}`}, ${tx.json(payload)}
-    )
-    ON CONFLICT (provider, dedupe_key) DO NOTHING
-  `;
+    const owner = await ownerOf(tx, notice.orgId);
+    const author = await reviewerIdentity(tx, notice.authorId);
+    /**
+     * THE OWNER's row — unless the owner wrote this comment (D120).
+     *
+     * "If there is a comment we made, we don't need to receive the email." The
+     * owner writes in two ways and both are theirs: from the dashboard, where
+     * the author is their studio reviewer row (`user_id` set), and through the
+     * widget on their own site, where the author is whatever reviewer identity
+     * they typed — "eurico-test" — with their own address in it. The first is
+     * matched by user id, the second by address, case-insensitively, because an
+     * address typed into a widget has whatever capitals the hand gave it.
+     *
+     * Decided HERE, at enqueue, rather than at send: the row that is never
+     * written is the one that cannot be sent in `each` mode and cannot be folded
+     * into a digest in `digest` mode, so one check covers both.
+     *
+     * No recipient in the event: the delivery job reads that absence as "the
+     * project owner", which is what every row queued before the fan-out existed
+     * also means. Backward compatibility by shape rather than by version flag.
+     */
+    if (!isSamePerson(author, owner)) {
+        await tx `
+      INSERT INTO outbox (id, org_id, project_id, thread_id, provider, topic, dedupe_key, event)
+      VALUES (
+        ${id}, ${notice.orgId}, ${notice.projectId}, ${notice.threadId},
+        'email', ${TOPIC}, ${`${TOPIC}:${notice.commentId}`}, ${tx.json(payload)}
+      )
+      ON CONFLICT (provider, dedupe_key) DO NOTHING
+    `;
+    }
     /**
      * …and ONE ROW PER PARTICIPANT — B2's "created or replied".
      *
@@ -87,6 +115,12 @@ export async function queueCommentNotice(tx, notice, id) {
      * Excluded: the author of this very comment (nobody needs mail about their
      * own typing), anyone with no address, anyone who unsubscribed, and anyone
      * blocked or erased.
+     *
+     * …and THE OWNER, under any identity (D120). The owner already has the row
+     * above; if they have also replied on this thread from the dashboard, their
+     * studio reviewer row is a participant too, and without this they got the
+     * same comment twice — and in `digest` mode the participant copy would have
+     * arrived at once, around the digest that exists to stop exactly that.
      */
     await fanOut(tx, {
         orgId: notice.orgId,
@@ -95,6 +129,8 @@ export async function queueCommentNotice(tx, notice, id) {
         topic: TOPIC,
         keyPrefix: `${TOPIC}:${notice.commentId}`,
         exclude: notice.authorId,
+        excludeEmail: author?.email ?? null,
+        excludeOwner: owner,
         payload,
     });
     // D119: the request drains this once its response is ready.
@@ -109,6 +145,9 @@ export async function queueCommentNotice(tx, notice, id) {
  * somebody who did not ask.
  */
 async function fanOut(tx, o) {
+    const email = o.excludeEmail ?? null;
+    const ownerUser = o.excludeOwner?.userId ?? null;
+    const ownerEmail = o.excludeOwner?.email ?? null;
     const participants = await tx `
     SELECT DISTINCT r.id
       FROM comments c
@@ -120,6 +159,9 @@ async function fanOut(tx, o) {
        AND r.notifications_off_at IS NULL
        AND r.blocked_at IS NULL
        AND r.erased_at IS NULL
+       AND (${email}::text IS NULL OR lower(r.email) <> lower(${email}::text))
+       AND (${ownerUser}::uuid IS NULL OR r.user_id IS DISTINCT FROM ${ownerUser}::uuid)
+       AND (${ownerEmail}::text IS NULL OR lower(r.email) <> lower(${ownerEmail}::text))
   `;
     for (const p of participants) {
         await tx `
@@ -133,6 +175,40 @@ async function fanOut(tx, o) {
     `;
     }
 }
+/**
+ * THE owner of an org — the first `owner` membership, as it has always been
+ * chosen for owner mail. One query in one place, because "who is the owner"
+ * answered differently at enqueue (am I mailing myself?) and at send (whom do
+ * I mail?) is how the self-check passes and the mail still arrives.
+ */
+export async function ownerOf(sql, orgId) {
+    const [owner] = await sql `
+    SELECT u.id AS user_id, u.email
+      FROM memberships m
+      JOIN users u ON u.id = m.user_id
+     WHERE m.org_id = ${orgId} AND m.role = 'owner' AND u.deleted_at IS NULL
+     ORDER BY m.created_at
+     LIMIT 1`;
+    return owner ? { userId: owner.user_id, email: owner.email } : null;
+}
+/** A reviewer row's link to a person: the dashboard user behind it, and its address. */
+async function reviewerIdentity(sql, reviewerId) {
+    const [r] = await sql `
+    SELECT user_id, email FROM reviewers WHERE id = ${reviewerId}::uuid`;
+    return r ? { userId: r.user_id, email: r.email } : null;
+}
+/**
+ * Is this reviewer identity the owner? By user id first — the studio row the
+ * dashboard writes with — and then by address, case-insensitively, which is
+ * what catches the owner reviewing their own site through the widget.
+ */
+export function isSamePerson(who, owner) {
+    if (!who || !owner)
+        return false;
+    if (who.userId && who.userId === owner.userId)
+        return true;
+    return !!who.email && who.email.trim().toLowerCase() === owner.email.trim().toLowerCase();
+}
 const RESOLVED = "thread.resolved";
 /**
  * "Somebody marked your snag resolved" — B2's second topic.
@@ -157,6 +233,8 @@ export async function queueResolvedNotice(tx, notice) {
         topic: RESOLVED,
         keyPrefix: `${RESOLVED}:${notice.threadId}:${notice.version}`,
         exclude: notice.actorId,
+        // The person who clicked, under any identity — the same rule as a comment.
+        excludeEmail: (await reviewerIdentity(tx, notice.actorId))?.email ?? null,
         payload: {
             threadKey: notice.threadKey,
             actorName: notice.actorName,
@@ -173,8 +251,14 @@ const BACKOFF_MIN = [1, 5, 15, 30, 60];
 /**
  * The delivery job. Registered only when a mailer is configured — with none,
  * there is nothing to drain and the absence is reported at boot instead.
+ *
+ * `notify` defaults to `each` HERE — the job's behaviour before D120, for a
+ * caller that does not say — while the PRODUCT's default is `digest`, which
+ * `jobs/set.ts` reads from the registry. The registry is where a default an
+ * operator can see belongs; a function's default is only what it does when
+ * nobody asked.
  */
-export function deliverEmail(mailer, address, keys) {
+export function deliverEmail(mailer, address, keys, notify = "each") {
     return {
         name: "deliver-email",
         everyMs: 30_000,
@@ -187,6 +271,11 @@ export function deliverEmail(mailer, address, keys) {
             // that one provider timeout takes the whole batch's rows to `inflight`
             // with nothing sent. One row per pass, `more: true` to drain — the
             // engine's batching, reused rather than reinvented.
+            //
+            // In `digest` mode the owner's comment rows are NOT claimable: they wait
+            // for `digest.ts` to fold them. Excluded in the claim itself rather than
+            // claimed and put back, because a row moved to `inflight` and back is a
+            // row the "never twice" machinery has to reason about for nothing.
             const [row] = await sql `
         UPDATE outbox SET status = 'inflight', attempts = attempts + 1
          WHERE id = (
@@ -194,11 +283,12 @@ export function deliverEmail(mailer, address, keys) {
             WHERE provider = 'email'
               AND status = 'pending'
               AND next_attempt_at <= ${now}
+              ${notify === "digest" ? sql `AND NOT (topic = ${TOPIC} AND event->>'toReviewer' IS NULL)` : sql ``}
             ORDER BY next_attempt_at
             FOR UPDATE SKIP LOCKED
             LIMIT 1
          )
-        RETURNING id, org_id, project_id, thread_id, attempts, event
+        RETURNING id, org_id, project_id, thread_id, topic, attempts, event
       `;
             if (!row)
                 return { did: 0 };
@@ -217,6 +307,17 @@ export function deliverEmail(mailer, address, keys) {
                 await sql `UPDATE outbox SET status = 'dropped', last_error = 'no deliverable recipient', completed_at = ${now} WHERE id = ${row.id}`;
                 return { did: 0, more: true, note: "one notification had no recipient — dropped" };
             }
+            // A digest without the sites deleted since it was folded; with none
+            // left there is nothing to say, and it is dropped before it can count
+            // against the address's allowance.
+            let digest = null;
+            if (row.topic === DIGEST_TOPIC) {
+                digest = await pruneDigest(sql, row.org_id, row.event);
+                if (!digest) {
+                    await sql `UPDATE outbox SET status = 'dropped', last_error = 'every site in the digest was deleted', completed_at = ${now} WHERE id = ${row.id}`;
+                    return { did: 0, more: true, note: "one digest listed only deleted sites — dropped" };
+                }
+            }
             /**
              * PER-ADDRESS RATE LIMIT — B2's last piece.
              *
@@ -241,8 +342,14 @@ export function deliverEmail(mailer, address, keys) {
            WHERE id = ${row.id}`;
                 return { did: 0, more: true, note: "one notification deferred — address over its hourly rate" };
             }
+            // The digest is its own message (`digest.ts`); every other row links
+            // to its thread, read now — outside the `try`, because a failing read
+            // is the database's problem, not a send to back off from.
+            const mail = digest
+                ? renderDigest(digest, to.email, baseUrl)
+                : render(row, to.email, await threadLink(sql, row.thread_id, baseUrl));
             try {
-                await mailer.send({ ...render(row, to.email, baseUrl), ...(to.headers ? { headers: to.headers } : {}) });
+                await mailer.send({ ...mail, ...(to.headers ? { headers: to.headers } : {}) });
                 await sql `
           UPDATE outbox SET status = 'done', completed_at = ${now}, last_error = NULL
            WHERE id = ${row.id}`;
@@ -341,13 +448,7 @@ async function recipient(sql, row, keys, baseUrl) {
             ? { email: r.email, headers: unsubscribeHeaders(baseUrl, unsubscribeToken(keys, reviewerId)) }
             : { email: r.email };
     }
-    const [owner] = await sql `
-    SELECT u.email
-      FROM memberships m
-      JOIN users u ON u.id = m.user_id
-     WHERE m.org_id = ${row.org_id} AND m.role = 'owner' AND u.deleted_at IS NULL
-     ORDER BY m.created_at
-     LIMIT 1`;
+    const owner = await ownerOf(sql, row.org_id);
     return owner ? { email: owner.email } : null;
 }
 /**
@@ -363,7 +464,7 @@ async function recipient(sql, row, keys, baseUrl) {
  * the ones above, and the message is four lines: who, where, what, and a link.
  * There is nothing here that a `<div>` would make clearer.
  */
-function render(row, to, baseUrl) {
+function render(row, to, link) {
     const key = sanitise(row.event.threadKey ?? "a snag", "plain", { singleLine: true, max: 24 });
     const author = sanitise(row.event.authorName ?? "Someone", "plain", { singleLine: true, max: 60 });
     const body = sanitiseWithRedactor(row.event.body ?? "", "plain", redactText, { max: 2000 });
@@ -383,7 +484,7 @@ function render(row, to, baseUrl) {
                 `${actor} marked ${key} resolved.`,
                 "",
                 page ? `On the page: ${page}` : "",
-                `See the round: ${baseUrl}/dashboard`,
+                `See the thread: ${link}`,
                 "",
                 "— Snagset",
             ]
@@ -400,7 +501,7 @@ function render(row, to, baseUrl) {
             body,
             "",
             page ? `On the page: ${page}` : "",
-            `Open the review: ${baseUrl}/dashboard`,
+            `Open the thread: ${link}`,
             "",
             "— Snagset",
         ]