api(personal): pin manual posts/upvotes for 14 d then keep elevated

User-action rows (manual Post button + upvote) now lead the
personal page by their action timestamp for 14 d, then fall back
to a +12 score boost so they stay "quite high" but a strong recent
parsed doc can surpass them.

Schema
- documents.created_via_post BOOLEAN DEFAULT FALSE
  Distinguishes manual Post-button rows from background syncs and
  pipeline imports — both already share the documents table.

Backend
- BulkSaveRequest gains optional `via: String`. The /search compose
  dialog sends `via: "post"`; sync calls + MCP omit it.
- INSERT stamps `created_via_post = ($12::bool)`. ON CONFLICT
  preserves a prior TRUE via `OR EXCLUDED.created_via_post`.
- Personal-page ORDER BY (both VIP fast path and legacy path):
    Tier 1: hard pin within 14 d by GREATEST(fav.created_at,
            CASE WHEN created_via_post THEN created_at END).
    Tier 2: +12 score boost for any user-action row (any age).
            Older posts stay elevated; a high-scoring parsed doc
            still wins on its own merit.
    Tier 3: snapshot score, date, url (existing tiebreakers).

Bonus
- favorite_documents.sql was created out-of-band on prod and never
  in the boot migration list. A fresh local / DR-restored install
  would have booted without the table and every personal-page hit
  500'd. Wired in now.

Local verification: F (1 d upvote) → A (3 d post) → D (parsed
score 40) → B (30 d post, 5+12=17) → C (90 d post) → E (parsed
score 15) — matches the spec exactly.

Author: raphaelsty

api/src/handlers/auth.rs

@@ -2747,6 +2747,14 @@ pub struct BulkSaveRequest {
     /// some bookmarked URLs unstarred when the second call failed.
     #[serde(default)]
     pub favorite: bool,
+    /// Provenance flag. Set by the /search "Post" compose dialog
+    /// (`via = "post"`) to mark the row as a manual user action;
+    /// the personal-page sort pins these to the top by
+    /// `created_at`. Omitted by bulk sync calls and the MCP
+    /// upsert path so pipeline-style imports don't dominate the
+    /// page on every refresh.
+    #[serde(default)]
+    pub via: Option<String>,
 }
 
 #[derive(Serialize)]
