Add historical scoring, breakout radar, source-health, Reddit adapter, env/schema refactors, and frontend history UI

[not-wowmagic]

Motivation

• Provide explicit persisted observation semantics and deterministic historical scoring so BookPulse can surface explainable trend history and breakout intelligence.
• Expose pipeline operational state via a public source-health endpoint to avoid silently substituting demo data and to preserve latest-known-good snapshots on partial failures.
• Replace brittle provider assumptions by failing unavailable adapters closed (Goodreads/TikTok) and implement an OAuth-bounded Reddit adapter for production collection.
• Harden environment parsing and Supabase interactions for edge/node contexts and support new explicit observation fields and idempotent persistence.

Description

• Introduces explainable historical scoring and ranking in backend/core/trendScorer.js with computeHistoricalTrend and rankBreakouts, and exposes Breakout Radar via GET /api/breakouts backed by backend/repository/breakoutRepository.js.
• Adds per-book persisted history API GET /api/books/:canonicalKey/history implemented in api/books/[canonicalKey]/history.js and repository logic in backend/repository/historyRepository.js that returns sparse, signal-aware series and trend intelligence.
• Adds GET /api/source-health (edge) implemented in api/source-health.js and backend/core/sourceHealth.js that derives public health states from recent ingest_runs and read-model availability.
• Refactors environment validation in backend/config/env.js to normalize defaults and enforce node/edge constraints, updates .env.example accordingly, and makes getSupabaseAdminClient async with dynamic import in backend/gateways/supabase.js.
• Evolves ingestion and persistence to explicit signal semantics and idempotent observation keys by adding columns and migrations (see supabase/migrations/*), switching source_mentions upsert to observation_key and enriching buildMentionRows in backend/pipeline/ingestRun.js with signal_type, signal_value, provider_record_id, and observation_key generation.
• Implements a robust Reddit adapter backend/pipeline/sourceAdapters/reddit.js with OAuth endpoint validation, pagination, bounded collection window, stable provider IDs, and normalization to discussion_count; makes Goodreads/TikTok adapters fail-closed without authorized integrations.
• Adds REST helpers for public read projections in backend/gateways/supabase.js including ingestRunsRest and readModelByKeyRest used by source-health and other edge handlers.
• Frontend additions include historical detail UI and interactions: BookDetail, BreakoutRadar, SourceHealth, Methodology, services in src/services/historyApi.js, CSS updates, and wiring in src/App.jsx and TrendingBoard.jsx to open book history dialogs.
• Adds migrations to introduce explicit observation contract and public read boundaries and a preflight that fails if duplicate observation identities exist (supabase/migrations/*).
• Test and docs additions: contract docs docs/contracts.md, feasibility/methodology/operational docs, and a comprehensive backend test suite with new unit tests for Reddit adapter, history, scoring, breakout radar, and source health.

Testing

• Ran the backend unit suite with npm run test:backend, and the backend tests passed (45 tests across newly added backend/tests/*).
• Ran focused tests: backend/tests/contractsFixture.test.js, backend/tests/sourceHealth.test.js, backend/tests/historyRepository.test.js, backend/tests/redditAdapter.test.js, backend/tests/historicalTrendScorer.test.js, and backend/tests/breakoutRepository.test.js, and they succeeded in the test environment.
• The repository includes fixtures and deterministic assertions to validate signal semantics, windowing, ranking movement, and adapter pagination/deduplication.

---

Codex Task

[vercel]

Deployment failed for project book-pulse with the following error:

Hobby accounts are limited to daily cron jobs. This cron expression (*/15 * * * *) would run more than once per day. Upgrade to the Pro plan to unlock all Cron Jobs features on Vercel.

Learn More: https://vercel.link/3Fpeeb1