@jant/core 0.6.14 → 0.6.16

package/src/db/migrations/pg/meta/_journal.json

@@ -176,6 +176,41 @@
       "when": 1781807044981,
       "tag": "0024_high_violations",
       "breakpoints": true
+    },
+    {
+      "idx": 25,
+      "version": "7",
+      "when": 1784131458842,
+      "tag": "0025_moaning_epoch",
+      "breakpoints": true
+    },
+    {
+      "idx": 26,
+      "version": "7",
+      "when": 1784343834845,
+      "tag": "0026_talented_killer_shrike",
+      "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "7",
+      "when": 1784436805462,
+      "tag": "0027_short_cannonball",
+      "breakpoints": true
+    },
+    {
+      "idx": 28,
+      "version": "7",
+      "when": 1784531392184,
+      "tag": "0028_perfect_sharon_carter",
+      "breakpoints": true
+    },
+    {
+      "idx": 29,
+      "version": "7",
+      "when": 1786008671529,
+      "tag": "0029_rare_hairball",
+      "breakpoints": true
     }
   ]
 }

package/src/db/pg/schema.ts

@@ -19,6 +19,7 @@ import {
   customType,
 } from "drizzle-orm/pg-core";
 import { sql } from "drizzle-orm";
+import { SYSTEM_NAV_KEY_VALUES } from "../../types/constants.js";
 
 const SITE_STATUSES = ["active", "suspended"] as const;
 const SITE_DOMAIN_KINDS = ["primary", "alias"] as const;
@@ -27,16 +28,8 @@ const FORMATS = ["note", "link", "quote"] as const;
 const STATUSES = ["draft", "published"] as const;
 const VISIBILITIES = ["public", "latest_hidden", "private"] as const;
 const COLLECTION_SORT_ORDERS = ["newest", "oldest", "rating_desc"] as const;
-const NAV_ITEM_TYPES = ["link", "system", "collection"] as const;
+const NAV_ITEM_TYPES = ["link", "system", "collection", "page"] as const;
 const NAV_ITEM_PLACEMENTS = ["header", "more"] as const;
