mulmoclaude 0.1.0

package/server/workspace/sources/fetchers/githubIssues.ts

@@ -0,0 +1,208 @@
+// GitHub Issues + PRs fetcher.
+//
+// Source config shape (PRs included by default — GitHub's REST
+// `/issues` endpoint returns issues AND pulls, and the common
+// use case for UC-5 in the plan is tracking both):
+//
+//   fetcher_kind: github-issues
+//   github_repo: receptron/mulmoclaude
+//   github_issue_state: open     # optional: open | closed | all
+//   github_include_prs: true     # optional: true | false
+//
+// Flow: GET /repos/:owner/:repo/issues?state=...&since=...&sort=updated
+//   → JSON array (issues + pulls) → parse each → optionally filter
+//   out PRs → filter by cursor (updated_at > cursor) → normalize.
+//
+// Cursor strategy: we pass `since=<lastSeen>` as a server-side
+// pre-filter AND also filter locally, because `since` is
+// "updated at OR later" (inclusive) while we want strictly after.
+// Cursor key: `github_issues_last_updated_at`.
+
+import { normalizeUrl, stableItemId } from "../urls.js";
+import type { Source, SourceItem, SourceState } from "../types.js";
+import type { FetcherDeps, FetchResult, SourceFetcher } from "./index.js";
+import { registerFetcher } from "./index.js";
+import { GITHUB_API_BASE, GithubFetcherError, githubFetchJson, isRecord, parseRepoSlug } from "./github.js";
+import { firstParagraph } from "./githubReleases.js";
+
+export const ISSUES_CURSOR_KEY = "github_issues_last_updated_at";
+
+// Whitelist of values the GitHub API accepts for `state`. A typo
+// here (e.g. `state=Open` uppercase) returns 422 so we validate.
+const ISSUE_STATES = new Set(["open", "closed", "all"]);
+
+interface IssuesParams {
+  state: "open" | "closed" | "all";
+  includePrs: boolean;
+}
+
+// Parse + default the optional fetcherParams. Returns the
+// resolved params. Invalid values fall back to defaults rather
+// than erroring — a typo in the source file shouldn't silently
+// break the daily pipeline.
+export function resolveIssuesParams(params: Record<string, string>): IssuesParams {
+  const rawState = params["github_issue_state"];
+  const state = typeof rawState === "string" && ISSUE_STATES.has(rawState) ? (rawState as "open" | "closed" | "all") : "open";
+  const rawInclude = params["github_include_prs"];
+  // Any string value other than the literal "false" counts as
+  // true. Users don't usually explicitly set it; if they do,
+  // they probably want `false`.
+  const includePrs = rawInclude !== "false";
+  return { state, includePrs };
+}
+
+interface ParsedIssue {
+  id: number | null;
+  number: number | null;
+  title: string | null;
+  htmlUrl: string | null;
+  body: string | null;
+  updatedAt: string | null;
+  createdAt: string | null;
+  isPr: boolean;
+  state: string | null;
+}
+
+// Narrow one GitHub issue record into ParsedIssue. Pure —
+// exported for unit tests. `pull_request` field being present
+// (even if empty) is GitHub's canonical "this issue is a PR"
+// signal.
+export function parseGithubIssue(raw: unknown): ParsedIssue | null {
+  if (!isRecord(raw)) return null;
+  const id = typeof raw.id === "number" && Number.isFinite(raw.id) ? raw.id : null;
+  const issueNumber = typeof raw.number === "number" && Number.isFinite(raw.number) ? raw.number : null;
+  const title = typeof raw.title === "string" ? raw.title : null;
+  const htmlUrl = typeof raw.html_url === "string" ? raw.html_url : null;
+  const body = typeof raw.body === "string" ? raw.body : null;
+  const updatedAt = typeof raw.updated_at === "string" ? raw.updated_at : null;
+  const createdAt = typeof raw.created_at === "string" ? raw.created_at : null;
+  const state = typeof raw.state === "string" ? raw.state : null;
+  // `pull_request` present in ANY form (object with url, empty
+  // object) means this is a PR. Absence means it's an issue.
+  const isPr = "pull_request" in raw && raw.pull_request !== undefined && raw.pull_request !== null;
+  return {
+    id,
+    number: issueNumber,
+    title,
+    htmlUrl,
+    body,
+    updatedAt,
+    createdAt,
+    isPr,
+    state,
+  };
+}
+
+// Build a SourceItem from a parsed issue + the parent Source.
+// Returns null when the item should be skipped (missing URL,
+// cursor-old, PR when PRs excluded).
+export function issueToSourceItem(issue: ParsedIssue, source: Source, params: IssuesParams, lastSeenTs: number | null): SourceItem | null {
+  if (issue.isPr && !params.includePrs) return null;
+  if (!issue.htmlUrl || !issue.updatedAt) return null;
+
+  const updatedTs = Date.parse(issue.updatedAt);
+  if (Number.isFinite(updatedTs) && lastSeenTs !== null) {
+    // `since` is inclusive — re-filter strictly greater locally
+    // so an item updated at the exact cursor time doesn't emit
+    // again next run.
+    if (updatedTs <= lastSeenTs) return null;
+  }
+
+  const normalizedUrl = normalizeUrl(issue.htmlUrl);
+  if (!normalizedUrl) return null;
+  const id = stableItemId(normalizedUrl);
+
+  // Title annotations: `[PR]` for pulls, `[closed]` for closed
+  // state so the daily summary makes state visible at a glance.
+  const parts: string[] = [];
+  if (issue.isPr) parts.push("[PR]");
+  if (issue.state === "closed") parts.push("[closed]");
+  const baseTitle = issue.title ?? `#${issue.number ?? "?"}`;
+  const title = parts.length > 0 ? `${parts.join(" ")} ${baseTitle}` : baseTitle;
+
+  const summary = issue.body ? firstParagraph(issue.body) : null;
+
+  return {
+    id,
+    title,
+    url: normalizedUrl,
+    publishedAt: new Date(updatedTs).toISOString(),
+    ...(summary !== null && { summary }),
+    ...(issue.body !== null && { content: issue.body }),
+    categories: source.categories,
+    sourceSlug: source.slug,
+  };
+}
+
+export function updateIssuesCursor(current: Record<string, string>, issues: readonly ParsedIssue[], params: IssuesParams): Record<string, string> {
+  let newest: number | null = null;
+  for (const issue of issues) {
+    if (issue.isPr && !params.includePrs) continue;
+    if (!issue.updatedAt) continue;
+    const ts = Date.parse(issue.updatedAt);
+    if (!Number.isFinite(ts)) continue;
+    if (newest === null || ts > newest) newest = ts;
+  }
+  if (newest === null) return current;
+  const currentTs = current[ISSUES_CURSOR_KEY] ? Date.parse(current[ISSUES_CURSOR_KEY]) : -Infinity;
+  if (newest <= currentTs) return current;
+  return {
+    ...current,
+    [ISSUES_CURSOR_KEY]: new Date(newest).toISOString(),
+  };
+}
+
+// Pure: run parse + filter + cursor-advance on an already-fetched
+// body, so tests can exercise the normalizer path without HTTP.
+export function processIssuesResponse(rawBody: unknown, source: Source, params: IssuesParams, cursor: Record<string, string>): FetchResult {
+  if (!Array.isArray(rawBody)) return { items: [], cursor };
+  const parsed: ParsedIssue[] = [];
+  for (const raw of rawBody) {
+    const issue = parseGithubIssue(raw);
+    if (issue) parsed.push(issue);
+  }
+  const lastSeenTs = cursor[ISSUES_CURSOR_KEY] ? Date.parse(cursor[ISSUES_CURSOR_KEY]) : null;
+  const effectiveLastSeen = lastSeenTs !== null && Number.isFinite(lastSeenTs) ? lastSeenTs : null;
+
+  const items: SourceItem[] = [];
+  for (const issue of parsed) {
+    if (items.length >= source.maxItemsPerFetch) break;
+    const item = issueToSourceItem(issue, source, params, effectiveLastSeen);
+    if (item) items.push(item);
+  }
+  return { items, cursor: updateIssuesCursor(cursor, parsed, params) };
+}
+
+// Build the GitHub issues URL. `since` and `per_page` are set
+// for freshness + a reasonable upper bound (the API caps at 100).
+// `sort=updated&direction=desc` pairs with the cursor so newest
+// items arrive first.
+export function issuesUrl(owner: string, repo: string, state: string, since: string | null, perPage: number): string {
+  const params = new URLSearchParams();
+  params.set("state", state);
+  params.set("sort", "updated");
+  params.set("direction", "desc");
+  // GitHub API accepts max 100 per page. Clamp defensively.
+  const clamped = Math.max(1, Math.min(100, Math.floor(perPage)));
+  params.set("per_page", String(clamped));
+  if (since) params.set("since", since);
+  return `${GITHUB_API_BASE}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/issues?${params.toString()}`;
+}
+
+export const githubIssuesFetcher: SourceFetcher = {
+  kind: "github-issues",
+  async fetch(source: Source, state: SourceState, deps: FetcherDeps): Promise<FetchResult> {
+    const repoRaw = source.fetcherParams["github_repo"];
+    const slug = parseRepoSlug(repoRaw ?? "");
+    if (!slug) {
+      throw new GithubFetcherError(source.url, 0, `github_repo param is required and must be owner/repo, got ${JSON.stringify(repoRaw)}`);
+    }
+    const params = resolveIssuesParams(source.fetcherParams);
+    const since = state.cursor[ISSUES_CURSOR_KEY] ?? null;
+    const url = issuesUrl(slug.owner, slug.repo, params.state, since, source.maxItemsPerFetch);
+    const body = await githubFetchJson(url, deps.http);
+    return processIssuesResponse(body, source, params, state.cursor);
+  },
+};
+
+registerFetcher(githubIssuesFetcher);

