# FeedEntry Decoupling Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Replace the flat `liked_by_viewer`/`boosted_by_viewer` booleans and inline stats fields on `FeedEntry` with two named sub-structs (`EngagementStats`, `Option<ViewerContext>`), and fix the search adapter to compute real viewer context instead of hardcoding `false`.

**Architecture:** Three sequential tasks. Task 1 changes the domain model, which breaks compilation. Task 2 fixes all downstream construction sites and restores compilation. Task 3 adds the functional improvement — viewer-aware SQL in the search adapter.

**Tech Stack:** Rust, SQLx, Postgres trigram search (`pg_trgm`).

---

### Task 1: Add `EngagementStats` and `ViewerContext` to the domain model

**Files:**
- Modify: `crates/domain/src/models/feed.rs`

- [ ] **Step 1: Replace the flat fields on `FeedEntry` with two named sub-structs**

Replace the entire contents of `crates/domain/src/models/feed.rs` with:

```rust
use crate::models::{thought::Thought, user::User};
use crate::value_objects::UserId;

#[derive(Debug, Clone)]
pub struct EngagementStats {
    pub like_count:  i64,
    pub boost_count: i64,
    pub reply_count: i64,
}

/// Present only when an authenticated viewer made the request.
/// `liked`/`boosted` are the viewer's interaction state with this thought.
/// `None` means anonymous request or viewer context unavailable.
#[derive(Debug, Clone)]
pub struct ViewerContext {
    pub liked:   bool,
    pub boosted: bool,
}

#[derive(Debug, Clone)]
pub struct FeedEntry {
    pub thought: Thought,
    pub author:  User,
    pub stats:   EngagementStats,
    pub viewer:  Option<ViewerContext>,
}

#[derive(Debug, Clone)]
pub struct UserSummary {
    pub id: UserId,
    pub username: String,
    pub display_name: Option<String>,
    pub avatar_url: Option<String>,
    pub bio: Option<String>,
    pub thought_count: i64,
    pub follower_count: i64,
    pub following_count: i64,
}

#[derive(Debug, Clone)]
pub struct PageParams {
    pub page: u64,
    pub per_page: u64,
}
impl PageParams {
    pub fn offset(&self) -> i64 {
        ((self.page.saturating_sub(1)) * self.per_page) as i64
    }
    pub fn limit(&self) -> i64 {
        self.per_page as i64
    }
}

#[derive(Debug, Clone)]
pub struct Paginated<T> {
    pub items: Vec<T>,
    pub total: i64,
    pub page: u64,
    pub per_page: u64,
}
```

- [ ] **Step 2: Verify the domain crate compiles (other crates will break)**

```bash
cargo check -p domain 2>&1 | head -10
```

Expected: `domain` compiles clean. Other crates (`postgres`, `postgres-search`, `presentation`) will show errors referencing the removed fields — that is expected and will be fixed in Task 2.

- [ ] **Step 3: Commit the domain model change**

```bash
git add crates/domain/src/models/feed.rs
git commit -m "refactor(domain): FeedEntry — EngagementStats + Option<ViewerContext> sub-structs"
```

---

### Task 2: Fix downstream compilation — adapters and handler

**Files:**
- Modify: `crates/adapters/postgres/src/feed.rs` (line 136 — `row_to_entry`)
- Modify: `crates/adapters/postgres-search/src/lib.rs` (line 97 — `row_to_entry`)
- Modify: `crates/presentation/src/handlers/feed.rs` (line 22 — `to_thought_response`)

- [ ] **Step 1: Update `row_to_entry` in `postgres/src/feed.rs`**

Find `row_to_entry` in `crates/adapters/postgres/src/feed.rs` (around line 109). Replace the `Ok(FeedEntry { ... })` block (currently lines 136–144) with:

```rust
    Ok(FeedEntry {
        thought,
        author,
        stats: domain::models::feed::EngagementStats {
            like_count:  r.like_count,
            boost_count: r.boost_count,
            reply_count: r.reply_count,
        },
        viewer: Some(domain::models::feed::ViewerContext {
            liked:   r.liked_by_viewer,
            boosted: r.boosted_by_viewer,
        }),
    })
```

Note: `postgres/src/feed.rs` already builds `viewer = Some(...)` unconditionally here because its `feed_select(viewer)` function always produces `liked_by_viewer`/`boosted_by_viewer` columns — `false AS liked_by_viewer` when there is no viewer, and the real EXISTS result when there is one. The `Option<ViewerContext>` distinction (`None` = anonymous) is handled by the caller's knowledge of whether a viewer was passed. To preserve the `None`-when-no-viewer semantic, read how `viewer` is passed into the calling functions and thread it through.