-const SYSTEM_NAV_KEYS = [
-  "latest",
-  "featured",
-  "collections",
-  "archive",
-  "rss",
-  "settings",
-] as const;
 const UPLOAD_SESSION_STATES = [
   "pending",
   "uploaded",
@@ -167,6 +160,7 @@ export const posts = pgTable(
     url: text("url"),
     body: text("body"),
     bodyHtml: text("body_html"),
+    bodyHtmlVersion: integer("body_html_version").notNull().default(1),
     bodyText: text("body_text"),
     quoteText: text("quote_text"),
     summary: text("summary"),
@@ -185,8 +179,23 @@ export const posts = pgTable(
     previewProvider: text("preview_provider"),
     replyToId: text("reply_to_id"),
     threadId: text("thread_id").notNull(),
+    /**
+     * The author added this reply without announcing it. Persisted so both
+     * activity timestamps below stay recomputable from the rows alone.
+     * Always false on Thread roots.
+     */
+    quietReply: boolean("quiet_reply").notNull().default(false),
     publishedAt: integer("published_at"),
+    /**
+     * Root only: newest published_at in the Thread, excluding quiet replies —
+     * "last announced". Drives Latest and the feeds.
+     */
     lastActivityAt: integer("last_activity_at"),
+    /**
+     * Root only: newest published_at in the Thread, quiet replies included —
+     * "last changed". Drives the archive's updated sort.
+     */
+    threadUpdatedAt: integer("thread_updated_at"),
     createdAt: integer("created_at").notNull(),
     updatedAt: integer("updated_at").notNull(),
   },
@@ -234,6 +243,9 @@ export const posts = pgTable(
     index("idx_post_site_root_published_activity")
       .on(table.siteId, table.lastActivityAt, table.id)
       .where(sql`${table.replyToId} IS NULL AND ${table.status} = 'published'`),
+    index("idx_post_site_root_thread_updated")
+      .on(table.siteId, table.threadUpdatedAt, table.id)
+      .where(sql`${table.replyToId} IS NULL AND ${table.status} = 'published'`),
     index("idx_post_site_root_draft_updated")
       .on(table.siteId, table.updatedAt, table.id)
       .where(sql`${table.replyToId} IS NULL AND ${table.status} = 'draft'`),
@@ -242,8 +254,8 @@ export const posts = pgTable(
       .where(
         sql`${table.replyToId} IS NOT NULL AND ${table.status} = 'published'`,
       ),
-    index("idx_post_site_featured_featured_at")
-      .on(table.siteId, table.featuredAt, table.threadId, table.id)
+    index("idx_post_site_featured_thread_published")
+      .on(table.siteId, table.threadId, table.publishedAt, table.id)
       .where(
         sql`${table.status} = 'published' AND ${table.featuredAt} IS NOT NULL`,
       ),
@@ -591,16 +603,16 @@ export const collectionDirectoryItems = pgTable(
 );
 
 // =============================================================================
-// Post-Collection Junction Table (M:N)
+// Thread-Collection Junction Table (M:N)
 // =============================================================================
 
-export const postCollections = pgTable(
-  "post_collection",
+export const threadCollections = pgTable(
+  "thread_collection",
   {
     siteId: text("site_id")
       .notNull()
       .references(() => sites.id, { onDelete: "cascade" }),
-    postId: text("post_id")
+    threadId: text("thread_id")
       .notNull()
       .references(() => posts.id, { onDelete: "cascade" }),
     collectionId: text("collection_id")
@@ -611,16 +623,16 @@ export const postCollections = pgTable(
     pinnedAt: integer("pinned_at"),
   },
   (table) => [
-    primaryKey({ columns: [table.siteId, table.postId, table.collectionId] }),
-    index("idx_post_collection_site_collection_id").on(
+    primaryKey({ columns: [table.siteId, table.threadId, table.collectionId] }),
+    index("idx_thread_collection_site_collection_id").on(
       table.siteId,
       table.collectionId,
     ),
-    index("idx_post_collection_site_collection_created_post").on(
+    index("idx_thread_collection_site_collection_created_thread").on(
       table.siteId,
       table.collectionId,
       table.createdAt,
-      table.postId,
+      table.threadId,
     ),
   ],
 );
@@ -642,11 +654,14 @@ export const navItems = pgTable(
       .notNull()
       .default("link"),
     systemKey: text("system_key", {
-      enum: SYSTEM_NAV_KEYS,
+      enum: SYSTEM_NAV_KEY_VALUES,
     }),
     collectionId: text("collection_id").references(() => collections.id, {
       onDelete: "cascade",
     }),
+    postId: text("post_id").references(() => posts.id, {
+      onDelete: "cascade",
+    }),
     label: text("label").notNull(),
     url: text("url").notNull(),
     placement: text("placement", {
@@ -673,14 +688,22 @@ export const navItems = pgTable(
         ${table.type} = 'link'
         AND ${table.systemKey} IS NULL
         AND ${table.collectionId} IS NULL
+        AND ${table.postId} IS NULL
       ) OR (
         ${table.type} = 'system'
         AND ${table.systemKey} IS NOT NULL
         AND ${table.collectionId} IS NULL
+        AND ${table.postId} IS NULL
       ) OR (
         ${table.type} = 'collection'
         AND ${table.systemKey} IS NULL
         AND ${table.collectionId} IS NOT NULL
+        AND ${table.postId} IS NULL
+      ) OR (
+        ${table.type} = 'page'
+        AND ${table.systemKey} IS NULL
+        AND ${table.collectionId} IS NULL
+        AND ${table.postId} IS NOT NULL
       )`,
     ),
     uniqueIndex("uq_nav_item_site_position").on(table.siteId, table.position),
@@ -690,6 +713,9 @@ export const navItems = pgTable(
     uniqueIndex("uq_nav_item_site_collection_id")
       .on(table.siteId, table.collectionId)
       .where(sql`${table.collectionId} IS NOT NULL`),
+    uniqueIndex("uq_nav_item_site_post_id")
+      .on(table.siteId, table.postId)
+      .where(sql`${table.postId} IS NOT NULL`),
   ],
 );
 

package/src/db/rehearsal-fixtures/demo-current.json

@@ -1,25 +1,60 @@
 {
   "name": "demo-current",
-  "baseMigrationTag": "0003_fts_site_aware",
+  "baseMigrationTag": "0026_absent_rhodey",
   "seedPath": "./demo-current.sql",
   "assertions": [
     {
       "name": "published posts exist",
       "sql": "SELECT COUNT(*) AS count FROM post",
       "column": "count",
-      "atLeast": 1
+      "equals": 3
     },
     {
       "name": "collections exist",
       "sql": "SELECT COUNT(*) AS count FROM collection",
       "column": "count",
-      "atLeast": 1
+      "equals": 2
     },
     {
       "name": "fts index populated",
       "sql": "SELECT COUNT(*) AS count FROM post_fts",
       "column": "count",
-      "atLeast": 1
+      "equals": 3
+    },
+    {
+      "name": "thread collection union preserves both collections",
+      "sql": "SELECT COUNT(*) AS count FROM thread_collection",
+      "column": "count",
+      "equals": 2
+    },
+    {
+      "name": "shared collection metadata is aggregated across the thread",
+      "sql": "SELECT COUNT(*) AS count FROM thread_collection WHERE site_id = 'sit_01kme7j7j1f4m7s2k8r5c9t0qb' AND thread_id = 'pst_01kme7ja2mf4m7s2k8r5c9t0qf' AND collection_id = 'col_01kme7j8f9f4m7s2k8r5c9t0qc' AND created_at = 1774200040 AND position = 1 AND pinned_at = 1774200500",
+      "column": "count",
+      "equals": 1
+    },
+    {
+      "name": "child-only collection becomes thread membership",
+      "sql": "SELECT COUNT(*) AS count FROM thread_collection WHERE site_id = 'sit_01kme7j7j1f4m7s2k8r5c9t0qb' AND thread_id = 'pst_01kme7ja2mf4m7s2k8r5c9t0qf' AND collection_id = 'col_01kme7j8f9f4m7s2k8r5c9t0qd' AND created_at = 1774200060 AND position = 4 AND pinned_at = 1774200600",
+      "column": "count",
+      "equals": 1
+    },
+    {
+      "name": "thread collection targets are roots",
+      "sql": "SELECT COUNT(*) AS count FROM thread_collection tc INNER JOIN post root ON root.site_id = tc.site_id AND root.id = tc.thread_id WHERE root.reply_to_id IS NOT NULL OR root.thread_id <> root.id",
+      "column": "count",
+      "equals": 0
+    },
+    {
+      "name": "legacy post collection table is removed",
+      "sql": "SELECT COUNT(*) AS count FROM sqlite_master WHERE type = 'table' AND name = 'post_collection'",
+      "column": "count",
+      "equals": 0
+    },
+    {
+      "name": "foreign keys remain valid",
+      "sql": "PRAGMA foreign_key_check",
+      "rowCount": 0
     }
   ]
 }

package/src/db/rehearsal-fixtures/demo-current.sql

@@ -31,6 +31,24 @@ INSERT INTO "collection" (
   1774200010
 );
 
+INSERT INTO "collection" (
+  "id",
+  "site_id",
+  "title",
+  "description",
+  "sort_order",
+  "created_at",
+  "updated_at"
+) VALUES (
+  'col_01kme7j8f9f4m7s2k8r5c9t0qd',
+  'sit_01kme7j7j1f4m7s2k8r5c9t0qb',
+  'Child-only Notes',
+  'Collection assigned only to a reply before the Thread migration.',
+  'newest',
+  1774200011,
+  1774200011
+);
+
 INSERT INTO "nav_item" (
   "id",
   "site_id",
@@ -149,18 +167,115 @@ INSERT INTO "post" (
   1774200020
 );
 
-INSERT INTO "post_collection" (
+INSERT INTO "post" (
+  "id",
   "site_id",
-  "post_id",
-  "collection_id",
-  "created_at"
+  "format",
+  "status",
+  "visibility",
+  "title",
+  "body",
+  "body_html",
+  "body_text",
+  "reply_to_id",
+  "thread_id",
+  "published_at",
+  "last_activity_at",
+  "created_at",
+  "updated_at"
 ) VALUES (
+  'pst_01kme7ja2mf4m7s2k8r5c9t0qh',
   'sit_01kme7j7j1f4m7s2k8r5c9t0qb',
+  'note',
+  'published',
+  NULL,
+  'First rehearsal reply',
+  '{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"First migration rehearsal reply."}]}]}',
+  '<p>First migration rehearsal reply.</p>',
+  'First migration rehearsal reply.',
   'pst_01kme7ja2mf4m7s2k8r5c9t0qf',
-  'col_01kme7j8f9f4m7s2k8r5c9t0qc',
-  1774200021
+  'pst_01kme7ja2mf4m7s2k8r5c9t0qf',
+  1774200030,
+  1774200030,
+  1774200030,
+  1774200030
 );
 
+INSERT INTO "post" (
+  "id",
+  "site_id",
+  "format",
+  "status",
+  "visibility",
+  "title",
+  "body",
+  "body_html",
+  "body_text",
+  "reply_to_id",
+  "thread_id",
+  "published_at",
+  "last_activity_at",
+  "created_at",
+  "updated_at"
+) VALUES (
+  'pst_01kme7ja2mf4m7s2k8r5c9t0qi',
+  'sit_01kme7j7j1f4m7s2k8r5c9t0qb',
+  'note',
+  'published',
+  NULL,
+  'Second rehearsal reply',
+  '{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Second migration rehearsal reply."}]}]}',
+  '<p>Second migration rehearsal reply.</p>',
+  'Second migration rehearsal reply.',
+  'pst_01kme7ja2mf4m7s2k8r5c9t0qh',
+  'pst_01kme7ja2mf4m7s2k8r5c9t0qf',
+  1774200040,
+  1774200040,
+  1774200040,
+  1774200040
+);
+
+INSERT INTO "post_collection" (
+  "site_id",
+  "post_id",
+  "collection_id",
+  "created_at",
+  "position",
+  "pinned_at"
+) VALUES
+  (
+    'sit_01kme7j7j1f4m7s2k8r5c9t0qb',
+    'pst_01kme7ja2mf4m7s2k8r5c9t0qf',
+    'col_01kme7j8f9f4m7s2k8r5c9t0qc',
+    1774200021,
+    7,
+    1774200300
+  ),
+  (
+    'sit_01kme7j7j1f4m7s2k8r5c9t0qb',
+    'pst_01kme7ja2mf4m7s2k8r5c9t0qh',
+    'col_01kme7j8f9f4m7s2k8r5c9t0qc',
+    1774200040,
+    5,
+    NULL
+  ),
+  (
+    'sit_01kme7j7j1f4m7s2k8r5c9t0qb',
+    'pst_01kme7ja2mf4m7s2k8r5c9t0qi',
+    'col_01kme7j8f9f4m7s2k8r5c9t0qc',
+    1774200030,
+    1,
+    1774200500
+  ),
+  (
+    'sit_01kme7j7j1f4m7s2k8r5c9t0qb',
+    'pst_01kme7ja2mf4m7s2k8r5c9t0qh',
+    'col_01kme7j8f9f4m7s2k8r5c9t0qd',
+    1774200060,
+    4,
+    1774200600
+  );
+
 INSERT INTO "path_registry" (
   "id",
   "site_id",

package/src/db/schema.ts

@@ -15,6 +15,7 @@ import {
   check,
 } from "drizzle-orm/sqlite-core";
 import { sql } from "drizzle-orm";
+import { SYSTEM_NAV_KEY_VALUES } from "../types/constants.js";
 
 const SITE_STATUSES = ["active", "suspended"] as const;
 const SITE_DOMAIN_KINDS = ["primary", "alias"] as const;
@@ -23,16 +24,8 @@ const FORMATS = ["note", "link", "quote"] as const;
 const STATUSES = ["draft", "published"] as const;
 const VISIBILITIES = ["public", "latest_hidden", "private"] as const;
 const COLLECTION_SORT_ORDERS = ["newest", "oldest", "rating_desc"] as const;
-const NAV_ITEM_TYPES = ["link", "system", "collection"] as const;
+const NAV_ITEM_TYPES = ["link", "system", "collection", "page"] as const;
 const NAV_ITEM_PLACEMENTS = ["header", "more"] as const;
-const SYSTEM_NAV_KEYS = [
-  "latest",
-  "featured",
-  "collections",
-  "archive",
-  "rss",
-  "settings",
-] as const;
 const UPLOAD_SESSION_STATES = [
   "pending",
   "uploaded",
@@ -161,6 +154,7 @@ export const posts = sqliteTable(
     url: text("url"),
     body: text("body"),
     bodyHtml: text("body_html"),
+    bodyHtmlVersion: integer("body_html_version").notNull().default(1),
     bodyText: text("body_text"),
     quoteText: text("quote_text"),
     summary: text("summary"),
@@ -170,8 +164,25 @@ export const posts = sqliteTable(
     previewProvider: text("preview_provider"),
     replyToId: text("reply_to_id"),
     threadId: text("thread_id").notNull(),
+    /**
+     * The author added this reply without announcing it. Persisted so both
+     * activity timestamps below stay recomputable from the rows alone.
+     * Always false on Thread roots.
+     */
+    quietReply: integer("quiet_reply", { mode: "boolean" })
+      .notNull()
+      .default(false),
     publishedAt: integer("published_at"),
+    /**
+     * Root only: newest published_at in the Thread, excluding quiet replies —
+     * "last announced". Drives Latest and the feeds.
+     */
     lastActivityAt: integer("last_activity_at"),
+    /**
+     * Root only: newest published_at in the Thread, quiet replies included —
+     * "last changed". Drives the archive's updated sort.
+     */
+    threadUpdatedAt: integer("thread_updated_at"),
     createdAt: integer("created_at").notNull(),
     updatedAt: integer("updated_at").notNull(),
   },
@@ -219,6 +230,9 @@ export const posts = sqliteTable(
     index("idx_post_site_root_published_activity")
       .on(table.siteId, table.lastActivityAt, table.id)
       .where(sql`${table.replyToId} IS NULL AND ${table.status} = 'published'`),
+    index("idx_post_site_root_thread_updated")
+      .on(table.siteId, table.threadUpdatedAt, table.id)
+      .where(sql`${table.replyToId} IS NULL AND ${table.status} = 'published'`),
     index("idx_post_site_root_draft_updated")
       .on(table.siteId, table.updatedAt, table.id)
       .where(sql`${table.replyToId} IS NULL AND ${table.status} = 'draft'`),
@@ -227,8 +241,8 @@ export const posts = sqliteTable(
       .where(
         sql`${table.replyToId} IS NOT NULL AND ${table.status} = 'published'`,
       ),
-    index("idx_post_site_featured_featured_at")
-      .on(table.siteId, table.featuredAt, table.threadId, table.id)
+    index("idx_post_site_featured_thread_published")
+      .on(table.siteId, table.threadId, table.publishedAt, table.id)
       .where(
         sql`${table.status} = 'published' AND ${table.featuredAt} IS NOT NULL`,
       ),
@@ -571,16 +585,16 @@ export const collectionDirectoryItems = sqliteTable(
 );
 
 // =============================================================================
-// Post-Collection Junction Table (M:N)
+// Thread-Collection Junction Table (M:N)
 // =============================================================================
 
-export const postCollections = sqliteTable(
-  "post_collection",
+export const threadCollections = sqliteTable(
+  "thread_collection",
   {
     siteId: text("site_id")
       .notNull()
       .references(() => sites.id, { onDelete: "cascade" }),
-    postId: text("post_id")
+    threadId: text("thread_id")
       .notNull()
       .references(() => posts.id, { onDelete: "cascade" }),
     collectionId: text("collection_id")
@@ -591,16 +605,16 @@ export const postCollections = sqliteTable(
     pinnedAt: integer("pinned_at"),
   },
   (table) => [
-    primaryKey({ columns: [table.siteId, table.postId, table.collectionId] }),
-    index("idx_post_collection_site_collection_id").on(
+    primaryKey({ columns: [table.siteId, table.threadId, table.collectionId] }),
+    index("idx_thread_collection_site_collection_id").on(
       table.siteId,
       table.collectionId,
     ),
-    index("idx_post_collection_site_collection_created_post").on(
+    index("idx_thread_collection_site_collection_created_thread").on(
       table.siteId,
       table.collectionId,
       table.createdAt,
-      table.postId,
+      table.threadId,
     ),
   ],
 );
@@ -622,11 +636,14 @@ export const navItems = sqliteTable(
       .notNull()
       .default("link"),
     systemKey: text("system_key", {
-      enum: SYSTEM_NAV_KEYS,
+      enum: SYSTEM_NAV_KEY_VALUES,
     }),
     collectionId: text("collection_id").references(() => collections.id, {
       onDelete: "cascade",
     }),
+    postId: text("post_id").references(() => posts.id, {
+      onDelete: "cascade",
+    }),
     label: text("label").notNull(),
     url: text("url").notNull(),
     placement: text("placement", {
@@ -653,14 +670,22 @@ export const navItems = sqliteTable(
         ${table.type} = 'link'
         AND ${table.systemKey} IS NULL
         AND ${table.collectionId} IS NULL
+        AND ${table.postId} IS NULL
       ) OR (
         ${table.type} = 'system'
         AND ${table.systemKey} IS NOT NULL
         AND ${table.collectionId} IS NULL
+        AND ${table.postId} IS NULL
       ) OR (
         ${table.type} = 'collection'
         AND ${table.systemKey} IS NULL
         AND ${table.collectionId} IS NOT NULL
+        AND ${table.postId} IS NULL
+      ) OR (
+        ${table.type} = 'page'
+        AND ${table.systemKey} IS NULL
+        AND ${table.collectionId} IS NULL
+        AND ${table.postId} IS NOT NULL
       )`,
     ),
     uniqueIndex("uq_nav_item_site_position").on(table.siteId, table.position),
@@ -670,6 +695,9 @@ export const navItems = sqliteTable(
     uniqueIndex("uq_nav_item_site_collection_id")
       .on(table.siteId, table.collectionId)
       .where(sql`${table.collectionId} IS NOT NULL`),
+    uniqueIndex("uq_nav_item_site_post_id")
+      .on(table.siteId, table.postId)
+      .where(sql`${table.postId} IS NOT NULL`),
   ],
 );
 

package/src/db/thread-activity.ts

@@ -0,0 +1,101 @@
+/**
+ * Thread activity — one definition, shared by every surface that orders by it.
+ *
+ * A Thread's activity is when it last **gained a post**. Editing an existing
+ * post is not activity: otherwise fixing a typo would drag a years-old thread
+ * back to the top of Latest and of every collection that holds it.
+ *
+ * This lived as three separate copies (the collection thread sort, the
+ * collection directory, and the Hugo export). One of them was changed in #144
+ * to treat a newer `updated_at` as activity and the others were not, so the
+ * same thread ranked differently depending on which page you were looking at,
+ * and the drift went unnoticed for months. Adding a fourth copy is the failure
+ * mode this module exists to prevent — call it instead.
+ *
+ * Two flavors of "last activity" exist, and they differ only in how they treat
+ * quiet replies:
+ *
+ * - `last_activity_at` — quiet replies excluded. "Last announced." Latest, the
+ *   feeds, and collection ordering read this.
+ * - `thread_updated_at` — quiet replies included. "Last changed." The
+ *   archive's updated sort reads this.
+ *
+ * Both are maintained on the Thread root by the post service; everything here
+ * only reads them, with fallbacks for rows that predate the columns.
+ */
+
+import { sql, type SQL, type SQLWrapper } from "drizzle-orm";
+
+/**
+ * Activity timestamp for a Thread root row, in SQL.
+ *
+ * Pass column references for a query whose rows are already Thread roots, or
+ * raw fragments (`sql.raw("root.last_activity_at")`) when reaching a root
+ * through a correlated subquery.
+ *
+ * **Correlated-subquery warning:** Drizzle only qualifies interpolated columns
+ * with their table name when the query has a join. In a single-table
+ * `select()`, `${posts.id}` renders as a bare `"id"`, which inside a subquery
+ * binds to the subquery's own alias instead of correlating to the outer row —
+ * silently, with no error. Write the outer table out (`"post"."id"`) in that
+ * case rather than interpolating.
+ *
+ * @param root - The root's three timestamp columns, most authoritative first
+ * @returns COALESCE expression usable in ORDER BY, GROUP BY, or a projection
+ *
+ * @example
+ * ```ts
+ * // Rows are already Thread roots (joined on thread_collection.thread_id):
+ * const activityAt = buildRootActivityExpr({
+ *   lastActivityAt: posts.lastActivityAt,
+ *   publishedAt: posts.publishedAt,
+ *   updatedAt: posts.updatedAt,
+ * });
+ * ```
+ */
+export function buildRootActivityExpr(root: {
+  lastActivityAt: SQLWrapper;
+  publishedAt: SQLWrapper;
+  updatedAt: SQLWrapper;
+}): SQL<number> {
+  return sql<number>`COALESCE(
+    ${root.lastActivityAt},
+    ${root.publishedAt},
+    ${root.updatedAt}
+  )`;
+}
+
+/** The Thread root's timestamp columns, named for a correlated subquery alias. */
+export function rootActivityColumns(alias: string): {
+  lastActivityAt: SQLWrapper;
+  publishedAt: SQLWrapper;
+  updatedAt: SQLWrapper;
+} {
+  return {
+    lastActivityAt: sql.raw(`${alias}.last_activity_at`),
+    publishedAt: sql.raw(`${alias}.published_at`),
+    updatedAt: sql.raw(`${alias}.updated_at`),
+  };
+}
+
+/**
+ * Activity timestamp for an already-loaded Thread root, in TypeScript.
+ *
+ * The same COALESCE order as {@link buildRootActivityExpr}, for callers that
+ * hold hydrated posts rather than a query builder.
+ *
+ * @param root - A Thread root post
+ * @returns Unix timestamp (seconds) of the root's last activity
+ *
+ * @example
+ * ```ts
+ * const activityAt = getRootActivityAt(threadRoot);
+ * ```
+ */
+export function getRootActivityAt(root: {
+  lastActivityAt?: number | null;
+  publishedAt?: number | null;
+  updatedAt: number;
+}): number {
+  return root.lastActivityAt ?? root.publishedAt ?? root.updatedAt;
+}