package/server/workspace/sources/fetchers/githubReleases.ts

@@ -0,0 +1,186 @@
+// GitHub Releases fetcher.
+//
+// Source config shape:
+//
+//   fetcher_kind: github-releases
+//   github_repo: anthropics/claude-code
+//
+// Flow: GET /repos/:owner/:repo/releases → JSON array → parse each
+// release → filter against cursor (published_at) → normalize to
+// SourceItem.
+//
+// Cursor key: `github_releases_last_published_at` — ISO timestamp
+// of the newest release we've emitted. Separate key from the RSS
+// cursor so a source transitioning between fetcher kinds doesn't
+// mishandle state.
+//
+// Unauthenticated only in phase 1. The 60 req/hour/IP rate-limit
+// is plenty for a workspace with a handful of repos.
+
+import { normalizeUrl, stableItemId } from "../urls.js";
+import type { Source, SourceItem, SourceState } from "../types.js";
+import type { FetcherDeps, FetchResult, SourceFetcher } from "./index.js";
+import { registerFetcher } from "./index.js";
+import { GITHUB_API_BASE, GithubFetcherError, githubFetchJson, isRecord, parseRepoSlug } from "./github.js";
+
+export const RELEASES_CURSOR_KEY = "github_releases_last_published_at";
+
+// GitHub Releases endpoint. 30 releases per page by default; we
+// cap at `source.maxItemsPerFetch` downstream. Phase-1 doesn't
+// paginate — one page covers every active project's last ~1-2
+// years of releases, plenty for the cursor to advance on.
+function releasesUrl(owner: string, repo: string): string {
+  return `${GITHUB_API_BASE}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/releases`;
+}
+
+// One parsed release. Mirrors the GitHub API shape we actually
+// read (we drop the other ~20 fields for clarity and to keep the
+// normalizer testable in isolation).
+interface ParsedRelease {
+  id: number | null;
+  name: string | null;
+  tagName: string | null;
+  htmlUrl: string | null;
+  body: string | null;
+  publishedAt: string | null;
+  draft: boolean;
+  prerelease: boolean;
+}
+
+// Narrow one GitHub release record into ParsedRelease. Pure —
+// exported so tests can exercise the JSON-shape handling without
+// hitting the network.
+export function parseGithubRelease(raw: unknown): ParsedRelease | null {
+  if (!isRecord(raw)) return null;
+  const id = typeof raw.id === "number" && Number.isFinite(raw.id) ? raw.id : null;
+  const name = typeof raw.name === "string" ? raw.name : null;
+  const tagName = typeof raw.tag_name === "string" ? raw.tag_name : null;
+  const htmlUrl = typeof raw.html_url === "string" ? raw.html_url : null;
+  const body = typeof raw.body === "string" ? raw.body : null;
+  const publishedAt = typeof raw.published_at === "string" ? raw.published_at : null;
+  const draft = raw.draft === true;
+  const prerelease = raw.prerelease === true;
+  return { id, name, tagName, htmlUrl, body, publishedAt, draft, prerelease };
+}
+
+// Build a SourceItem from a parsed release + the parent Source.
+// Returns null when the release doesn't carry the fields we need
+// to make a useful item (missing URL, or cursor says we've seen
+// this release already).
+export function releaseToSourceItem(release: ParsedRelease, source: Source, lastSeenTs: number | null): SourceItem | null {
+  // Drafts are private — GitHub only shows them to authed readers.
+  // But defensively skip if the API somehow returns one.
+  if (release.draft) return null;
+  if (!release.htmlUrl || !release.publishedAt) return null;
+
+  // Cursor filter: drop releases at-or-older than the cursor.
+  // Null cursor means first run → pass through.
+  const publishedTs = Date.parse(release.publishedAt);
+  if (Number.isFinite(publishedTs) && lastSeenTs !== null) {
+    if (publishedTs <= lastSeenTs) return null;
+  }
+
+  const normalizedUrl = normalizeUrl(release.htmlUrl);
+  if (!normalizedUrl) return null;
+  const id = stableItemId(normalizedUrl);
+
+  // Title resolution: prefer <name> (release display name), fall
+  // back to <tag_name> (e.g. "v1.2.3"). Annotate pre-releases so
+  // the daily summary can visually distinguish them.
+  const baseTitle = release.name ?? release.tagName ?? "Release";
+  const title = release.prerelease ? `[pre] ${baseTitle}` : baseTitle;
+  const summary = release.body ? firstParagraph(release.body) : null;
+
+  return {
+    id,
+    title,
+    url: normalizedUrl,
+    publishedAt: new Date(publishedTs).toISOString(),
+    ...(summary !== null && { summary }),
+    ...(release.body !== null && { content: release.body }),
+    categories: source.categories,
+    sourceSlug: source.slug,
+  };
+}
+
+// Extract the first "paragraph" of a release body for the short
+// summary. GitHub release bodies are Markdown — we take everything
+// up to the first double-newline so multi-line markdown lists or
+// images in paragraph 2+ don't bloat the summary.
+//
+// Pure; exported for tests.
+export function firstParagraph(body: string): string | null {
+  const trimmed = body.trim();
+  if (!trimmed) return null;
+  const doubleNewline = trimmed.indexOf("\n\n");
+  const head = doubleNewline === -1 ? trimmed : trimmed.slice(0, doubleNewline);
+  return head.length > 0 ? head : null;
+}
+
+// After filtering, advance the cursor to the newest publishedAt
+// across ALL parsed releases in the response — not just the
+// emitted ones — so a quiet repo doesn't keep replaying its last
+// release on every run.
+//
+// Exported pure for direct unit testing.
+export function updateReleasesCursor(current: Record<string, string>, releases: readonly ParsedRelease[]): Record<string, string> {
+  let newest: number | null = null;
+  for (const release of releases) {
+    if (release.draft) continue;
+    if (!release.publishedAt) continue;
+    const ts = Date.parse(release.publishedAt);
+    if (!Number.isFinite(ts)) continue;
+    if (newest === null || ts > newest) newest = ts;
+  }
+  if (newest === null) return current;
+  const currentTs = current[RELEASES_CURSOR_KEY] ? Date.parse(current[RELEASES_CURSOR_KEY]) : -Infinity;
+  if (newest <= currentTs) return current;
+  return {
+    ...current,
+    [RELEASES_CURSOR_KEY]: new Date(newest).toISOString(),
+  };
+}
+
+// Pure: run the parse + filter + cursor-advance pipeline on an
+// already-fetched JSON body. Exposed separately from the fetch
+// itself so we can test the full normalization path with
+// fabricated API responses and no HTTP stubbing.
+export function processReleasesResponse(rawBody: unknown, source: Source, cursor: Record<string, string>): FetchResult {
+  if (!Array.isArray(rawBody)) {
+    return { items: [], cursor };
+  }
+  const parsed: ParsedRelease[] = [];
+  for (const raw of rawBody) {
+    const release = parseGithubRelease(raw);
+    if (release) parsed.push(release);
+  }
+  const lastSeenTs = cursor[RELEASES_CURSOR_KEY] ? Date.parse(cursor[RELEASES_CURSOR_KEY]) : null;
+  const effectiveLastSeen = lastSeenTs !== null && Number.isFinite(lastSeenTs) ? lastSeenTs : null;
+
+  const items: SourceItem[] = [];
+  for (const release of parsed) {
+    if (items.length >= source.maxItemsPerFetch) break;
+    const item = releaseToSourceItem(release, source, effectiveLastSeen);
+    if (item) items.push(item);
+  }
+  return {
+    items,
+    cursor: updateReleasesCursor(cursor, parsed),
+  };
+}
+
+export const githubReleasesFetcher: SourceFetcher = {
+  kind: "github-releases",
+  async fetch(source: Source, state: SourceState, deps: FetcherDeps): Promise<FetchResult> {
+    const repoRaw = source.fetcherParams["github_repo"];
+    const slug = parseRepoSlug(repoRaw ?? "");
+    if (!slug) {
+      throw new GithubFetcherError(source.url, 0, `github_repo param is required and must be owner/repo, got ${JSON.stringify(repoRaw)}`);
+    }
+    const url = releasesUrl(slug.owner, slug.repo);
+    const body = await githubFetchJson(url, deps.http);
+    return processReleasesResponse(body, source, state.cursor);
+  },
+};
+
+registerFetcher(githubReleasesFetcher);