Actually, the correct fix: the `row_to_entry` function doesn't know if a viewer was passed. Pass the viewer `Option<uuid::Uuid>` as a parameter so it can decide:

Replace the signature of `row_to_entry`:
```rust
fn row_to_entry(r: FeedRow, viewer: Option<uuid::Uuid>) -> Result<FeedEntry, DomainError> {
```

And change the construction:
```rust
    Ok(FeedEntry {
        thought,
        author,
        stats: domain::models::feed::EngagementStats {
            like_count:  r.like_count,
            boost_count: r.boost_count,
            reply_count: r.reply_count,
        },
        viewer: viewer.map(|_| domain::models::feed::ViewerContext {
            liked:   r.liked_by_viewer,
            boosted: r.boosted_by_viewer,
        }),
    })
```

Then update all call sites of `row_to_entry` inside `postgres/src/feed.rs`. Each `FeedRepository` method already has a `viewer` variable of type `Option<uuid::Uuid>`. Pass it through:

```rust
// Before:
.map(row_to_entry)
.collect::<Result<Vec<_>, _>>()?

// After:
.map(|r| row_to_entry(r, viewer))
.collect::<Result<Vec<_>, _>>()?
```

Read `crates/adapters/postgres/src/feed.rs` to find all five `impl FeedRepository` methods and update each `.map(row_to_entry)` call.

- [ ] **Step 2: Update `row_to_entry` in `postgres-search/src/lib.rs`**

In `crates/adapters/postgres-search/src/lib.rs`, find `row_to_entry` (line 70). Change the `Ok(FeedEntry { ... })` block (lines 97–105) to:

```rust
    Ok(FeedEntry {
        thought,
        author,
        stats: domain::models::feed::EngagementStats {
            like_count:  r.like_count,
            boost_count: r.boost_count,
            reply_count: r.reply_count,
        },
        viewer: None,   // Task 3 will fix this to use real viewer data
    })
```

