Skip to content

World's first open-source enterprise world model.

Scope RSS hydration summaries to each source (#462)

Daniel90f7c15298ad
diff --git a/crates/utopia-store/src/sources.rs b/crates/utopia-store/src/sources.rs
index ab2c087c..de9a319e 100644
--- a/crates/utopia-store/src/sources.rs
+++ b/crates/utopia-store/src/sources.rs
@@ -84,37 +84,50 @@ pub async fn list(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<SourceView>> {
// config 剔掉凭据:列表给 Viewer 看,哪一种连接器的密钥都不下发。
// 键在 `SOURCE_SECRET_KEYS` 一张表上——从前这里只减 `auth_header`,五种连接器
// 的密钥就这么漏出去的(#246)
+ // 外层别名不能与 ENTRY_SELECT 的来源别名重名;来源和当前代谓词必须留在投影内部,
+ // 否则 PostgreSQL 会先计算部署中的全部 observation,再丢弃与当前来源无关的行。
let rows: Vec<SourceView> = sqlx::query_as(
- &format!("WITH projected AS ({}) SELECT s.id, s.kind, s.name, s.config - $2::text[] AS config, s.icon,
- s.sync_interval_minutes, s.sync_cron,
- s.last_sync_at, s.last_sync_status, s.last_sync_error, s.last_sync_added,
+ &format!("SELECT listed_source.id, listed_source.kind, listed_source.name,
+ listed_source.config - $2::text[] AS config, listed_source.icon,
+ listed_source.sync_interval_minutes, listed_source.sync_cron,
+ listed_source.last_sync_at, listed_source.last_sync_status,
+ listed_source.last_sync_error, listed_source.last_sync_added,
(SELECT count(*) FROM documents d
- WHERE d.source_id = s.id AND d.deleted_at IS NULL) AS doc_count,
+ WHERE d.source_id = listed_source.id AND d.deleted_at IS NULL) AS doc_count,
(SELECT count(*) FROM documents d
- WHERE d.source_id = s.id AND d.missing_since IS NOT NULL
+ WHERE d.source_id = listed_source.id AND d.missing_since IS NOT NULL
AND d.deleted_at IS NULL) AS missing_count,
- CASE WHEN s.kind <> 'rss' THEN NULL
- WHEN s.config->>'content_mode' IS DISTINCT FROM 'full_new_items' THEN 'disabled'
- WHEN s.rss_baselined_at IS NULL THEN 'pending' ELSE 'active' END AS rss_full_content_state,
- CASE WHEN s.kind='rss' THEN s.rss_generation END AS rss_full_content_generation,
- (SELECT count(*)::int FROM projected e
- WHERE e.source_id=s.id AND e.activation_generation=s.rss_generation AND e.state='baseline') AS rss_full_content_baseline_count,
- COALESCE((SELECT count(*) FROM projected e
- WHERE e.source_id = s.id AND e.activation_generation = s.rss_generation
- AND e.state = 'pending'), 0) AS rss_full_content_pending_count,
- COALESCE((SELECT count(*) FROM projected e
- WHERE e.source_id = s.id AND e.activation_generation = s.rss_generation
- AND e.state IN ('queued', 'hydrating')), 0) AS rss_full_content_queued_count,
- COALESCE((SELECT count(*) FROM projected e
- WHERE e.source_id = s.id AND e.activation_generation = s.rss_generation
- AND e.state = 'retry_wait'), 0) AS rss_full_content_retrying_count,
- COALESCE((SELECT count(*) FROM projected e
- WHERE e.source_id = s.id AND e.activation_generation = s.rss_generation
- AND e.state = 'complete'), 0) AS rss_full_content_complete_count,
- COALESCE((SELECT count(*) FROM projected e
- WHERE e.source_id = s.id AND e.activation_generation = s.rss_generation
- AND e.state IN ('terminal','deleted','superseded')), 0) AS rss_full_content_terminal_count
- FROM sources s WHERE s.kb_id = $1 ORDER BY s.created_at", crate::rss_full_content::ENTRY_SELECT),
+ CASE WHEN listed_source.kind <> 'rss' THEN NULL
+ WHEN listed_source.config->>'content_mode' IS DISTINCT FROM 'full_new_items' THEN 'disabled'
+ WHEN listed_source.rss_baselined_at IS NULL THEN 'pending' ELSE 'active' END AS rss_full_content_state,
+ CASE WHEN listed_source.kind='rss' THEN listed_source.rss_generation END AS rss_full_content_generation,
+ COALESCE(hydration.baseline_count, 0) AS rss_full_content_baseline_count,
+ COALESCE(hydration.pending, 0) AS rss_full_content_pending_count,
+ COALESCE(hydration.queued, 0) AS rss_full_content_queued_count,
+ COALESCE(hydration.retrying, 0) AS rss_full_content_retrying_count,
+ COALESCE(hydration.complete, 0) AS rss_full_content_complete_count,
+ COALESCE(hydration.terminal, 0) AS rss_full_content_terminal_count
+ FROM sources listed_source
+ LEFT JOIN LATERAL (
+ SELECT
+ (count(*) FILTER (WHERE projected.state = 'baseline'))::int AS baseline_count,
+ count(*) FILTER (WHERE projected.state = 'pending') AS pending,
+ count(*) FILTER (WHERE projected.state IN ('queued', 'hydrating')) AS queued,
+ count(*) FILTER (WHERE projected.state = 'retry_wait') AS retrying,
+ count(*) FILTER (WHERE projected.state = 'complete') AS complete,
+ count(*) FILTER (
+ WHERE projected.state IN ('terminal', 'deleted', 'superseded')
+ ) AS terminal
+ FROM (
+ {}
+ WHERE listed_source.kind = 'rss'
+ AND e.source_id = listed_source.id
+ AND e.activation_generation = listed_source.rss_generation
+ ) projected
+ ) hydration ON listed_source.kind = 'rss'
+ WHERE listed_source.kb_id = $1 ORDER BY listed_source.created_at",
+ crate::rss_full_content::ENTRY_SELECT
+ ),
)
.bind(kb_id)
.bind(SOURCE_SECRET_KEYS)
diff --git a/crates/utopia-store/tests/rss_full_content.rs b/crates/utopia-store/tests/rss_full_content.rs
index e3829825..e2c21447 100644
--- a/crates/utopia-store/tests/rss_full_content.rs
+++ b/crates/utopia-store/tests/rss_full_content.rs
@@ -296,6 +296,321 @@ async fn seed_source(pool: &PgPool) -> anyhow::Result<(Uuid, Uuid, Uuid, Uuid)>
Ok((org_id, kb_id, source_id, workspace_id))
}
+async fn insert_source(
+ pool: &PgPool,
+ kb_id: Uuid,
+ kind: &str,
+ name: &str,
+ config: serde_json::Value,
+) -> anyhow::Result<Uuid> {
+ let id = Uuid::now_v7();
+ sqlx::query(
+ "INSERT INTO sources (id, kb_id, kind, name, config)
+ VALUES ($1, $2, $3, $4, $5)",
+ )
+ .bind(id)
+ .bind(kb_id)
+ .bind(kind)
+ .bind(name)
+ .bind(config)
+ .execute(pool)
+ .await?;
+ Ok(id)
+}
+
+async fn job_id_for(pool: &PgPool, source_id: Uuid, external_key: &str) -> anyhow::Result<i64> {
+ let job_id: Option<i64> = sqlx::query_scalar(
+ "SELECT e.current_job_id
+ FROM rss_full_content_entries e
+ WHERE e.source_id = $1 AND e.external_key = $2",
+ )
+ .bind(source_id)
+ .bind(external_key)
+ .fetch_one(pool)
+ .await?;
+ job_id.ok_or_else(|| anyhow::anyhow!("expected a hydration job for {external_key}"))
+}
+
+#[tokio::test]
+async fn source_list_exposes_scoped_rss_summary() -> anyhow::Result<()> {
+ let Some(url) = utopia_store::test_db::url() else {
+ return Ok(());
+ };
+ let pool = PgPool::connect(&url).await?;
+ let (org_id, kb_id, source_id, _) = seed_source(&pool).await?;
+ let folder_id =
+ insert_source(&pool, kb_id, "folder", "folder-test", serde_json::json!({})).await?;
+ let url_id = insert_source(
+ &pool,
+ kb_id,
+ "url",
+ "url-test",
+ serde_json::json!({"urls":["https://example.com"]}),
+ )
+ .await?;
+ sqlx::query(
+ "UPDATE sources
+ SET created_at = CASE id
+ WHEN $1 THEN '2020-01-01T00:00:00Z'::timestamptz
+ WHEN $2 THEN '2020-01-02T00:00:00Z'::timestamptz
+ WHEN $3 THEN '2020-01-03T00:00:00Z'::timestamptz
+ END
+ WHERE id IN ($1, $2, $3)",
+ )
+ .bind(source_id)
+ .bind(folder_id)
+ .bind(url_id)
+ .execute(&pool)
+ .await?;
+
+ let mut tx = pool.begin().await?;
+ utopia_store::rss_full_content::initialize_source(&mut tx, source_id).await?;
+ tx.commit().await?;
+
+ let listed = utopia_store::sources::list(&pool, kb_id).await?;
+ assert_eq!(
+ listed
+ .iter()
+ .map(|source| source.name.as_str())
+ .collect::<Vec<_>>(),
+ vec!["rss-full-content-test", "folder-test", "url-test"]
+ );
+ for (id, kind) in [(folder_id, "folder"), (url_id, "url")] {
+ let source = listed
+ .iter()
+ .find(|source| source.id == id)
+ .ok_or_else(|| anyhow::anyhow!("{kind} source is missing"))?;
+ assert!(source.rss_full_content_state.is_none());
+ assert!(source.rss_full_content_generation.is_none());
+ assert_eq!(source.rss_full_content_baseline_count, Some(0));
+ assert_eq!(source.rss_full_content_pending_count, 0);
+ assert_eq!(source.rss_full_content_queued_count, 0);
+ assert_eq!(source.rss_full_content_retrying_count, 0);
+ assert_eq!(source.rss_full_content_complete_count, 0);
+ assert_eq!(source.rss_full_content_terminal_count, 0);
+ }
+ let rss = listed
+ .iter()
+ .find(|source| source.id == source_id)
+ .ok_or_else(|| anyhow::anyhow!("RSS source is missing"))?;
+ assert_eq!(rss.rss_full_content_state.as_deref(), Some("pending"));
+ assert_eq!(
+ (
+ rss.rss_full_content_pending_count,
+ rss.rss_full_content_queued_count,
+ rss.rss_full_content_retrying_count,
+ rss.rss_full_content_complete_count,
+ rss.rss_full_content_terminal_count
+ ),
+ (0, 0, 0, 0, 0)
+ );
+
+ utopia_store::rss_full_content::record_baseline(&pool, source_id, 1, &[]).await?;
+ let entries = vec![
+ entry("queued"),
+ entry("hydrating"),
+ entry("retrying"),
+ entry("complete"),
+ entry("superseded"),
+ entry("deleted"),
+ {
+ let mut value = entry("terminal");
+ value.has_usable_source = false;
+ value
+ },
+ ];
+ utopia_store::rss_full_content::discover(&pool, source_id, 1, &entries).await?;
+ assert_eq!(
+ utopia_store::rss_full_content::claim_pending_and_enqueue(&pool, source_id, 1, 6, 5)
+ .await?,
+ 6
+ );
+ utopia_store::rss_full_content::discover(&pool, source_id, 1, &[entry("pending")]).await?;
+ let hydrating_job = job_id_for(&pool, source_id, "hydrating").await?;
+ sqlx::query("UPDATE jobs SET status = 'running' WHERE id = $1")
+ .bind(hydrating_job)
+ .execute(&pool)
+ .await?;
+ let retrying_job = job_id_for(&pool, source_id, "retrying").await?;
+ sqlx::query("UPDATE jobs SET status = 'queued', attempts = 1 WHERE id = $1")
+ .bind(retrying_job)
+ .execute(&pool)
+ .await?;
+ let superseded_job = job_id_for(&pool, source_id, "superseded").await?;
+ sqlx::query("UPDATE jobs SET status = 'done' WHERE id = $1")
+ .bind(superseded_job)
+ .execute(&pool)
+ .await?;
+
+ utopia_store::documents::create_with_version_and_processing(
+ &pool,
+ kb_id,
+ "complete.md",
+ "text/markdown",
+ 10,
+ "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+ Some(source_id),
+ None,
+ Some("complete"),
+ )
+ .await?;
+ let deleted = utopia_store::documents::create_with_version_and_processing(
+ &pool,
+ kb_id,
+ "deleted.md",
+ "text/markdown",
+ 10,
+ "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+ Some(source_id),
+ None,
+ Some("deleted"),
+ )
+ .await?;
+ utopia_store::documents::delete(&pool, kb_id, deleted.id, None).await?;
+ utopia_store::documents::purge(&pool, kb_id, deleted.id).await?;
+
+ let listed = utopia_store::sources::list(&pool, kb_id).await?;
+ let rss = listed
+ .iter()
+ .find(|source| source.id == source_id)
+ .ok_or_else(|| anyhow::anyhow!("RSS source is missing after discovery"))?;
+ assert_eq!(rss.rss_full_content_state.as_deref(), Some("active"));
+ assert_eq!(rss.rss_full_content_pending_count, 1);
+ assert_eq!(
+ rss.rss_full_content_queued_count, 2,
+ "queued and hydrating share one bucket"
+ );
+ assert_eq!(rss.rss_full_content_retrying_count, 1);
+ assert_eq!(rss.rss_full_content_complete_count, 1);
+ assert_eq!(
+ rss.rss_full_content_terminal_count, 3,
+ "terminal, deleted and superseded share one bucket"
+ );
+ assert_eq!(
+ rss.doc_count, 1,
+ "purged documents stay out of the live count"
+ );
+ assert_eq!(rss.missing_count, 0);
+
+ let mut tx = pool.begin().await?;
+ utopia_store::rss_full_content::enable_source(&mut tx, source_id).await?;
+ tx.commit().await?;
+ utopia_store::rss_full_content::record_baseline(&pool, source_id, 2, &[]).await?;
+ utopia_store::rss_full_content::discover(&pool, source_id, 2, &[entry("new-generation")])
+ .await?;
+ let listed = utopia_store::sources::list(&pool, kb_id).await?;
+ let rss = listed
+ .iter()
+ .find(|source| source.id == source_id)
+ .ok_or_else(|| anyhow::anyhow!("RSS source is missing after generation change"))?;
+ assert_eq!(rss.rss_full_content_state.as_deref(), Some("active"));
+ assert_eq!(
+ rss.rss_full_content_pending_count, 1,
+ "old-generation observations are excluded"
+ );
+ assert_eq!(rss.rss_full_content_terminal_count, 0);
+
+ sqlx::query(
+ "UPDATE sources
+ SET config = jsonb_set(config, '{content_mode}', '\"feed\"')
+ WHERE id = $1",
+ )
+ .bind(source_id)
+ .execute(&pool)
+ .await?;
+ let listed = utopia_store::sources::list(&pool, kb_id).await?;
+ let rss = listed
+ .iter()
+ .find(|source| source.id == source_id)
+ .ok_or_else(|| anyhow::anyhow!("RSS source is missing after disabling"))?;
+ assert_eq!(rss.rss_full_content_state.as_deref(), Some("disabled"));
+ assert_eq!(
+ rss.rss_full_content_terminal_count, 1,
+ "disabled current rows are superseded"
+ );
+
+ cleanup(&pool, org_id).await?;
+ Ok(())
+}
+
+/// The lateral aggregate must count only the listed source's own observations.
+///
+/// One RSS source per base is exactly the fixture that cannot catch the outer alias
+/// binding back to the inner `sources s`: the source filter turns trivially true and
+/// every source's entries are counted, yet a single source still reports its own
+/// number. So: two RSS sources in one base and a third in another, each with a
+/// different count, so a leak between any two of them shows up as a wrong number.
+#[tokio::test]
+async fn source_list_counts_only_the_listed_source() -> anyhow::Result<()> {
+ let Some(url) = utopia_store::test_db::url() else {
+ return Ok(());
+ };
+ let pool = PgPool::connect(&url).await?;
+ let (org_id, kb_id, first_id, workspace_id) = seed_source(&pool).await?;
+ let rss_config = serde_json::json!({
+ "feed_url": "https://example.com/feed",
+ "content_mode": "full_new_items"
+ });
+ let second_id = insert_source(&pool, kb_id, "rss", "rss-second", rss_config.clone()).await?;
+ let other_kb_id = Uuid::now_v7();
+ sqlx::query("INSERT INTO knowledge_bases (id, workspace_id, name) VALUES ($1, $2, $3)")
+ .bind(other_kb_id)
+ .bind(workspace_id)
+ .bind("rss-full-content-other-base")
+ .execute(&pool)
+ .await?;
+ let other_id = insert_source(&pool, other_kb_id, "rss", "rss-other-base", rss_config).await?;
+
+ for (source_id, keys) in [
+ (first_id, vec!["first-1"]),
+ (second_id, vec!["second-1", "second-2"]),
+ (other_id, vec!["other-1", "other-2", "other-3"]),
+ ] {
+ let mut tx = pool.begin().await?;
+ utopia_store::rss_full_content::initialize_source(&mut tx, source_id).await?;
+ tx.commit().await?;
+ utopia_store::rss_full_content::record_baseline(&pool, source_id, 1, &[]).await?;
+ let entries: Vec<_> = keys.into_iter().map(entry).collect();
+ utopia_store::rss_full_content::discover(&pool, source_id, 1, &entries).await?;
+ }
+
+ fn pending_of(listed: &[utopia_core::models::SourceView], id: Uuid) -> anyhow::Result<i64> {
+ listed
+ .iter()
+ .find(|source| source.id == id)
+ .map(|source| source.rss_full_content_pending_count)
+ .ok_or_else(|| anyhow::anyhow!("source {id} is missing from its base's list"))
+ }
+
+ let listed = utopia_store::sources::list(&pool, kb_id).await?;
+ assert_eq!(listed.len(), 2, "the first base lists its own two sources");
+ assert_eq!(
+ pending_of(&listed, first_id)?,
+ 1,
+ "the first source counts only its own observation"
+ );
+ assert_eq!(
+ pending_of(&listed, second_id)?,
+ 2,
+ "a second source in the same base does not inherit the first's rows"
+ );
+ for source in &listed {
+ assert_eq!(source.rss_full_content_complete_count, 0);
+ assert_eq!(source.rss_full_content_terminal_count, 0);
+ }
+
+ let listed = utopia_store::sources::list(&pool, other_kb_id).await?;
+ assert_eq!(listed.len(), 1, "the other base lists only its own source");
+ assert_eq!(
+ pending_of(&listed, other_id)?,
+ 3,
+ "a source in another base sees none of the first base's rows"
+ );
+
+ cleanup(&pool, org_id).await?;
+ Ok(())
+}
+
fn entry(key: impl Into<String>) -> utopia_store::rss_full_content::NewEntry {
utopia_store::rss_full_content::NewEntry {
external_key: key.into(),
diff --git a/docs/decisions/0033-rss-source-summaries-are-source-scoped.md b/docs/decisions/0033-rss-source-summaries-are-source-scoped.md
new file mode 100644
index 00000000..7cdff3be
--- /dev/null
+++ b/docs/decisions/0033-rss-source-summaries-are-source-scoped.md
@@ -0,0 +1,74 @@
+# 0033 · RSS summaries are scoped to the source being listed
+
+- **Status**: query implemented for #417; nested public contract pending
+- **Written**: 2026-09-06 (conventions in the [README](README.md))
+- **Related**: [0023](0023-rss-observations-are-not-documents.md) established RSS observations as a separate responsibility from documents; #417 changes the public `SourceView` contract while fixing the scope of its RSS summary.
+
+> A Library page lists ten sources. The database holds several thousand RSS observations, most belonging to other sources or older activations. The list query should count the rows belonging to each source and its current generation, not project the whole RSS observation table before it starts returning sources.
+
+## What the source list does today
+
+`sources::list` wraps the complete `ENTRY_SELECT` projection in one global CTE and then runs six correlated counts over that projection for every source. `ENTRY_SELECT` is also the canonical place where observation and job state becomes `pending`, `queued`, `hydrating`, `retry_wait`, `complete`, `terminal`, `deleted` or `superseded`.
+
+The CTE is referenced six times. PostgreSQL 12 and later inline a non-recursive, side-effect-free CTE by default only when it is referenced once; this CTE is therefore materialized. Because `ENTRY_SELECT` has no `WHERE`, materialization evaluates its three joins, deletion `EXISTS` and nine-branch state `CASE` for every RSS observation in every knowledge base and generation. The materialized result has no index, so each correlated count scans it in full for each source. The resulting shape is `O(sources × all entries × 6)` rather than `O(sources × own entries)`.
+
+The projection also exposes implementation state — `generation` and `baseline_count` — as part of the public source-list response.
+
+## Decisions
+
+### 1. Aggregate only the source and generation being listed
+
+The source list will use a `LEFT JOIN LATERAL` aggregate per source. The aggregate is parameterized by the outer source's `id` and current `rss_generation`, and its filters are pushed into `rss_full_content_entries` through the implicit btree named `rss_full_content_entries_source_id_activation_generation_ex_key`, which backs `UNIQUE (source_id, activation_generation, external_key)`. The partial `rss_full_content_entries_pending_idx` cannot serve this aggregate. The outer `sources` table must not use the `s` alias because `ENTRY_SELECT` has its own `sources s` join; reusing it would silently bind the source filter to the inner row and count entries from other sources. The `listed_source.kind = 'rss'` predicate appears both inside the lateral subquery and on the join. The join predicate is what excludes non-RSS sources from the lateral result; the inner predicate is retained as a defensive guard. The required execution plan will show how PostgreSQL applies both predicates rather than relying on an assumed one-time short circuit.
+
+The aggregate obtains `pending`, `queued`, `retrying`, `complete` and `terminal` with five `count(*) FILTER` expressions in one pass over the source's own entries. The first implementation cut also computes the existing internal `baseline_count` in that pass so it can preserve the flat API unchanged. It reuses the canonical `ENTRY_SELECT` projection and does not duplicate its state `CASE` in `sources.rs`. `queued` remains the union of `queued` and `hydrating`; `terminal` remains the union of `terminal`, `deleted` and `superseded`. Only rows whose `activation_generation` equals the source's current `rss_generation` are counted.
+
+`baseline` rows are intentionally excluded from all five counts. They represent pre-activation feed stock, not outstanding hydration work. A source containing only baseline observations therefore reports zero for all five work counts even though its observation ledger is not empty; the summary describes hydration work, not ledger cardinality. `baseline_count` remains available only to internal activation state where it is needed.
+
+The query continues to preserve source ordering, document and missing counts, credential removal, the `SOURCE_SECRET_KEYS` bind, and `config - $2::text[]`. Observation, job and document responsibilities remain unchanged, as does `rss_full_content::counts()` and the diagnostic list.
+
+### 2. Make the public summary an explicit nested type
+
+`SourceView` will replace its flat RSS fields with a nullable `rss_full_content` object:
+
+```json
+{
+ "rss_full_content": {
+ "state": "active",
+ "pending": 1,
+ "queued": 2,
+ "retrying": 3,
+ "complete": 4,
+ "terminal": 5
+ }
+}
+```
+
+The Rust API will expose a strongly typed `RssFullContentSummary`, not an arbitrary JSON value. A non-RSS source returns `"rss_full_content": null`. An RSS source always returns an object, including when full-content hydration is disabled. `queued` and `terminal` retain the state unions described above. `generation` and `baseline_count` remain internal state and are removed from the source-list API.
+
+The store will deserialize a private flat `SourceListRow`, then explicitly convert it to `SourceView`. Missing SQL fields or a row that cannot form the required RSS object are storage errors; the conversion will not use `unwrap`, `expect` or silent defaults to hide them.
+
+The TypeScript contract and Library consumer will use the nested object and first check it for null. No compatibility double-write of the old fields is planned. No UI redesign, new component, visual-style change or new copy is part of this decision.
+
+### 3. Do not add schema or runtime dependencies
+
+This change adds no migration and no new Rust or npm dependency. It changes the read query, the API model, the TypeScript contract and their tests only. SQL values continue to use binds; any dynamic SQL is assembled only from repository-owned constants.
+
+### 4. Land the decisions independently
+
+The query optimization and public contract will be implemented in two PRs against this record. The first PR changes only the store query and preserves the existing flat API fields, making the performance change independently measurable and revertible. The second PR replaces those fields with the nested Rust and TypeScript contract and updates the Library consumer. A problem in either change can then be reverted without taking back the other.
+
+## Alternatives rejected
+
+- **Keep the global CTE.** It is simple to reuse, but its work grows with the entire deployment rather than with the source being listed. A larger observation table makes every Library load more expensive.
+- **Run one query per count.** Five round trips and repeated scans add latency and work for the same source summary.
+- **Fetch every entry and count in Rust.** It transfers and retains data that the endpoint only needs as five numbers, making network and memory costs unacceptable.
+- **Add a cache table for the summary.** A cache introduces consistency and invalidation problems. The current read path is sufficient once its scope is source- and generation-bound.
+
+## Performance evidence required by the query implementation
+
+The query implementation PR will include before/after `EXPLAIN (ANALYZE, BUFFERS, VERBOSE)` results from a dedicated PostgreSQL database with one knowledge base, at least one full-content RSS source, several thousand current-generation observations, and observations for other sources or knowledge bases. The comparison will record actual entry scan rows, use of the `source_id`/`activation_generation` index, lateral loops, shared buffer hits/reads, execution time, and whether non-RSS sources avoid scanning entries. Temporary SQL, plans and generated data will stay out of the repository.
+
+## Open questions
+
+- **A transition period for the flat fields.** Not included. The nested object is the public contract approved by this record; a compatibility period would need a separate API decision.
+- **A summary cache.** Deferred until measured source-scoped aggregation is insufficient for a real workload; the invalidation boundary would need to be designed with it.
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index 7794154b..767b1f16 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -56,6 +56,7 @@ The test for writing one: if someone (including us) looks at a piece of code in
| 0030 | [A rule may read what a rule concluded](0030-a-rule-may-read-what-a-rule-concluded.md) | Cuts 1–2 · A rule could not read another rule's conclusion (`attribute_facts()` reads `facts`, subject scope is `entities.type_id`, one pass), so `A → B → C` has to be written as one flattened rule. The answer is the fixed point the axiom side already runs, **inside one call and in memory** — which answers 0013's objection instead of waiving it, since a run stays a pure function of the asserted facts. A derived typing enters as a **premise**, not a filter, so the conclusion narrows to the window the entity was actually a `B`; a rule may read its own conclusions because the derivable space is finite; `fact_derivations` gains `premise_derived_id` and the proof becomes a tree; retirement cascades for free because recompute is total. The page showing which rules feed which is next |
| 0031 | [An event holds at the moment it names](0031-an-event-holds-at-the-moment-it-names.md) | Implemented (#486) · `Validity::under` normalises every write by the predicate's `temporal` (an event is one moment written at both ends, an eternal fact has no dates), `world_axis` and `read_span` read an event as the bucket it names and an undated event at no moment, an eternal fact at every moment · the prompt marks `[event]` / `[eternal]` and says what to write · no schema change, old rows read correctly · the panel's point rendering and the ontology hint are the UI cut |
| 0032 | [A rule computes what it concludes](0032-a-rule-computes-what-it-concludes.md) | Cuts 1–2 · A rule's conclusion was a **constant** (`attribute_rules.conclude_value` is a JSONB literal), so a criterion about a number nobody wrote down — net pay, a margin, a ratio — gets computed elsewhere and typed back in as an assertion, losing the readings it stood on. An operand on either side becomes an expression tree over attributes: its premises are the readings it touched and its interval is their intersection, so retirement needs no new machinery. **Picked, not typed** — not because a parsed string would break the display (it would not; that reason is wrong and recorded as wrong) but because a picker cannot compose an expression over a predicate that does not exist, and because a text box grows a grammar on request. A value may be reached **across a relation** (a path has definite premises and an interval; a to-many path is just a cartesian product the evaluator already walks), while **aggregation is refused**: a `sum` asserts *these are all the readings*, a completeness claim this base cannot hold — and while recompute still retires it correctly, its proof cannot say why it was withdrawn, and nothing incremental could ever wake it. Row count, unit checking and division by zero are the costs |
+| 0033 | [RSS summaries are scoped to the source being listed](0033-rss-source-summaries-are-source-scoped.md) | Query implemented for #417 · source- and generation-scoped lateral aggregation preserves the flat API; nested `rss_full_content` public contract pending; baseline rows are intentionally outside the five work counts |
## Not a decision record