package/server/workspace/sources/fetchers/index.ts

@@ -0,0 +1,71 @@
+// Fetcher dispatcher.
+//
+// Each source in the registry has a `fetcherKind` that maps to a
+// module under `server/sources/fetchers/<kind>.ts` implementing
+// the `SourceFetcher` interface. The pipeline looks up the right
+// fetcher via `getFetcher(kind)`, then calls `fetcher.fetch(...)`.
+//
+// Adding a new fetcher kind in phase 2 / 3 / later:
+//   1. Create `server/sources/fetchers/<new-kind>.ts` exporting
+//      a `SourceFetcher` and calling `registerFetcher(...)` at
+//      the bottom so the module self-registers on import.
+//   2. Add the string to `FETCHER_KINDS` in `../types.ts`.
+//   3. **Add a side-effect import for the new module to
+//      `./registerAll.ts`.** Production entry points import that
+//      barrel; without this step the pipeline still resolves
+//      `getFetcher(kind)` to `null` and your fetcher never runs.
+//   4. Add a case to `test/sources/test_fetcherRegistration.ts`
+//      so regressions fail a unit test.
+// No other framework change is required.
+
+import type { HttpFetcherDeps } from "../httpFetcher.js";
+import type { FetcherKind, Source, SourceItem, SourceState } from "../types.js";
+
+// Per-run dependencies threaded into every fetcher so all I/O
+// goes through injectable hooks (tests never touch the network).
+export interface FetcherDeps {
+  // Wiring for `fetchPolite` — robots provider, rate limiter,
+  // fetch impl, timeout. Shared across fetchers in one pipeline
+  // run so their per-host rate limits serialize together.
+  http: HttpFetcherDeps;
+  // Monotonic wall-clock. Fetchers timestamp new items and update
+  // the cursor with it.
+  now: () => number;
+  // Pipeline-wide abort (e.g. server shutdown). Separate from
+  // the per-fetch timeout that lives inside `http`.
+  signal?: AbortSignal;
+}
+
+export interface FetchResult {
+  // Newly-discovered items (already filtered against the cursor).
+  // Empty array is a valid outcome — "no new items since last run".
+  items: SourceItem[];
+  // Replacement cursor for SourceState. Fetchers return only the
+  // keys they own; the caller merges this into the existing state.
+  cursor: Record<string, string>;
+}
+
+export interface SourceFetcher {
+  readonly kind: FetcherKind;
+  fetch(source: Source, state: SourceState, deps: FetcherDeps): Promise<FetchResult>;
+}
+
+// Registry of all known fetchers. Populated lazily via
+// `registerFetcher` so each fetcher module is responsible for
+// adding itself at import time — keeps the dispatcher free of
+// hard dependencies on modules that may pull heavy deps
+// (fast-xml-parser etc).
+const FETCHERS = new Map<FetcherKind, SourceFetcher>();
+
+export function registerFetcher(fetcher: SourceFetcher): void {
+  FETCHERS.set(fetcher.kind, fetcher);
+}
+
+export function getFetcher(kind: FetcherKind): SourceFetcher | null {
+  return FETCHERS.get(kind) ?? null;
+}
+
+// Test-only: clear the registry between cases.
+export function __resetFetchersForTests(): void {
+  FETCHERS.clear();
+}