Add `EngagementStats` and `ViewerContext` to the domain import at the top if needed (they're in `domain::models::feed`). The existing import already pulls in `FeedEntry` from that module.

- [ ] **Step 3: Update `to_thought_response` in `presentation/src/handlers/feed.rs`**

Find `to_thought_response` (line 22 in `crates/presentation/src/handlers/feed.rs`). Update it to read from the new sub-structs:

```rust
pub fn to_thought_response(e: &domain::models::feed::FeedEntry) -> ThoughtResponse {
    ThoughtResponse {
        id: e.thought.id.as_uuid(),
        content: e.thought.content.as_str().to_string(),
        author: to_user_response(&e.author),
        in_reply_to_id: e.thought.in_reply_to_id.as_ref().map(|id| id.as_uuid()),
        in_reply_to_url: None,
        visibility: e.thought.visibility.as_str().to_string(),
        content_warning: e.thought.content_warning.clone(),
        sensitive: e.thought.sensitive,
        like_count: e.stats.like_count,
        boost_count: e.stats.boost_count,
        reply_count: e.stats.reply_count,
        liked_by_viewer: e.viewer.as_ref().map(|v| v.liked).unwrap_or(false),
        boosted_by_viewer: e.viewer.as_ref().map(|v| v.boosted).unwrap_or(false),
        created_at: e.thought.created_at,
        updated_at: e.thought.updated_at,
    }
}
```

`ThoughtResponse` in `api-types/src/responses.rs` keeps `liked_by_viewer: bool` and `boosted_by_viewer: bool` — the wire format is unchanged.

- [ ] **Step 4: Compile check — full workspace must be clean**

```bash
cargo check --workspace 2>&1 | head -20
```

Expected: 0 errors. Fix any remaining references to the old flat fields (`e.like_count`, `e.liked_by_viewer`, etc.) — they must become `e.stats.like_count`, `e.viewer.as_ref().map(|v| v.liked).unwrap_or(false)`.

- [ ] **Step 5: Commit**

```bash
git add crates/adapters/postgres/src/feed.rs \
        crates/adapters/postgres-search/src/lib.rs \
        crates/presentation/src/handlers/feed.rs
git commit -m "refactor(adapters): update FeedEntry construction to use EngagementStats + ViewerContext"
```

---

### Task 3: Fix search adapter — real viewer context instead of hardcoded `false`

**Files:**
- Modify: `crates/adapters/postgres-search/src/lib.rs`

The `SearchPort::search_thoughts` signature already takes `viewer_id: Option<&UserId>` (the parameter is named `_viewer_id` because it was ignored). This task makes it real.

- [ ] **Step 1: Add `liked_by_viewer` and `boosted_by_viewer` to `FeedRow`**

In `crates/adapters/postgres-search/src/lib.rs`, find the `FeedRow` struct (line 27). Add two fields at the end:

```rust
#[derive(sqlx::FromRow)]
struct FeedRow {
    thought_id: uuid::Uuid,
    t_user_id: uuid::Uuid,
    content: String,
    in_reply_to_id: Option<uuid::Uuid>,
    visibility: String,
    content_warning: Option<String>,
    sensitive: bool,
    t_local: bool,
    thought_created_at: DateTime<Utc>,
    updated_at: Option<DateTime<Utc>>,
    author_id: uuid::Uuid,
    username: String,
    email: String,
    password_hash: String,
    display_name: Option<String>,
    bio: Option<String>,
    avatar_url: Option<String>,
    header_url: Option<String>,
    custom_css: Option<String>,
    author_local: bool,
    author_created_at: DateTime<Utc>,
    author_updated_at: DateTime<Utc>,
    like_count: i64,
    boost_count: i64,
    reply_count: i64,
    liked_by_viewer: bool,    // NEW
    boosted_by_viewer: bool,  // NEW
}
```

- [ ] **Step 2: Replace `FEED_SELECT` constant with a `feed_select(viewer)` function**

Delete the `const FEED_SELECT` and replace with a function that injects viewer-aware columns — identical pattern to `postgres/src/feed.rs`:

```rust
fn feed_select(viewer: Option<uuid::Uuid>) -> String {
    let viewer_checks = match viewer {
        Some(uid) => format!(
            "EXISTS(SELECT 1 FROM likes  WHERE user_id='{uid}' AND thought_id=t.id) AS liked_by_viewer,
             EXISTS(SELECT 1 FROM boosts WHERE user_id='{uid}' AND thought_id=t.id) AS boosted_by_viewer"
        ),
        None => "false AS liked_by_viewer, false AS boosted_by_viewer".to_string(),
    };
    format!(
        "
    SELECT
        t.id AS thought_id, t.user_id AS t_user_id, t.content,
        t.in_reply_to_id,
        t.visibility, t.content_warning, t.sensitive, t.local AS t_local,
        t.created_at AS thought_created_at, t.updated_at,
        u.id AS author_id, u.username, u.email, u.password_hash,
        u.display_name, u.bio, u.avatar_url, u.header_url, u.custom_css,
        u.local AS author_local,
        u.created_at AS author_created_at, u.updated_at AS author_updated_at,
        (SELECT COUNT(*) FROM likes  l WHERE l.thought_id=t.id) AS like_count,
        (SELECT COUNT(*) FROM boosts b WHERE b.thought_id=t.id) AS boost_count,
        (SELECT COUNT(*) FROM thoughts r WHERE r.in_reply_to_id=t.id) AS reply_count,
        {viewer_checks}
    FROM thoughts t JOIN users u ON u.id=t.user_id"
    )
}
```

- [ ] **Step 3: Update `row_to_entry` to use viewer fields**

Update `row_to_entry` to accept `viewer: Option<uuid::Uuid>` and build the `ViewerContext`:

```rust
fn row_to_entry(r: FeedRow, viewer: Option<uuid::Uuid>) -> Result<FeedEntry, DomainError> {
    let thought = Thought {
        id: ThoughtId::from_uuid(r.thought_id),
        user_id: UserId::from_uuid(r.t_user_id),
        content: Content::new_remote(r.content),
        in_reply_to_id: r.in_reply_to_id.map(ThoughtId::from_uuid),
        visibility: Visibility::from_db_str(&r.visibility)?,
        content_warning: r.content_warning,
        sensitive: r.sensitive,
        local: r.t_local,
        created_at: r.thought_created_at,
        updated_at: r.updated_at,
    };
    let author = User {
        id: UserId::from_uuid(r.author_id),
        username: Username::from_trusted(r.username),
        email: Email::from_trusted(r.email),
        password_hash: PasswordHash(r.password_hash),
        display_name: r.display_name,
        bio: r.bio,
        avatar_url: r.avatar_url,
        header_url: r.header_url,
        custom_css: r.custom_css,
        local: r.author_local,
        created_at: r.author_created_at,
        updated_at: r.author_updated_at,
    };
    Ok(FeedEntry {
        thought,
        author,
        stats: domain::models::feed::EngagementStats {
            like_count:  r.like_count,
            boost_count: r.boost_count,
            reply_count: r.reply_count,
        },
        viewer: viewer.map(|_| domain::models::feed::ViewerContext {
            liked:   r.liked_by_viewer,
            boosted: r.boosted_by_viewer,
        }),
    })
}
```

- [ ] **Step 4: Update `search_thoughts` to use viewer_id**

Find `search_thoughts` in `crates/adapters/postgres-search/src/lib.rs` (line 110). Rename `_viewer_id` → `viewer_id`, extract the viewer UUID, and thread it through `feed_select` and `row_to_entry`:

```rust
async fn search_thoughts(
    &self,
    query: &str,
    page: &PageParams,
    viewer_id: Option<&UserId>,          // was _viewer_id
) -> Result<Paginated<FeedEntry>, DomainError> {
    let viewer = viewer_id.map(|v| v.as_uuid());
    let select = feed_select(viewer);

    let total: i64 = sqlx::query_scalar(
        "SELECT COUNT(*) FROM thoughts t
         WHERE t.content % $1 AND t.visibility='public'",
    )
    .bind(query)
    .fetch_one(&self.pool)
    .await
    .map_err(|e| DomainError::Internal(e.to_string()))?;

    let sql = format!(
        "{select}
         WHERE t.content % $1 AND t.visibility='public'
         ORDER BY similarity(t.content, $1) DESC
         LIMIT $2 OFFSET $3"
    );
    let rows = sqlx::query_as::<_, FeedRow>(&sql)
        .bind(query)
        .bind(page.limit())
        .bind(page.offset())
        .fetch_all(&self.pool)
        .await
        .map_err(|e| DomainError::Internal(e.to_string()))?;

    Ok(Paginated {
        items: rows
            .into_iter()
            .map(|r| row_to_entry(r, viewer))
            .collect::<Result<Vec<_>, _>>()?,
        total,
        page: page.page,
        per_page: page.per_page,
    })
}
```

Note: `USER_SELECT` from `postgres::user` is no longer used in this file after the switch from const to function. Remove the `use postgres::user::{UserRow, USER_SELECT};` import if `UserRow`/`USER_SELECT` are no longer referenced.

- [ ] **Step 5: Add an integration test for viewer-aware search**

In the `#[cfg(test)]` module in `postgres-search/src/lib.rs`, add after the existing tests:

```rust
#[sqlx::test(migrations = "../postgres/migrations")]
async fn search_thoughts_sets_viewer_context_when_authed(pool: sqlx::PgPool) {
    use domain::ports::{LikeRepository, UserWriter};
    use postgres::{like::PgLikeRepository, user::PgUserRepository};
    use domain::models::social::Like;
    use domain::value_objects::LikeId;

    let (alice, thought) = seed_thought(&pool, "alice", "hello world").await;

    // alice likes her own thought
    let like_repo = PgLikeRepository::new(pool.clone());
    like_repo.save(&Like {
        id: LikeId::new(),
        user_id: alice.id.clone(),
        thought_id: thought.id.clone(),
        ap_id: None,
        created_at: chrono::Utc::now(),
    }).await.unwrap();

    let repo = PgSearchRepository::new(pool);

    // with viewer — should see liked = true
    let authed = repo
        .search_thoughts("hello", &PageParams { page: 1, per_page: 20 }, Some(&alice.id))
        .await
        .unwrap();
    assert_eq!(authed.items.len(), 1);
    let ctx = authed.items[0].viewer.as_ref().expect("viewer context present");
    assert!(ctx.liked, "alice should see the thought as liked");
    assert!(!ctx.boosted);

    // without viewer — viewer should be None
    let anon = repo
        .search_thoughts("hello", &PageParams { page: 1, per_page: 20 }, None)
        .await
        .unwrap();
    assert_eq!(anon.items.len(), 1);
    assert!(anon.items[0].viewer.is_none(), "anonymous request has no viewer context");
}
```

- [ ] **Step 6: Compile check**

```bash
cargo check --workspace 2>&1 | head -20
```

Expected: 0 errors.

- [ ] **Step 7: Commit**

```bash
git add crates/adapters/postgres-search/src/lib.rs
git commit -m "fix(search): viewer-aware SQL in search_thoughts — ViewerContext now real instead of hardcoded false"
```

---

## Self-Review

**Spec coverage:**

| Spec requirement | Task |
|---|---|
| Add `EngagementStats` struct | Task 1 |
| Add `ViewerContext` struct | Task 1 |
| `FeedEntry.viewer: Option<ViewerContext>` | Task 1 |
| postgres feed adapter uses new structs | Task 2 |
| Handler `to_thought_response` uses new fields | Task 2 |
| search adapter `viewer: None` (structural fix) | Task 2 |
| search adapter uses real viewer SQL (functional fix) | Task 3 |
| `viewer: None` = anonymous; `Some(...)` = viewer present | Tasks 2 + 3 |
| Wire format (`ThoughtResponse`) unchanged | Task 2 step 3 |

**No placeholders found.**

**Type consistency:** `EngagementStats` and `ViewerContext` defined in Task 1, used by name in Tasks 2 and 3. `row_to_entry(r, viewer)` signature matches in both Task 2 and Task 3. `viewer: Option<uuid::Uuid>` threaded consistently.