@@ -2892,10 +2900,15 @@ pub async fn bulk_save_documents(
     //              so pipeline syncs don't blow away user-curated tags.
     //   * deleted: clear — re-posting a soft-deleted URL resurrects it,
     //              same way the merge branch of update_document does.
+    // $12 = TRUE when this came from the /search compose dialog
+    // (`via = "post"` in the request). Pipeline-style imports leave it
+    // FALSE so they don't pin to the top of the personal page.
+    let via_post: bool = req.via.as_deref() == Some("post");
     let sql = "
         INSERT INTO documents (
             user_id, url, title, summary, date, tags, extra_tags,
-            source, source_url, public, linked_urls, link_hosts
+            source, source_url, public, linked_urls, link_hosts,
+            created_via_post
         )
         SELECT $1, u.url, u.title, u.summary,
                NULLIF(u.date, '')::date,
@@ -2905,7 +2918,8 @@ pub async fn bulk_save_documents(
                u.source, u.source_url, u.public,
                COALESCE(u.linked_urls::jsonb, '[]'::jsonb),
                CASE WHEN u.link_hosts = '' THEN '{}'::text[]
-                    ELSE string_to_array(u.link_hosts, ',') END
+                    ELSE string_to_array(u.link_hosts, ',') END,
+               $12::bool
           FROM UNNEST($2::text[], $3::text[], $4::text[], $5::text[],
                       $6::text[], $7::text[], $8::bool[], $9::text[],
                       $10::text[], $11::text[])
@@ -2941,6 +2955,13 @@ pub async fn bulk_save_documents(
                 -- away from the favorite-only lifecycle so a later
                 -- un-upvote no longer deletes the row.
                 created_via_favorite = FALSE,
+                -- Once a row has been authored by the user via
+                -- Post, keep that flag set on subsequent syncs of
+                -- the same URL (a later background sync of the same
+                -- URL shouldn't strip the manual-action provenance).
+                -- A direct re-post (`via=post` again) refreshes the
+                -- flag to TRUE just like the first time.
+                created_via_post = documents.created_via_post OR EXCLUDED.created_via_post,
                 deleted = FALSE,
                 updated_at = now()
     ";
@@ -2967,6 +2988,7 @@ pub async fn bulk_save_documents(
         .bind(&tag_csvs)
         .bind(&linked_urls_json)
         .bind(&link_hosts_csv)
+        .bind(via_post)
         .execute(&mut *tx)
         .await;
 

api/src/handlers/users.rs

@@ -424,6 +424,7 @@ pub async fn list_documents(
                    d.linked_urls,\n\
                    d.link_hosts,\n\
                    d.created_at,\n\
+                   d.created_via_post,\n\
                    d.canonical_url,\n\
                    d.canonical_referenced_urls\n\
               FROM documents d\n\
@@ -553,8 +554,33 @@ pub async fn list_documents(
                LEFT JOIN users uu ON uu.username = $1\n\
                LEFT JOIN favorite_documents fav\n\
                  ON fav.user_id = uu.id AND fav.url = c.url\n\
-              ORDER BY fav.created_at DESC NULLS LAST,\n\
-                       c.date DESC NULLS LAST, c.created_at DESC",
+              ORDER BY CASE\n\
+                           WHEN GREATEST(\n\
+                                    fav.created_at,\n\
+                                    CASE WHEN c.created_via_post THEN c.created_at END\n\
+                                ) > now() - interval '14 days'\n\
+                           THEN GREATEST(\n\
+                                    fav.created_at,\n\
+                                    CASE WHEN c.created_via_post THEN c.created_at END\n\
+                                )\n\
+                       END DESC NULLS LAST,\n\
+                       -- After the 14-d hard pin expires, user-action\n\
+                       -- rows keep a +12 bump on their date-based sort\n\
+                       -- so they stay elevated; a strong recent parsed\n\
+                       -- doc still surpasses them when its score wins.\n\
+                       -- The legacy path doesn't carry a per-doc score\n\
+                       -- column, so we approximate \"score\" via\n\
+                       -- `c.date` and add a virtual day-bump on the\n\
+                       -- date axis only for user-action rows.\n\
+                       (c.date + CASE\n\
+                           WHEN GREATEST(\n\
+                                    fav.created_at,\n\
+                                    CASE WHEN c.created_via_post THEN c.created_at END\n\
+                                ) IS NOT NULL\n\
+                           THEN INTERVAL '30 days'\n\
+                           ELSE INTERVAL '0'\n\
+                       END) DESC NULLS LAST,\n\
+                       c.created_at DESC",
         );
     } else {
         sql.push_str(
@@ -593,7 +619,7 @@ pub async fn list_documents(
                 SELECT DISTINCT ON (anchor_url)\n\
                        url, title, summary, date, tags, extra_tags,\n\
                        source, source_url, indexed, linked_urls, link_hosts,\n\
-                       created_at\n\
+                       created_at, created_via_post\n\
                   FROM candidate_anchors\n\
                  ORDER BY anchor_url, image_count DESC, url_count DESC,\n\
                           date DESC NULLS LAST, created_at DESC\n\
@@ -607,8 +633,29 @@ pub async fn list_documents(
                LEFT JOIN users uu ON uu.username = $1\n\
                LEFT JOIN favorite_documents fav\n\
                  ON fav.user_id = uu.id AND fav.url = dedup.url\n\
-              ORDER BY fav.created_at DESC NULLS LAST,\n\
-                       dedup.date DESC NULLS LAST, dedup.created_at DESC",
+              ORDER BY CASE\n\
+                           WHEN GREATEST(\n\
+                                    fav.created_at,\n\
+                                    CASE WHEN dedup.created_via_post THEN dedup.created_at END\n\
+                                ) > now() - interval '14 days'\n\
+                           THEN GREATEST(\n\
+                                    fav.created_at,\n\
+                                    CASE WHEN dedup.created_via_post THEN dedup.created_at END\n\
+                                )\n\
+                       END DESC NULLS LAST,\n\
+                       -- Same date-shift as the skip_dedup branch:\n\
+                       -- after the 14-d pin expires, user-action rows\n\
+                       -- ride 30 days ahead of their actual date so\n\
+                       -- they stay elevated. Pipeline rows shift 0d.\n\
+                       (dedup.date + CASE\n\
+                           WHEN GREATEST(\n\
+                                    fav.created_at,\n\
+                                    CASE WHEN dedup.created_via_post THEN dedup.created_at END\n\
+                                ) IS NOT NULL\n\
+                           THEN INTERVAL '30 days'\n\
+                           ELSE INTERVAL '0'\n\
+                       END) DESC NULLS LAST,\n\
+                       dedup.created_at DESC",
         );
     }
     // Server-side cap so the personal page doesn't have to ship the
@@ -786,12 +833,15 @@ async fn try_list_documents_from_snapshot(
         .unwrap_or_default();
 
     // Build the SQL incrementally to keep $N placeholders aligned.
-    // The LEFT JOIN on favorite_documents is what pins upvoted docs
-    // to the top of the page (see the ORDER BY below) — every doc
-    // the page-owner has favourited gets `fav.created_at` non-null,
-    // and we sort that ASC NULLS LAST so the freshest upvote leads.
+    // Two LEFT JOINs feed the ORDER BY's "user activity" sort key:
+    //   * favorite_documents → upvotes (fav.created_at)
+    //   * documents.created_via_post → manual Post-button rows
+    //                                  (d_post.created_at)
+    // Whichever timestamp is more recent wins, so an upvote made
+    // after a post still rises above it. Pipeline-imported rows
+    // leave both slots NULL and fall back to feed-score order.
     let mut sql = String::from(
-        "SELECT ps.url,\n         ps.title,\n         ps.summary,\n         COALESCE(to_char(ps.date, 'YYYY-MM-DD'), '') AS date,\n         ps.tags,\n         ps.extra_tags,\n         ps.source,\n         ps.source_url,\n         ps.indexed,\n         ps.linked_urls,\n         ps.link_hosts,\n         COALESCE(to_char(ps.date AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS\"Z\"'), '') AS created_at,\n         ps.sharers,\n         ps.sharer_count\n    FROM personal_snapshot ps\n    JOIN users u ON u.id = ps.user_id\n    LEFT JOIN favorite_documents fav\n      ON fav.user_id = ps.user_id AND fav.url = ps.url\n   WHERE u.username = $1",
+        "SELECT ps.url,\n         ps.title,\n         ps.summary,\n         COALESCE(to_char(ps.date, 'YYYY-MM-DD'), '') AS date,\n         ps.tags,\n         ps.extra_tags,\n         ps.source,\n         ps.source_url,\n         ps.indexed,\n         ps.linked_urls,\n         ps.link_hosts,\n         COALESCE(to_char(ps.date AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS\"Z\"'), '') AS created_at,\n         ps.sharers,\n         ps.sharer_count\n    FROM personal_snapshot ps\n    JOIN users u ON u.id = ps.user_id\n    LEFT JOIN favorite_documents fav\n      ON fav.user_id = ps.user_id AND fav.url = ps.url\n    LEFT JOIN documents d_post\n      ON d_post.user_id = ps.user_id AND d_post.url = ps.url\n     AND d_post.deleted = FALSE\n   WHERE u.username = $1",
     );
     let mut idx: usize = 2;
     if !sources_vec.is_empty() {
@@ -816,13 +866,26 @@ async fn try_list_documents_from_snapshot(
         sql.push_str(&format!(" AND ps.categories && ${idx}"));
         idx += 1;
     }
-    // Upvoted docs ALWAYS lead, sorted by most-recent upvote first.
-    // The rest of the library follows in feed-score order. Using
-    // `NULLS LAST` on the upvote timestamp keeps non-favourited rows
-    // out of the front block; sorting `fav.created_at DESC` puts
-    // freshly-upvoted items at the very top.
+    // User-activity boost (manual Post + upvote) on the personal
+    // page — two-tier so fresh actions hard-pin and older ones still
+    // stay elevated but yield to a strong recent parsed doc.
+    //
+    //   * Tier 1 — hard pin (≤ 14 d): the sort uses
+    //     `GREATEST(fav.created_at, post.created_at)` as the first
+    //     key. Today's upvote beats yesterday's post; a Post lands
+    //     instantly at the top.
+    //   * Tier 2 — score boost (any age): every user-action row gets
+    //     a +12 bump on `ps.score` for the secondary sort key. After
+    //     the 14-d pin expires the row still ranks like a top-tier
+    //     doc, so it stays "quite high" — but a parsed doc that
+    //     genuinely scores higher (recent, broadly shared, sci-
+    //     anchored) can now surpass it.
+    //   * Pipeline-imported docs leave both inputs NULL (the
+    //     `created_via_post` guard masks them on the post side, no
+    //     favorite_documents row on the upvote side) so they sort
+    //     by raw `ps.score` without the bump.
     sql.push_str(
-        "\n   ORDER BY fav.created_at DESC NULLS LAST,\n            ps.score DESC,\n            ps.date DESC NULLS LAST,\n            ps.url",
+        "\n   ORDER BY CASE\n                WHEN GREATEST(\n                         fav.created_at,\n                         CASE WHEN d_post.created_via_post THEN d_post.created_at END\n                     ) > now() - interval '14 days'\n                THEN GREATEST(\n                         fav.created_at,\n                         CASE WHEN d_post.created_via_post THEN d_post.created_at END\n                     )\n            END DESC NULLS LAST,\n            (ps.score + CASE\n                WHEN GREATEST(\n                         fav.created_at,\n                         CASE WHEN d_post.created_via_post THEN d_post.created_at END\n                     ) IS NOT NULL\n                THEN 12.0\n                ELSE 0\n            END) DESC,\n            ps.date DESC NULLS LAST,\n            ps.url",
     );
     let mut limit_val: Option<i64> = None;
     if let Some(n) = params.limit {

api/src/main.rs

@@ -367,6 +367,16 @@ async fn run_sql_migrations(pool: &sqlx::PgPool) -> Result<(), sqlx::Error> {
             "favorites.sql",
             include_str!("../../sources/sql/favorites.sql"),
         ),
+        // Per-URL upvotes (the heart icon on every doc card). Distinct
+        // from `favorites.sql` which tracks "I follow this person".
+        // Was previously created out-of-band on prod and missing from
+        // this list — a fresh local install (or any DR restore) would
+        // boot without the table and every /api/users/<slug>/documents
+        // request 500s.
+        (
+            "favorite_documents.sql",
+            include_str!("../../sources/sql/favorite_documents.sql"),
+        ),
         ("follows.sql", include_str!("../../sources/sql/follows.sql")),
         ("events.sql", include_str!("../../sources/sql/events.sql")),
         (

sources/sql/documents.sql

@@ -140,6 +140,23 @@ BEGIN
         ALTER TABLE documents
             ADD COLUMN created_via_favorite BOOLEAN NOT NULL DEFAULT FALSE;
     END IF;
+    -- created_via_post: TRUE iff the row was inserted by the user
+    -- clicking the "Post" button in /search compose (NOT by a
+    -- background sync, an upvote-mirror, or the Python pipeline).
+    -- The personal page uses this flag to pin manual posts to the
+    -- top of the page by their `created_at`, sharing the same slot
+    -- as upvotes (`favorite_documents.created_at`) — the most
+    -- recent of the two wins, so an upvote made AFTER a post still
+    -- rises above it. Pipeline-imported docs leave the flag FALSE
+    -- so they slot into the natural feed-score order instead of
+    -- consistently topping the page on every refresh cycle.
+    IF NOT EXISTS (
+        SELECT 1 FROM information_schema.columns
+         WHERE table_name = 'documents' AND column_name = 'created_via_post'
+    ) THEN
+        ALTER TABLE documents
+            ADD COLUMN created_via_post BOOLEAN NOT NULL DEFAULT FALSE;
+    END IF;
     -- Inline link previews. Replaces the old "create a companion
     -- document per URL embedded in a tweet" pattern: a tweet with N
     -- external links now stays a single row whose `linked_urls`

web/search/page.js

@@ -8509,6 +8509,10 @@
               public: true,
             },
           ],
+          // Provenance — backend stamps `created_via_post = TRUE`
+          // so the personal page pins this row to the top by
+          // `created_at`. Background-sync calls omit this field.
+          via: "post",
         }),
       });
       if (!r.ok) throw new Error(`HTTP ${r.status}`);