package/server/workspace/sources/fetchers/registerAll.ts

@@ -0,0 +1,15 @@
+// Side-effect bootstrap: importing this module registers every
+// known fetcher with the dispatcher in `./index.ts`. Each fetcher
+// module calls `registerFetcher(...)` at import time.
+//
+// The dispatcher itself intentionally does not import the fetcher
+// modules (see the comment in `./index.ts`) so it stays free of
+// heavy parser dependencies and tests can register only the
+// fetchers they need. Production entry points that run the
+// pipeline must import this barrel once so `getFetcher(kind)`
+// returns a non-null result for every FetcherKind.
+
+import "./rss.js";
+import "./githubReleases.js";
+import "./githubIssues.js";
+import "./arxiv.js";

package/server/workspace/sources/fetchers/rss.ts

@@ -0,0 +1,141 @@
+// RSS / Atom source fetcher.
+//
+// Flow:
+//   1. fetchPolite(source.url) — respects robots, User-Agent,
+//      rate limit, timeout
+//   2. parseFeed(bodyText) — pure XML → ParsedFeed
+//   3. normalizeToSourceItems(...) — ParsedFeedItem[] → SourceItem[]
+//      with cursor filtering so we only emit items newer than the
+//      last-seen pubDate
+//   4. updateCursor(...) — advance the cursor to the most-recent
+//      publishedAt across ALL items in this response (not just
+//      the emitted ones) so a quiet feed doesn't keep replaying
+//      old items after a one-shot republish
+//
+// The parser / normalizer / cursor logic are pure functions
+// exported for direct unit tests. The `rssFetcher` object is the
+// Promise-aware orchestrator that stitches them together.
+
+import { fetchPolite } from "../httpFetcher.js";
+import { normalizeUrl, stableItemId } from "../urls.js";
+import type { Source, SourceItem, SourceState } from "../types.js";
+import type { FetcherDeps, FetchResult, SourceFetcher } from "./index.js";
+import { registerFetcher } from "./index.js";
+import { parseFeed, type ParsedFeed, type ParsedFeedItem } from "./rssParser.js";
+
+// Cursor key we store in SourceState.cursor for RSS feeds.
+// ISO timestamp of the most-recent item's publishedAt we've seen.
+// Items whose publishedAt is <= this value are skipped on the
+// next run. Separate key name from other fetchers so adding
+// GitHub / arXiv cursors next to RSS ones on the same source
+// never conflicts.
+export const RSS_CURSOR_KEY = "rss_last_seen_at";
+
+export class RssFetcherError extends Error {
+  readonly url: string;
+  readonly status: number | null;
+  constructor(url: string, status: number | null, message: string) {
+    super(message);
+    this.name = "RssFetcherError";
+    this.url = url;
+    this.status = status;
+  }
+}
+
+// Filter raw parsed items against the cursor and normalize into
+// the pipeline's `SourceItem` shape. Pure — exported so tests
+// can exercise cursor semantics with fabricated ParsedFeed
+// structures without spinning up HTTP.
+export function normalizeToSourceItems(feed: ParsedFeed, source: Source, cursor: Record<string, string>, maxItems: number): SourceItem[] {
+  const lastSeen = cursor[RSS_CURSOR_KEY] ?? null;
+  const lastSeenTs = lastSeen ? Date.parse(lastSeen) : null;
+  const items: SourceItem[] = [];
+
+  for (const entry of feed.items) {
+    if (items.length >= maxItems) break;
+    const item = entryToSourceItem(entry, source, lastSeenTs);
+    if (item) items.push(item);
+  }
+  return items;
+}
+
+function entryToSourceItem(entry: ParsedFeedItem, source: Source, lastSeenTs: number | null): SourceItem | null {
+  if (!entry.link) return null;
+  const normalizedUrl = normalizeUrl(entry.link);
+  if (!normalizedUrl) return null;
+  // Cursor comparison: drop items at or older than the last-seen
+  // timestamp. Null publishedAt → keep (rare but happens with
+  // misformatted feeds; we'd rather emit a dup once than lose
+  // an item forever).
+  if (entry.publishedAt && lastSeenTs !== null) {
+    const itemTs = Date.parse(entry.publishedAt);
+    if (Number.isFinite(itemTs) && itemTs <= lastSeenTs) return null;
+  }
+  // Use the feed's own id as a hint, but always derive the
+  // SourceItem.id from the normalized URL so cross-source dedup
+  // (see #188 Q3) lines up regardless of feed conventions.
+  const id = stableItemId(normalizedUrl);
+  const publishedAt =
+    entry.publishedAt ??
+    // Synthesize a fetch-time timestamp when the feed didn't
+    // provide one, so downstream sorting has a monotonic key.
+    new Date().toISOString();
+
+  // Build the SourceItem with conditional spreads so we don't
+  // carry `undefined` fields that break exactOptionalPropertyTypes
+  // on the server tsconfig.
+  return {
+    id,
+    title: entry.title,
+    url: normalizedUrl,
+    publishedAt,
+    ...(entry.summary !== null && { summary: entry.summary }),
+    ...(entry.content !== null && { content: entry.content }),
+    categories: source.categories,
+    sourceSlug: source.slug,
+  };
+}
+
+// After filtering, advance the cursor to the newest publishedAt
+// in the full ParsedFeed (not just the emitted items). Doing
+// this on the full set prevents a feed that republishes older
+// items without updating pubDate from causing us to re-emit
+// them forever.
+//
+// Exported pure so tests can pin the advancement policy down.
+export function updateCursor(current: Record<string, string>, feed: ParsedFeed): Record<string, string> {
+  let newest: number | null = null;
+  for (const entry of feed.items) {
+    if (!entry.publishedAt) continue;
+    const ts = Date.parse(entry.publishedAt);
+    if (!Number.isFinite(ts)) continue;
+    if (newest === null || ts > newest) newest = ts;
+  }
+  if (newest === null) return current;
+  // Only advance forwards. A feed whose newest item is older
+  // than our cursor should leave the cursor where it was so
+  // we don't retroactively re-emit everything on the next run.
+  const currentTs = current[RSS_CURSOR_KEY] ? Date.parse(current[RSS_CURSOR_KEY]) : -Infinity;
+  if (newest <= currentTs) return current;
+  return { ...current, [RSS_CURSOR_KEY]: new Date(newest).toISOString() };
+}
+
+export const rssFetcher: SourceFetcher = {
+  kind: "rss",
+  async fetch(source: Source, state: SourceState, deps: FetcherDeps): Promise<FetchResult> {
+    const res = await fetchPolite(source.url, deps.http);
+    if (!res.ok) {
+      throw new RssFetcherError(source.url, res.status, `RSS fetch ${source.url} failed with HTTP ${res.status}`);
+    }
+    const body = await res.text();
+    const feed = parseFeed(body);
+    if (!feed) {
+      throw new RssFetcherError(source.url, res.status, `RSS body at ${source.url} did not parse as RSS / Atom / RDF`);
+    }
+    const items = normalizeToSourceItems(feed, source, state.cursor, source.maxItemsPerFetch);
+    const cursor = updateCursor(state.cursor, feed);
+    return { items, cursor };
+  },
+};
+
+registerFetcher(rssFetcher);