backend-conventionslisted

# Backend Conventions — anthropic-watch This project is a scraper pipeline, not a web service. There is no HTTP API, no database, no auth. Backend conventions here cover scrapers, fetching, state, and feed generation. Authoritative deep-dive: `docs/ARCHITECTURE.md`. This document is the working-memory summary for agents. ## Scraper Contract Every scraper is a function with a fixed signature: - **Input:** source config object from `src/sources.js` (must include `key`, `category`, `name`, and type-specific fields) - **Output:** `Array<Item>` on success; **throws** on failure - **Item shape:** 8 fields — `id`, `title`, `date`, `url`, `snippet`, `source`, `sourceCategory`, `sourceName` Rules: 1. **Never wrap scraper logic in `try/catch { return [] }`.** Let errors propagate. The orchestrator's `Promise.allSettled` captures them, records the real message, and increments `consecutiveFailures`. The v1.0.1 silent-failure bug was caused by scrapers catching their own errors. 2. **Empty array return means "no items right now"** — it is not a failure signal. Return `[]` when the source is live but has nothing new. 3. **IDs must be stable.** Don't use timestamps or random values. Use source-natural IDs: `tag_name`, post URL, version string, incident ID, heading text. Use SHA-256 hashes only as a fallback when no natural ID exists. 4. **`date` may be `null`** when the source legitimately has no per-item date (e.g. the models reference table). Never fake a date. 5. **`snippet` max 3