@snagset/server 0.1.16 → 0.1.19

package/dist/routes/threads.js

@@ -13,13 +13,13 @@ import { queueIntegrationEvent } from "../integrations/outbox.js";
 import { inOrg } from "../db/scope.js";
 import { isStudioModerator } from "../studioReviewers.js";
 /**
- * Wire id ⇄ row id — 05 §3.5, verbatim: *"id uuid PRIMARY KEY — client-minted
+ * Wire id ⇄ row id, verbatim: *"id uuid PRIMARY KEY — client-minted
  * UUIDv7; wire form 'thr_…'"*.
  *
  * The row is a bare uuid so it indexes and joins as one; the prefixed form is
  * the identity everything OUTSIDE the database uses, because a bare uuid in a
  * webhook payload, a GitHub issue marker or a support ticket tells you nothing
- * about what you are looking at (foundations §2.10).
+ * about what you are looking at.
  *
  * Both directions live here rather than at each call site. The widget mints
  * the id, so the very first POST arrives prefixed, and a server that stores
@@ -34,10 +34,10 @@ function rowId(wire, prefix) {
 }
 const wireId_ = (row, prefix) => prefix + row;
 /**
- * §2.2's envelope. `details` was missing from this file's copy while
+ * The envelope. `details` was missing from this file's copy while
  * `comments.ts` had it, so every `field_not_permitted` here — including the
  * long-standing refusal to move a thread between rounds — shipped without the
- * `details.field` §6.9 registers for that code. A client cannot mark the
+ * `details.field` registers for that code. A client cannot mark the
  * offending input without it.
  */
 function fail(c, status, code, message, details) {
@@ -45,8 +45,8 @@ function fail(c, status, code, message, details) {
 }
 /**
  * Every request runs inside a transaction with `app.org_id` set, which is what
- * makes 08 §9.2's RLS policies do anything at all. It is set even where the
- * connecting role can bypass them (D50) — the day someone points DATABASE_URL
+ * makes the RLS policies do anything at all. It is set even where the
+ * connecting role can bypass them — the day someone points DATABASE_URL
  * at a properly restricted role, every query here has to already be correct,
  * and a `SET LOCAL` added later would be added under incident conditions.
  */
@@ -58,12 +58,12 @@ function fail(c, status, code, message, details) {
  * added to each by hand after a link session's list was caught carrying a
  * private reply: a rule answered in three places drifts.
  *
- * ── TEAM-ONLY (05 §6.4a) ──
+ * ── TEAM-ONLY ──
  *
  * A `private` reply is for the studio's eyes and never reaches a reviewer
  * session or an agent. The owner sees all of them.
  *
- * ── TOMBSTONES, FOR THE OWNER ONLY (§3.11) ──
+ * ── TOMBSTONES, FOR THE OWNER ONLY ──
  *
  * A deleted comment is a row with `body` NULL. Everyone else gets it filtered
  * out, as before — the widget drops it and has nothing to render a hole with.
@@ -74,10 +74,10 @@ function fail(c, status, code, message, details) {
  * on the studio's screen as a tombstone exactly until the next poll replaced
  * the row, and then gone.
  *
- * The tombstone is §3.11's shape — id, NULL body, deletedAt, the author's
- * NAME only — plus `createdAt`, which §3.11 leaves out and the studio needs:
+ * The tombstone is the shape — id, NULL body, deletedAt, the author's
+ * NAME only — plus `createdAt`, which leaves out and the studio needs:
  * a hole is placed in time by when it was written. `seq` stays server-side
- * for §3.11's reason, and the author's id and kind go with the words.
+ * for the reason, and the author's id and kind go with the words.
  */
 function commentsJson(tx, asOwner) {
     return tx `COALESCE(
@@ -97,7 +97,7 @@ function commentsJson(tx, asOwner) {
     '[]'::json)`;
 }
 export function threadRoutes(sql, 
-/** The 10-second cache (05 §4.4), not a fresh SELECT per handler. Every
+/** The 10-second cache, not a fresh SELECT per handler. Every
  *  route here starts by resolving `{uid}`, and on a database one round trip
  *  away that lookup was costing more than the work it introduced. */
 projects, 
@@ -106,8 +106,8 @@ projects,
  *  not need to know how storage is configured. */
 features, 
 /**
- * Is a mail transport configured (08 §4.8)? Same gate `commentRoutes` takes,
- * and for the same reason: with no transport, 08 §4.8 wants notifications
+ * Is a mail transport configured ? Same gate `commentRoutes` takes,
+ * and for the same reason: with no transport, the design wants notifications
  * "off and say so, rather than silently queueing" — rows that would otherwise
  * accumulate for the life of the install and arrive in one burst the day
  * somebody configures Resend.
@@ -116,12 +116,12 @@ notifications = async () => false,
 /** Where this instance lives (SNAGSET_BASE_URL) — the brief's screenshot links are absolute. */
 baseUrl = async () => "http://localhost:8080", 
 /**
- * D95/D97: the site's tracker connections — id, provider, and whether
+ * The site's tracker connections — id, provider, and whether
  * issues are made on every new thread. Injected so this file never opens
  * a token; the worker does that.
  */
 trackers = async () => [], 
-/** D123: how long an assignment waits before its email (SNAGSET_ASSIGN_MAIL_DELAY_S). */
+/** How long an assignment waits before its email (SNAGSET_ASSIGN_MAIL_DELAY_S). */
 assignDelayMs) {
     const app = new Hono();
     /** Resolve `{uid}`, and 404 rather than leak whether a uid exists. */
@@ -132,7 +132,7 @@ assignDelayMs) {
     // request and, worse, ran AFTER the real one and overwrote
     // `Access-Control-Allow-Headers` with a hand-typed `content-type` — harmless
     // only because a preflight never reaches this far.
-    /** 05 §6.1 — what the widget reads at mount to know what this deployment can do. */
+    /** What the widget reads at mount to know what this deployment can do. */
     app.get("/api/v1/projects/:uid/config", async (c) => {
         const p = await project(c.req.param("uid"));
         if (!p)
@@ -140,7 +140,7 @@ assignDelayMs) {
         c.header("x-snagset-config-version", String(p.config_version));
         c.header("ETag", `"${p.config_etag}"`);
         /**
-         * CACHEABLE, briefly — D66 makes this the stub's visibility check, fetched
+         * CACHEABLE, briefly — the decision makes this the stub's visibility check, fetched
          * once per visitor per page-load-cluster rather than per page. 60 seconds:
          * long enough that a browsing session costs one request, short enough that
          * flipping the audience in the dashboard lands within a minute.
@@ -151,7 +151,7 @@ assignDelayMs) {
         // full body to a stranger origin, and the split below would be theatre.
         c.header("Vary", "Origin");
         /**
-         * 05 §7.2's ORIGIN-AWARE BODY, finally conformed to (D69) — Eurico's
+         * The ORIGIN-AWARE BODY, finally conformed to — the maintainer's
          * question, verbatim: "the api gets the url that should be there and then
          * just validates in the frontend?" Which is this design: the server never
          * learns the page's URL (the browser sends only its origin, which CORS
@@ -161,14 +161,14 @@ assignDelayMs) {
          * for it is printed in their page source.
          *
          * A stranger origin still gets a 200 with the public subset (writeMode
-         * included) rather than a 403: the fetch is also how D2's origin
+         * included) rather than a 403: the fetch is also how the origin
          * suggestion is born, and the stub on an archive.org mirror needs a
          * readable "writable: false" to stay dormant — a CORS-omitted header would
          * do that too, but this route is public-read so the suggestion flow works.
          * `originAllowed` is absent (never false) when there is no Origin header:
          * same-origin pages and curl are not strangers.
          */
-        // D91 — the switch, 05 §4.9 layer 6: a paused site is writable from
+        // The switch, layer 6: a paused site is writable from
         // nowhere, and the stub reads `writable` and stays dormant. Said before
         // the origin verdict, because "switched off" is the more useful sentence.
         const paused = p.status !== "active";
@@ -182,9 +182,9 @@ assignDelayMs) {
             // mode is a complete product, not a degraded one.
             features: await features(p.org_id),
             /**
-             * EFFECTIVE, not the raw column — D66 turns this field into the thing
+             * EFFECTIVE, not the raw column — turns this field into the thing
              * that decides whether every visitor sees the toolbar, and the raw value
-             * lies during D1's grace: a site 25 hours old still says `open` while
+             * lies during the grace: a site 25 hours old still says `open` while
              * every write is already refused. The session route learned this first
              * (see effectiveWriteMode's own comment); the config route repeating the
              * raw column would show a toolbar nobody can type into.
@@ -194,13 +194,15 @@ assignDelayMs) {
         };
         if (!writable)
             return c.json({ ...base, reason: paused ? "project_paused" : "origin_not_allowed" });
-        // T10/M2-22: the round HISTORY rides the config the widget already fetches
+        // T10/: the round HISTORY rides the config the widget already fetches
         // at mount, so the dock's selector costs no extra request. Behind the
-        // origin split with `keyPrefix` (§7.2): the least sensitive PRIVATE things
-        // on the project, which is not the same as public.
+        // origin split with `keyPrefix`: the least sensitive PRIVATE things
+        // on the project, which is not the same as public. An ARCHIVED round is
+        // left out: the studio put it away, and the selector is where it
+        // would otherwise come back for every reviewer.
         const rounds = await inOrg(sql, p.org_id, (tx) => tx `
       SELECT number, name, closed_at IS NOT NULL AS closed
-      FROM rounds WHERE project_id = ${p.id} AND deleted_at IS NULL
+      FROM rounds WHERE project_id = ${p.id} AND deleted_at IS NULL AND archived_at IS NULL
       ORDER BY number DESC
     `);
         return c.json({
@@ -210,7 +212,7 @@ assignDelayMs) {
         });
     });
     /**
-     * 05 §6.4 — the list, endpoint 7, which the route table marks **W/D**.
+     * The list, endpoint 7, which the route table marks **W/D**.
      *
      * ONE endpoint, TWO audiences, and the credential decides the scope. That is
      * the spec's design and not a shortcut: a dashboard is not a different kind
@@ -227,7 +229,7 @@ assignDelayMs) {
      * cross-origin credentialed read is refused by the browser whatever this
      * returns.
      *
-     * `route` is the generated projection off the anchor (§3.5), so filtering by
+     * `route` is the generated projection off the anchor, so filtering by
      * it is an index scan rather than a JSONB walk on every row.
      */
     app.get("/api/v1/projects/:uid/threads", async (c) => {
@@ -241,7 +243,7 @@ assignDelayMs) {
         const owner = c.get("owner");
         const asOwner = !!owner && owner.orgId === p.org_id;
         /**
-         * An MCP token with `threads:read` (07 §8.2) reads with the studio's
+         * An MCP token with `threads:read` reads with the studio's
          * FILTERS but not the studio's PRIVACY, and the split is deliberate.
          *
          * Filters: an agent asked to "list the open snags on checkout" needs
@@ -249,10 +251,10 @@ assignDelayMs) {
          * Denying those would make `list_threads` return the latest open round of
          * the default environment and call it the project.
          *
-         * Privacy: `private` threads and team-only replies (§6.4a) stay OUT. 07's
+         * Privacy: `private` threads and team-only replies stay OUT. The
          * scope table grants "list and read threads, comments, anchor state" and
-         * says nothing about private, while §8.6 mitigation 7 is *scope
-         * minimalism* and §8.2 separates `context:read` precisely because the
+         * says nothing about private, while the design is *scope
+         * minimalism* and separates `context:read` precisely because the
          * personal-data-bearing half should not ride along by default. A team-only
          * note is the studio talking about the client; an agent that reads one and
          * quotes it into a pull request has published it.
@@ -268,8 +270,8 @@ assignDelayMs) {
         // Better a sentence naming the missing scope than a confident short list.
         if (mcp && !asAgent)
             return scopeDenied(c, "threads:read");
-        // §6.4's filters. `status` and `q` stay dashboard-only. `round` used to be
-        // gated the same way (`asOwner ? … : null`), which is the M2-22 bug: a
+        // The filters. `status` and `q` stay dashboard-only. `round` used to be
+        // gated the same way (`asOwner ? …: null`), which is the bug: a
         // review-link session's `?round` was silently discarded and every reader
         // without an owner cookie saw every round's pins forever, including ones
         // long since closed. A reviewer session may now ask for a round exactly
@@ -279,7 +281,7 @@ assignDelayMs) {
         const requestedRound = Number(c.req.query("round")) || null;
         const q = asStudio ? (c.req.query("q") ?? "").trim() : "";
         /**
-         * `?assignee=rev_…|unassigned` — 05 §6.4b's triage filter ("what has
+         * `?assignee=rev_…|unassigned` — the triage filter ("what has
          * nobody picked up"). `unassigned` is a word rather than an empty value
          * because `assignee=` with nothing after it is indistinguishable from an
          * absent parameter on the wire. Studio-only, like status and q: a filter
@@ -294,7 +296,7 @@ assignDelayMs) {
             }
         }
         /**
-         * `?since=` — 05 §6.3's delta poll, and A10's whole realtime story.
+         * `?since=` — the delta poll, and the whole realtime story.
          *
          * *"`GET …/threads?since=<iso>` returns everything with `updated_at >
          * since`, plus the `deleted[]` tombstone array. The client keeps
@@ -306,14 +308,14 @@ assignDelayMs) {
          * forever in a background tab.
          */
         /**
-         * `?key=SN-14` — 05 §6.3's server-side permalink, and the thing that makes
+         * `?key=SN-14` — the server-side permalink, and the thing that makes
          * a shared link survive a round.
          *
          * `?snag_t=SN-14` resolves LOCALLY in the widget, against the list it
          * already holds. That list is round-scoped: a non-owner reader defaults to
          * the latest OPEN round. So a permalink to a thread from a closed round —
          * which is most permalinks anyone bothers to share, since they share the
-         * ones that mattered — found nothing and showed F-06's "we could not find
+         * ones that mattered — found nothing and showed F-the "we could not find
          * that comment". The thread was there the whole time, one round back.
          *
          * An exact match on `UNIQUE (project_id, key)`, so at most one row, and it
@@ -321,7 +323,7 @@ assignDelayMs) {
          * named a specific thread, which is a stronger statement of intent than
          * any default. Privacy is not ignored — a private thread is absent for a
          * non-owner, which reads as "no such key" rather than confirming it exists
-         * (§6.4a's rule for `GET /threads/{id}`).
+         * (the rule for `GET /threads/{id}`).
          */
         const key = c.req.query("key")?.trim().toUpperCase();
         const sinceRaw = c.req.query("since");
@@ -336,7 +338,7 @@ assignDelayMs) {
         /**
          * ── WHY `visible` IS A COLUMN AND NOT A FILTER ──
          *
-         * 05 §6.4a, acceptance A36: a thread the studio marks `private` must land
+         * Acceptance A36: a thread the studio marks `private` must land
          * in the caller's `deleted[]` so a cached copy is DROPPED. With the
          * predicate in the WHERE clause the row simply stops being returned, which
          * is indistinguishable from "nothing changed" — the client keeps showing a
@@ -345,7 +347,7 @@ assignDelayMs) {
          *
          * Only the two genuine VISIBILITY conditions are computed. Status, search,
          * environment and round are FILTERS: status does not hide a thread, and a
-         * thread can never change environment or round (D2 — `environment_id` is
+         * thread can never change environment or round (`environment_id` is
          * set at creation and a thread never moves), so none of them can take a
          * client from seeing a thread to not seeing it.
          *
@@ -356,6 +358,29 @@ assignDelayMs) {
          * explanation.
          */
         const rows = await inOrg(sql, p.org_id, async (tx) => {
+            // Absent round query param: an OWNER still sees every round
+            // (unchanged), but a non-owner reader defaults to the latest OPEN
+            // round, so a fresh page load is -clean rather than showing a round
+            // that closed weeks ago. Not an archived or deleted one either:
+            // the same round a new thread would land in. The correlated subquery is
+            // cheap — one project's round table is a handful of rows.
+            //
+            // ON A POLL the predicate moves into `visible`, like privacy does: a
+            // thread the studio MOVED to another round has to come back as a
+            // tombstone for the list it left, and a WHERE clause would only make it
+            // vanish from the delta, so the old round's list kept showing it.
+            const inRound = key
+                ? null
+                : requestedRound
+                    ? tx `rd.number = ${requestedRound}`
+                    : asStudio
+                        ? null
+                        : tx `rd.number = (
+                SELECT number FROM rounds
+                WHERE project_id = ${p.id} AND closed_at IS NULL
+                  AND deleted_at IS NULL AND archived_at IS NULL
+                ORDER BY number DESC LIMIT 1
+              )`;
             return tx `
         SELECT t.id, t.key, t.status, t.version, t.anchor, t.anchor_state, t.context, t.round_number,
                t.created_at, t.updated_at, t.resolved_at, t.comment_count_public,
@@ -383,7 +408,8 @@ assignDelayMs) {
                -- VISIBLE, computed rather than filtered. See the note above
                -- the query: a thread that becomes private must be TOMBSTONED,
                -- and a WHERE clause can only make it vanish.
-               (t.deleted_at IS NULL AND ${asOwner ? tx `true` : tx `t.private = false`}) AS visible
+               (t.deleted_at IS NULL AND ${asOwner ? tx `true` : tx `t.private = false`}
+                AND ${since && inRound ? inRound : tx `true`}) AS visible
         FROM threads t
         JOIN reviewers r ON r.id = t.created_by
         -- The assignee, when there is one (05 section 6.4b). LEFT: most
@@ -392,7 +418,7 @@ assignDelayMs) {
         JOIN environments e ON e.id = t.environment_id
         -- Joined for the round filter, and the join is the fix for a real
         -- trap: threads.round_number is the thread's position WITHIN its round
-        -- (01 §5.2 -- the number on the pin), while rounds.number is which
+        -- (-- the number on the pin), while rounds.number is which
         -- round it is. Two different integers whose names differ by one word,
         -- and filtering on the first is how round=1 returned the single thread
         -- that happened to be first in its round.
@@ -422,23 +448,9 @@ assignDelayMs) {
                 : assigneeFilter === "unassigned"
                     ? tx `AND t.assignee_id IS NULL`
                     : tx `AND t.assignee_id = ${assigneeFilter}::uuid`}
-          -- Absent round query param: an OWNER still sees every round
-          -- (unchanged), but a non-owner reader defaults to the latest OPEN
-          -- round, so a fresh page load is D2-clean rather than showing a
-          -- round that closed weeks ago. The ORDER BY number DESC LIMIT 1
-          -- correlated subquery is cheap here -- one project's round table
-          -- is a handful of rows, never a scan of threads.
-          ${key
-                ? tx ``
-                : requestedRound
-                    ? tx `AND rd.number = ${requestedRound}`
-                    : asStudio
-                        ? tx ``
-                        : tx `AND rd.number = (
-                    SELECT number FROM rounds
-                    WHERE project_id = ${p.id} AND closed_at IS NULL
-                    ORDER BY number DESC LIMIT 1
-                  )`}
+          -- The round, from inRound above: here on a full list, in the
+          -- visible column on a poll.
+          ${inRound && !since ? tx `AND ${inRound}` : tx ``}
           ${q && !key
                 ? tx `AND (t.key ILIKE ${"%" + q + "%"}
                      OR t.anchor_label ILIKE ${"%" + q + "%"}
@@ -479,11 +491,11 @@ assignDelayMs) {
          * clocks, one comparison: if the app server ran even a second ahead of the
          * database, every thread updated inside that second would be skipped on the
          * next poll and never returned again — a permanently missing comment, on a
-         * skew nobody would think to look for. 05 §12.3 says the client must never
+         * skew nobody would think to look for. The design says the client must never
          * use its own clock; the same argument applies one layer down.
          */
         const [clock] = await sql `SELECT now() AS now`;
-        // §6.3's tombstones. Ids only — the client already has these threads, and
+        // The tombstones. Ids only — the client already has these threads, and
         // a body would be handing back the private content that made it invisible.
         const visible = rows.filter((r) => r["visible"] !== false);
         const deleted = rows
@@ -497,7 +509,89 @@ assignDelayMs) {
         });
     });
     /**
-     * 05 §6.2 — create. The whole thing is one transaction because a thread
+     * Move threads to another round, the studio's filing act, and the
+     * one exception to the "a thread never moves": automatic placement never
+     * moves a thread; only this explicit move does. Owner or admin, from the
+     * dashboard (cookie and CSRF pair, checked inline because the bearer
+     * middleware owns this path for the widget).
+     *
+     * `{ ids: ["thr_…"], round: <number> }`. The target may be open or closed
+     * — filing a stray comment into a finished round is a filing decision — but
+     * not archived or deleted. One transaction: the target round's row is
+     * locked, its `thread_seq` advanced by the number moving, and each thread
+     * takes the next per-round number in creation order. The old round keeps
+     * its gap (a number quoted in an email is never handed to another thread)
+     * and the project-wide key is untouched, so every permalink still works.
+     * `version` moves, so every open dashboard's poll drops the thread from
+     * the round it left (the list's visible column) and shows it in the new one.
+     * Threads already in the target, deleted, or not in this site are skipped.
+     * No `events` row: status and assignee changes write none either.
+     */
+    app.post("/api/v1/projects/:uid/threads/move", async (c) => {
+        const p = await project(c.req.param("uid"));
+        if (!p)
+            return fail(c, 404, "project_not_found", "No project with that uid.");
+        const owner = c.get("owner");
+        if (!owner)
+            return fail(c, 401, "unauthorized", "Sign in to the dashboard first.");
+        if (owner.orgId !== p.org_id || (owner.role !== "owner" && owner.role !== "admin")) {
+            return fail(c, 403, "forbidden", "Only an owner or an admin can move comments between rounds.");
+        }
+        if (!csrfOk(c)) {
+            return fail(c, 403, "csrf_failed", "That request could not be verified. Reload the dashboard and try again.");
+        }
+        const body = (await c.req.json().catch(() => null));
+        const round = body?.round;
+        const ids = Array.isArray(body?.ids) ? body.ids.map((w) => rowId(w, ID_PREFIX.thread)) : [];
+        if (!ids.length || ids.length > 200 || ids.some((x) => !x)) {
+            return fail(c, 400, "validation_failed", "ids must be 1 to 200 thread ids (thr_…).");
+        }
+        if (!(typeof round === "number" && Number.isInteger(round) && round > 0)) {
+            return fail(c, 400, "validation_failed", "round must be a round number (1, 2, …).");
+        }
+        const out = await inOrg(sql, p.org_id, async (tx) => {
+            const [target] = await tx `
+        SELECT id, archived_at IS NOT NULL AS archived FROM rounds
+        WHERE project_id = ${p.id}::uuid AND number = ${round}::int AND deleted_at IS NULL
+        FOR UPDATE
+      `;
+            if (!target)
+                return "missing";
+            if (target.archived)
+                return "archived";
+            const moving = await tx `
+        SELECT id FROM threads
+        WHERE id = ANY(${ids}::uuid[]) AND project_id = ${p.id}::uuid
+          AND deleted_at IS NULL AND round_id <> ${target.id}::uuid
+        ORDER BY created_at, id
+        FOR UPDATE
+      `;
+            if (!moving.length)
+                return 0;
+            const [seq] = await tx `
+        UPDATE rounds SET thread_seq = thread_seq + ${moving.length}::int, updated_at = now()
+        WHERE id = ${target.id}::uuid
+        RETURNING thread_seq AS last
+      `;
+            const first = seq.last - moving.length;
+            await tx `
+        UPDATE threads t
+           SET round_id = ${target.id}::uuid, round_number = ${first}::int + o.n::int,
+               version = t.version + 1, updated_at = now()
+          FROM unnest(${moving.map((m) => m.id)}::uuid[]) WITH ORDINALITY AS o(id, n)
+         WHERE t.id = o.id
+      `;
+            return moving.length;
+        });
+        if (out === "missing")
+            return fail(c, 404, "round_not_found", `This site has no round ${round}.`);
+        if (out === "archived") {
+            return fail(c, 409, "round_archived", "That round is archived. Restore it in Settings to move comments into it.");
+        }
+        return c.json({ moved: out, round });
+    });
+    /**
+     * Create. The whole thing is one transaction because a thread
      * without its first comment is not a snag, it is a pin nobody can read.
      */
     app.post("/api/v1/projects/:uid/threads", async (c) => {
@@ -509,11 +603,11 @@ assignDelayMs) {
             return fail(c, 401, "unauthorized", "Open your review link, or reload the page, and try again.");
         }
         if (p.status !== "active") {
-            // D91: the switch is off — writes refused, reads work (05 §4.9 layer 6).
+            // The switch is off — writes refused, reads work (layer 6).
             return fail(c, 403, "project_paused", "This site's widget is switched off. Its owner can switch it back on.");
         }
         if (!session.perm.includes("thread:create")) {
-            // §4.8's matrix. A read-only session gets a sentence about permission,
+            // The matrix. A read-only session gets a sentence about permission,
             // not about authentication — they ARE signed in.
             return fail(c, 403, "forbidden", "This review link does not allow new comments.");
         }
@@ -525,6 +619,16 @@ assignDelayMs) {
         // the host put one on the script tag, and inventing one here would put a
         // comment in an environment the dashboard is not looking at.
         const envKey = typeof body.scope?.environment === "string" ? body.scope.environment : null;
+        // The round the reviewer is LOOKING AT, by number (the only round
+        // identity the widget holds). Rounds run side by side, so "the newest
+        // open one" stopped being the right answer the day a studio kept its own
+        // QA round going while the client's ran: a comment left while viewing
+        // Internal QA belongs to Internal QA.
+        const askedRound = body.scope?.round;
+        if (askedRound !== undefined && askedRound !== null && !(Number.isInteger(askedRound) && askedRound > 0)) {
+            return fail(c, 400, "validation_failed", "scope.round must be a round number (1, 2, …).");
+        }
+        const roundNo = typeof askedRound === "number" ? askedRound : null;
         // A client-minted id that is not a UUID is a bug in the client, not
         // something to paper over with a server-minted one: the widget's optimistic
         // copy would then be a different snag from the stored one. Parsed out here,
@@ -535,8 +639,8 @@ assignDelayMs) {
         }
         const commentBody = typeof body.comment?.body === "string" && body.comment.body ? body.comment.body : null;
         const commentId = rowId(body.comment?.id, ID_PREFIX.comment) ?? randomUUID();
-        // The attachments uploaded moments ago, to be BOUND by the write below (05
-        // §6.6). Until that runs they are `pending` rows with no owner: §3.6's
+        // The attachments uploaded moments ago, to be BOUND by the write below
+        // Until that runs they are `pending` rows with no owner: The
         // CHECK forbids a bound attachment without exactly one of
         // thread_id/comment_id, which is what makes an orphan detectable rather
         // than merely unlikely. The bind is scoped to this project AND to rows
@@ -549,7 +653,7 @@ assignDelayMs) {
         //
         // This used to read `createdBy.holderSecret` off the request and mint a
         // reviewer from it — a second, weaker answer to "who is this?" sitting
-        // beside the session that already answers it. 05 §4.4 is explicit that a
+        // beside the session that already answers it. The design is explicit that a
         // session's identity is decided at exchange and never taken from a request,
         // and leaving the body path in place would have meant a caller could author
         // as anyone by presenting a secret they had seen once.
@@ -566,38 +670,69 @@ assignDelayMs) {
                  * work never was the cost. The *count* was.
                  *
                  * What survives is the ORDER, because the order is load-bearing —
-                 * §2.1's allocation still row-locks the project before the insert
+                 * the allocation still row-locks the project before the insert
                  * reads it, still serialises creation per project, and still yields a
                  * gapless human id. A CTE does not relax that: data-modifying CTEs run
                  * exactly once, to completion, and the insert that reads pseq/rseq
                  * cannot begin before they have produced their rows.
                  */
+                /*
+                 * WHICH ROUND, in this order:
+                 *   1. the one asked for, when it is open and not archived -- and a
+                 *      409 when it is not, rather than a silent move elsewhere: the
+                 *      reviewer chose it, and a comment that lands somewhere else
+                 *      without a word is the bug parallel rounds exist to remove;
+                 *   2. else the review link's pinned round, when it is open;
+                 *   3. Else the newest open, unarchived round -- the original rule.
+                 * Still the same one statement: the environment and both candidates
+                 * come back together, and the choice is made below.
+                 */
                 const [ctx] = await tx `
           SELECT
             (SELECT id FROM environments
               WHERE project_id = ${p.id} AND deleted_at IS NULL
                 AND ${envKey ? tx `key = ${envKey}` : tx `is_default`}
               LIMIT 1) AS environment_id,
-            r.id AS round_id
+            a.id AS asked_id,
+            (a.closed_at IS NULL AND a.archived_at IS NULL) AS asked_open,
+            COALESCE(
+              ${session.lnk
+                    ? tx `(SELECT rd.id FROM review_links rl JOIN rounds rd ON rd.id = rl.round_id
+                         WHERE rl.id = ${session.lnk}::uuid AND rd.project_id = ${p.id}
+                           AND rd.deleted_at IS NULL AND rd.archived_at IS NULL AND rd.closed_at IS NULL)`
+                    : tx `NULL::uuid`},
+              r.id
+            ) AS round_id
           FROM (SELECT 1) one
           LEFT JOIN LATERAL (
             SELECT id FROM rounds
-            WHERE project_id = ${p.id} AND deleted_at IS NULL AND closed_at IS NULL
+            WHERE project_id = ${p.id} AND deleted_at IS NULL AND closed_at IS NULL AND archived_at IS NULL
             ORDER BY number DESC LIMIT 1
           ) r ON true
+          LEFT JOIN LATERAL (
+            SELECT id, closed_at, archived_at FROM rounds
+            WHERE project_id = ${p.id} AND deleted_at IS NULL AND number = ${roundNo ?? 0}::int
+          ) a ON true
         `;
                 // Kept as its own statement rather than folded into the write below,
                 // because these two are the only failures a caller can act on and
-                // §6.9 gives them distinct codes. A single statement that inserted
+                // the design gives them distinct codes. A single statement that inserted
                 // nothing would have to report "something was missing".
                 if (!ctx?.environment_id) {
                     throw new HttpError(400, "environment_not_found", envKey
                         ? `This project has no environment called "${envKey}".`
                         : "This project has no default environment.");
                 }
-                // The active round: highest number, not closed. D2 — a thread belongs
-                // to whichever round was active when it was created, and never moves.
-                if (!ctx.round_id)
+                // Still holds whichever round is chosen: a thread belongs to the
+                // round it was created in, and never moves.
+                if (roundNo !== null && !ctx.asked_id) {
+                    throw new HttpError(409, "round_not_found", `This site has no round ${roundNo}. Reload to see its rounds.`);
+                }
+                if (roundNo !== null && !ctx.asked_open) {
+                    throw new HttpError(409, "round_closed", `Round ${roundNo} is closed, so it takes no new comments. Pick an open round, or leave the round out.`);
+                }
+                const roundId = roundNo !== null ? ctx.asked_id : ctx.round_id;
+                if (!roundId)
                     throw new HttpError(409, "no_active_round", "This project has no open round.");
                 const counted = commentBody === null ? 0 : 1;
                 const [row] = await tx `
@@ -608,7 +743,7 @@ assignDelayMs) {
           ),
           rseq AS (
             UPDATE rounds SET thread_seq = thread_seq + 1
-            WHERE id = ${ctx.round_id}::uuid
+            WHERE id = ${roundId}::uuid
             RETURNING thread_seq
           ),
           ins AS (
@@ -617,7 +752,7 @@ assignDelayMs) {
                                  comment_count, comment_count_public)
             SELECT ${threadId}::uuid, ${p.org_id}::uuid, ${p.id}::uuid,
                    ${p.key_prefix}::text || '-' || pseq.thread_seq::text,
-                   ${ctx.environment_id}::uuid, ${ctx.round_id}::uuid, rseq.thread_seq,
+                   ${ctx.environment_id}::uuid, ${roundId}::uuid, rseq.thread_seq,
                    ${tx.json(body.anchor)}::jsonb, ${tx.json(body.context)}::jsonb,
                    ${reviewerId}::uuid, ${body.anchorState ?? "anchored"}::snag_anchor_state,
                    ${counted}::int, ${counted}::int
@@ -642,7 +777,7 @@ assignDelayMs) {
           ),
           -- The author's row: seen now, and the counters the assignee pool
           -- reads (05 section 3.4, section 6.4b -- "everyone who has
-          -- commented" is thread_count > 0 OR comment_count > 0). Until D90
+          -- commented" is thread_count > 0 OR comment_count > 0). Until
           -- nothing moved thread_count at all, so a client whose only act
           -- was leaving a pin was invisible to the pool. ONE update: two
           -- data-modifying CTEs touching the same row in one statement is
@@ -698,7 +833,7 @@ assignDelayMs) {
                         pageUrl: body.context?.url ?? "",
                     }, randomUUID());
                 }
-                // D95: a site whose tracker makes an issue on every new thread. Same
+                // A site whose tracker makes an issue on every new thread. Same
                 // transaction as the thread, keyed on the thread, so a retried POST
                 // cannot make a second issue.
                 for (const link of await trackers(p.org_id, p.id)) {
@@ -723,7 +858,7 @@ assignDelayMs) {
             if (e instanceof HttpError)
                 return fail(c, e.status, e.code, e.message);
             /**
-             * A RETRY IS NOT AN ERROR — 05 §11's idempotency, by natural key.
+             * A RETRY IS NOT AN ERROR — the idempotency, by natural key.
              *
              * A double-tapped Send, or a reviewer on a train whose request landed
              * while their connection dropped before the response did, sends the same
@@ -734,7 +869,7 @@ assignDelayMs) {
              * connection is the moment they try again, or give up and stop using it.
              *
              * The id makes this decidable with no header and no client change: the
-             * widget already mints it (§6.2), so a second POST carrying an id we
+             * widget already mints it, so a second POST carrying an id we
              * already hold IS the same request. Returning what the first one created
              * is the whole of the fix.
              *
@@ -790,7 +925,7 @@ assignDelayMs) {
         }
     });
     /**
-     * 05 §6.4 — status changes, endpoint 9, marked **W/D** like the list.
+     * Status changes, endpoint 9, marked **W/D** like the list.
      *
      * IT SHIPPED WITH NO AUTHENTICATION CHECK AT ALL. Not a weak one — none: the
      * handler read the uid, read the body and wrote. `bearerAuth` was mounted on
@@ -801,15 +936,15 @@ assignDelayMs) {
      *
      * Two credentials are legitimate here and they are checked separately: an
      * OWNER of this project's org, and a reviewer session carrying
-     * `thread:resolve` (§4.8's matrix — it is in the default link grant, because
-     * a client marking their own snag done is the loop D4 is built around).
+     * `thread:resolve` (the matrix — it is in the default link grant, because
+     * a client marking their own snag done is the loop the decision is built around).
      */
     /**
-     * 05 §6.4 endpoint 8 — one thread — and D93's brief: the same row as
+     * Endpoint 8 — one thread — and the brief: the same row as
      * `text/markdown` when the id ends in `.md`, for curl, an agent's shell or
      * a ticket body. The privacy rule is the list's: a private thread is absent
      * for a non-owner, which reads as "no such thread" rather than confirming
-     * one exists (§6.4a), and team-only replies stay out of a client's copy.
+     * one exists, and team-only replies stay out of a client's copy.
      */
     app.get("/api/v1/projects/:uid/threads/:id", async (c) => {
         const p = await project(c.req.param("uid"));
@@ -880,10 +1015,10 @@ assignDelayMs) {
         const mcp = c.get("mcp");
         const asOwner = !!owner && owner.orgId === p.org_id;
         /**
-         * `mark_ready` (07 §8.3) lands here — and this is the whole of an agent's
+         * `mark_ready` lands here — and this is the whole of an agent's
          * write surface on a thread, `threads:write`.
          *
-         * §8.6 mitigation 4: *"an agent can propose, never dispose"*. There is
+         * *"an agent can propose, never dispose"*. There is
          * deliberately no tool that resolves a thread, and the refusal below is
          * where that is actually true rather than merely absent from a tool list:
          * an agent PATCHing `status: 'resolved'` on this route is refused even
@@ -900,20 +1035,22 @@ assignDelayMs) {
             return fail(c, 403, "forbidden", "This review link does not allow changing status.");
         }
         const body = (await c.req.json().catch(() => null));
-        // D2: a thread belongs to exactly one round and NEVER moves. Refused
-        // explicitly rather than ignored, because a caller that sends `round` and
-        // gets a 200 will believe it moved — and the whole model rests on the fact
-        // that it did not. §6.9's `field_not_permitted` is the registered code.
+        // A thread never moves BY ACCIDENT. Refused explicitly rather than
+        // ignored, because a caller that sends `round` and gets a 200 will believe
+        // it moved. Moving is a studio act with its own route (the
+        // move below), which renumbers inside the target round; a PATCH field
+        // would be a second, quieter way to do it. The `field_not_permitted`
+        // is the registered code.
         for (const field of ["round", "roundId", "roundNumber"]) {
             if (body && field in body) {
-                return fail(c, 422, "field_not_permitted", "A comment stays in the round it was left in. Rounds are periods of time, not folders.", { field });
+                return fail(c, 422, "field_not_permitted", "A comment's round is not changed here. The studio moves comments between rounds from the dashboard.", { field });
             }
         }
         /**
-         * `private` — 05 §6.4, and the write that makes `deleted[]` mean something.
+         * `private`, and the write that makes `deleted[]` mean something.
          *
          * Studio-only, like the thread-level field it is: an owner always may, a
-         * reviewer session needs the link permission that names it. §6.4 is
+         * reviewer session needs the link permission that names it. The design is
          * explicit that this is `403 field_not_permitted` with `details.field`
          * rather than a silently ignored field, because a caller who sends
          * `private: true` and gets a 200 will believe the thread is private.
@@ -925,14 +1062,14 @@ assignDelayMs) {
             });
         }
         if (wantsPrivate !== undefined && asAgent && !asOwner) {
-            // §8.2: an agent write is never laundered into a trust tier it did not
+            // An agent write is never laundered into a trust tier it did not
             // earn, and team-only is the studio's register.
             return fail(c, 403, "field_not_permitted", "An agent cannot make a thread team-only.", {
                 field: "private",
             });
         }
         /**
-         * `assignee` — 05 §6.4b, D90. A reviewer id from the pool, or null to
+         * `assignee`. A reviewer id from the pool, or null to
          * un-assign. Same register as `private`: the studio's own routing of
          * work, so an owner always may, a reviewer session needs the permission
          * that names it, and a refusal is `403 field_not_permitted` with
@@ -954,7 +1091,7 @@ assignDelayMs) {
                 }
             }
             if (asAgent && !asOwner) {
-                // 07 §8.6 mitigation 4 again: an agent proposes, never disposes —
+                // Again: an agent proposes, never disposes
                 // and handing a thread to a person is disposing of it.
                 return fail(c, 403, "field_not_permitted", "An agent cannot assign a comment to someone.", {
                     field: "assignee",
@@ -976,7 +1113,7 @@ assignDelayMs) {
             return fail(c, 400, "validation_failed", "status must be one of open, progress, review, resolved.");
         }
         /**
-         * F-26's expected version — 01 §1221, AC-1-11's "no silent overwrite".
+         * F-26's expected version, the "no silent overwrite".
          *
          * `threads.version` has been incremented on every write since 0001 and
          * READ by nothing: the column existed, the guarantee did not. Two studio
@@ -987,7 +1124,7 @@ assignDelayMs) {
          * OPTIONAL, deliberately. A caller that sends no `version` is saying "I am
          * not editing a copy I read earlier" — the CLI, an agent acting on a fresh
          * read, a curl. Making it mandatory would break every existing caller to
-         * protect a case they are not in, and 05 §11.1's additive rule forbids
+         * protect a case they are not in, and the additive rule forbids
          * that. The dashboard and the widget send it because they ARE editing a
          * copy they read earlier, which is exactly the population F-26 is about.
          */
@@ -1004,7 +1141,7 @@ assignDelayMs) {
                 return fail(c, 403, "forbidden", "An agent may mark a snag ready for review, but not resolve it. " +
                     "Whoever reported it decides when it is fixed — tell your user it is ready.");
             }
-            // 07 §8.4's stop signal, spent before the write rather than after it.
+            // The stop signal, spent before the write rather than after it.
             const spent = await checkWriteBudget(sql, mcp.tokenId);
             if (spent !== null)
                 return budgetExhausted(c);
@@ -1030,10 +1167,10 @@ assignDelayMs) {
         let conflict;
         // Set by the transaction when the candidate assignee is not in the pool.
         let badAssignee = false;
-        // Read by the transaction when an assignee is being set (D123).
+        // Read by the transaction when an assignee is being set.
         let previousAssignee = null;
         /**
-         * The person pressing the button, as D123's assignment mail needs them:
+         * The person pressing the button, as the assignment mail needs them:
          * never mailed about handing a snag to themselves, and — when they ARE
          * the assignee and move its status — the mail about it is dropped,
          * because they have plainly seen it. An agent is nobody here: it cannot
@@ -1070,7 +1207,7 @@ assignDelayMs) {
                 }
             }
             /**
-             * The candidate must be IN THE POOL — §6.4b's predicate, shared with
+             * The candidate must be IN THE POOL — the predicate, shared with
              * the pool route — and in THIS project. Blocked and erased reviewers
              * keep the assignments they have but take no new ones; a guest who
              * never wrote is not assignable; a reviewer id from another project is
@@ -1087,7 +1224,7 @@ assignDelayMs) {
                 }
                 // Who held it BEFORE, under the row lock the UPDATE below would take
                 // anyway: re-sending the assignee a thread already has is not a new
-                // assignment, and must not be a second mail (D123).
+                // assignment, and must not be a second mail.
                 const [was] = await tx `
           SELECT assignee_id FROM threads
            WHERE id = ${threadRow}::uuid AND project_id = ${p.id}::uuid
@@ -1096,7 +1233,7 @@ assignDelayMs) {
                 previousAssignee = was?.assignee_id ?? null;
             }
             /**
-             * §6.4 consequence TWO of three, and it runs before the CTE rather than
+             * Consequence TWO of three, and it runs before the CTE rather than
              * inside it.
              *
              * *"every comment on a thread becoming private is set `private = true` in
@@ -1185,7 +1322,7 @@ assignDelayMs) {
       `;
             /**
              * `thread.resolved` — B2's second topic, queued in the SAME transaction
-             * as the status change (07 §2.5), so a resolve that commits without its
+             * as the status change, so a resolve that commits without its
              * notification is impossible and a notification about a resolve that
              * rolled back cannot exist.
              *
@@ -1213,10 +1350,10 @@ assignDelayMs) {
                 });
             }
             /**
-             * D123 — "this snag is yours now", an hour from now and only if it is
+             * "this snag is yours now", an hour from now and only if it is
              * still true then (`mail/assigned.ts`). Queued here, in the transaction
              * that assigned it, like every outbox row; only when it is a NEW holder
-             * and only when mail is configured at all (08 §4.8: off and say so,
+             * and only when mail is configured at all (off and say so,
              * rather than rows that arrive in a burst the day somebody sets it up).
              */
             if (assigneeRow && assigneeRow !== previousAssignee && actor && updated?.[0] && (await notifications())) {
@@ -1240,7 +1377,7 @@ assignDelayMs) {
             if (status !== undefined && actor && updated?.[0]) {
                 await dropAssignedBy(tx, threadRow, actor);
             }
-            // D95: our status is canonical, the tracker's follows — queued here, in
+            // Our status is canonical, the tracker's follows — queued here, in
             // the transaction that moved it, keyed on the version so every change
             // is one row. The worker maps by state type: resolved closes as
             // completed, anything else reopens; a thread with no issue is skipped.
@@ -1261,7 +1398,7 @@ assignDelayMs) {
         });
         /**
          * F-26, on the wire. 409 and not 412: `If-Match` semantics would make this
-         * a header concern, and 01 §1221 describes a product event ("someone else
+         * a header concern, and the design describes a product event ("someone else
          * updated this while you were typing") that the client renders with **Post
          * anyway** and **See what changed** — a conflict, not a failed
          * precondition. `currentVersion` rides along so the refetch has something
@@ -1279,7 +1416,7 @@ assignDelayMs) {
         if (!row)
             return fail(c, 404, "thread_not_found", "No such thread in this project.");
         /**
-         * 07 §8.6 mitigation 8: every agent write lands in `events` with the
+         * Every agent write lands in `events` with the
          * reviewer id and the token id.
          *
          * A SECOND transaction, and this is the one place that is not ideal: the
@@ -1316,12 +1453,12 @@ assignDelayMs) {
      * 05 endpoint 10 — deleting a whole thread, project-scoped like the PATCH
      * above. The studio, any thread; a reviewer, their own.
      *
-     * §4.8's matrix gives a reviewer "own only", behind the link permission
+     * The matrix gives a reviewer "own only", behind the link permission
      * `thread:delete:own` — on by default since 0.1.14 for guests and new
      * links, because the widget offered Delete on a reviewer's own snag and
      * this route refused it. "Own" is narrower than "opened": every live
      * comment in the thread must be theirs, so nobody's reply goes with it.
-     * An agent is still refused (§8.6 mitigation 4 — an agent proposes, never
+     * An agent is still refused (an agent proposes, never
      * disposes, and deleting is the most disposing act there is).
      *
      * ── SOFT, LIKE A SITE ──
@@ -1333,7 +1470,7 @@ assignDelayMs) {
      * column, and an operator who deletes the wrong thread has a row to
      * restore. `version` and `updated_at` move with it so a `?since=` poll —
      * every other open dashboard, every reviewer's widget — gets the id in
-     * `deleted[]` and drops its copy (§6.3), rather than showing a thread that
+     * `deleted[]` and drops its copy, rather than showing a thread that
      * is gone until somebody reloads.
      *
      * ── THE COMMENTS ARE LEFT ALONE, DELIBERATELY ──
@@ -1343,7 +1480,7 @@ assignDelayMs) {
      * thread's `deleted_at`; the two comment routes that address a comment by
      * its own id (commentEdit.ts) answer 404 once its thread is deleted. So
      * tombstoning them would hide nothing more today, and it would make the
-     * delete irreversible — §3.11's tombstone NULLs the body, and a restored
+     * delete irreversible — the tombstone NULLs the body, and a restored
      * thread with every word gone is not a restore. The counters stay as they
      * are for the same reason.
      *
@@ -1361,7 +1498,7 @@ assignDelayMs) {
      *     with and never looks back at the thread. A tracker row would be
      *     dropped by its worker anyway ("the thread is gone"); dropping it here
      *     says so in one place. Rows already in flight are left to finish.
-     *   · Linked issues in GitHub, Linear, Jira or Slack are NOT touched. 07's
+     *   · Linked issues in GitHub, Linear, Jira or Slack are NOT touched. The
      *     `thread.deleted` event is not built, and closing a developer's issue
      *     because a comment was moderated is not obviously what anyone wants.
      *     An inbound webhook for that issue finds no thread and is ignored.
@@ -1398,7 +1535,7 @@ assignDelayMs) {
                 if (!session.perm.includes("thread:delete:own")) {
                     return fail(c, 403, "forbidden", "Your review link does not allow deleting comments.");
                 }
-                // A studio owner or admin signed in from the widget (D122) deletes
+                // A studio owner or admin signed in from the widget deletes
                 // any thread, as in the dashboard.
                 const moderator = await inOrg(sql, p.org_id, (tx) => isStudioModerator(tx, p.org_id, session.sub));
                 const [t] = moderator ? [{ all_mine: true, any: true }] : await inOrg(sql, p.org_id, (tx) => tx `
@@ -1420,7 +1557,7 @@ assignDelayMs) {
             }
         }
         else {
-            // §4.8's matrix: member, admin and owner may; a viewer may not. Nobody
+            // The matrix: member, admin and owner may; a viewer may not. Nobody
             // can be GIVEN a viewer seat yet (members.ts wires owner and admin only),
             // so this is the rule written down where it applies, before the day the
             // seat exists and every route has to be audited for it.
@@ -1438,12 +1575,7 @@ assignDelayMs) {
         if (!threadRow)
             return fail(c, 404, "thread_not_found", "No such thread in this project.");
         const found = await inOrg(sql, p.org_id, async (tx) => {
-            const [gone] = await tx `
-        UPDATE threads
-           SET deleted_at = now(), version = version + 1, updated_at = now()
-         WHERE id = ${threadRow}::uuid AND project_id = ${p.id}::uuid AND deleted_at IS NULL
-        RETURNING id
-      `;
+            const gone = await softDeleteThreads(tx, p.id, { thread: threadRow }, "the thread was deleted");
             if (!gone) {
                 // Already deleted, or never here. Only the second is an error.
                 const [was] = await tx `
@@ -1451,19 +1583,6 @@ assignDelayMs) {
         `;
                 return !!was;
             }
-            // The thread's own pictures and any bound to its comments: FOLDBACK
-            // section A6 hangs an attachment off exactly one of the two.
-            await tx `
-        UPDATE attachments SET deleted_at = now()
-         WHERE deleted_at IS NULL
-           AND (thread_id = ${threadRow}::uuid
-                OR comment_id IN (SELECT id FROM comments WHERE thread_id = ${threadRow}::uuid))
-      `;
-            await tx `
-        UPDATE outbox
-           SET status = 'dropped', last_error = 'the thread was deleted', completed_at = now()
-         WHERE thread_id = ${threadRow}::uuid AND status = 'pending'
-      `;
             return true;
         });
         if (!found)
@@ -1472,6 +1591,44 @@ assignDelayMs) {
     });
     return app;
 }
+/**
+ * The thread DELETE's work, for one thread or for every live thread in a
+ * round (the round delete) — one copy, so a round's threads go exactly the
+ * way a single thread does and "what else goes with it" (the route's comment
+ * above) is answered in one place. Inside the caller's transaction, which has
+ * already set `app.org_id`. Returns how many threads it marked.
+ *
+ * `version` and `updated_at` move so a `?since=` poll tombstones each one;
+ * attachments on the thread or its comments are marked; pending outbox rows
+ * are dropped with `reason` in `last_error`. Comments are left alone, for the
+ * reason given above.
+ */
+export async function softDeleteThreads(tx, projectId, which, reason) {
+    const gone = await tx `
+    UPDATE threads
+       SET deleted_at = now(), version = version + 1, updated_at = now()
+     WHERE project_id = ${projectId}::uuid AND deleted_at IS NULL
+       AND ${"thread" in which ? tx `id = ${which.thread}::uuid` : tx `round_id = ${which.round}::uuid`}
+    RETURNING id
+  `;
+    if (!gone.length)
+        return 0;
+    const ids = gone.map((g) => g.id);
+    // The thread's own pictures and any bound to its comments:
+    // section A6 hangs an attachment off exactly one of the two.
+    await tx `
+    UPDATE attachments SET deleted_at = now()
+     WHERE deleted_at IS NULL
+       AND (thread_id = ANY(${ids}::uuid[])
+            OR comment_id IN (SELECT id FROM comments WHERE thread_id = ANY(${ids}::uuid[])))
+  `;
+    await tx `
+    UPDATE outbox
+       SET status = 'dropped', last_error = ${reason}, completed_at = now()
+     WHERE thread_id = ANY(${ids}::uuid[]) AND status = 'pending'
+  `;
+    return ids.length;
+}
 /**
  * Fields declared and assigned, NOT constructor parameter properties.
  *
@@ -1491,7 +1648,7 @@ class HttpError extends Error {
         this.code = code;
     }
 }
-/** Rows → 00 §5's `Thread`. The shape the widget already renders, unchanged. */
+/** Rows → the `Thread`. The shape the widget already renders, unchanged. */
 function shape(r) {
     return {
         id: wireId_(r.id, ID_PREFIX.thread),
@@ -1527,7 +1684,7 @@ function shape(r) {
                 isTeam: !!r.assignee_is_team,
             }
             : null,
-        // D95: where this thread lives elsewhere — the GitHub issue, later the
+        // Where this thread lives elsewhere — the GitHub issue, later the
         // Linear and Jira ones. Always an array, so a merge can clear it.
         refs: r.refs ?? [],
         createdAt: new Date(r.created_at).toISOString(),