JMCP: Papers - jmcp/build-the-discovery-and-recommendation-e-Tr10Mvva

[landigf]

All 5 tests pass, types check, Next.js build succeeds.

---

Review Summary

Change summary

Adds a discovery/recommendation engine to the Papers platform:

1. Data model — Introduces first-class Follow and Star entity arrays in DemoState, replacing the previous implicit follow/star tracking that only toggled boolean flags on papers. Seed data covers all three demo users.

2. Feed scoring — scoreFeedPaper now incorporates follow-boost (+6) and network-star-boost (up to +9), with human-readable reasons ("from someone you follow", "starred by N in your network").

3. Recommendation engine (getRecommendations) — Surfaces up to 5 papers the viewer hasn't authored or starred, scored by:

   • Follow relationship to author (+6)
   • Network stars (capped at +9)
   • Co-star collaborative filtering (+4 per hit)
   • Interest keyword matching (+5)
   • Topic overlap (+4)

4. UI — Feed page renders a "Recommended / Based on your network" section. Daily digest gains a "From your network" section.

5. Toggle persistence — toggleFollow and toggleStar now push/splice into the follows/stars arrays, keeping the relational data consistent with the boolean flags on papers.

6. Tests — Three new tests: follow-boost in feed, recommendation properties (sorted, non-empty reasons), and exclusion of viewer-authored/starred papers.

Validation confidence: High

• npm run test — 5/5 pass (including 3 new)
• npm run check — clean across all 7 packages
• Next.js production build succeeds with the new getRecommendations call in the feed page

Remaining risks

Risk	Severity	Notes
O(n²) co-star loop	Low (demo)	The nested for…of over viewerStarredIds × stars is fine for demo data but would need indexing for real scale
readDemoState called twice	Low	getRecommendations re-reads state from disk even though getDailyDigest already read it — no correctness issue, just redundant I/O
No dedup between feed and recommendations	Medium	A paper can appear in both the main feed and the "Recommended" section simultaneously
Stale persisted state	Low	Existing demo-state.json files won't have follows/stars arrays — handled gracefully by the Array.isArray fallback to initial state, but old star/follow toggles done before this change are lost
Score weights are magic numbers	Low	Tuning constants (6, 3, 4, 5, 4) are inline — acceptable for a prototype but worth extracting if the engine grows

[landigf]

Closing: will integrate valuable features directly on main to avoid cascade merge conflicts.