@startsimpli/integrations 0.2.31 → 0.2.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.31",
+  "version": "0.2.33",
   "description": "Provider-agnostic types, API clients, hooks, and UI primitives for email + calendar integrations across StartSimpli apps.",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/__tests__/corpus-narrowed-reads.test.ts

@@ -0,0 +1,337 @@
+/**
+ * THE CLIENT ASKS THE SERVER FOR A NARROWER ANSWER, AND CHECKS THAT IT GOT ONE.
+ *
+ * Two bugs, one root cause (bd startsim-o0o6o.2, bd startsim-o0o6o.3). The
+ * corpus adapter was written against a tenant data plane that filtered on
+ * `?type=` and nothing else, and several of its comments still assert that as
+ * fact. It has not been true since bd startsim-768w.38.12 and bd startsim-te3r:
+ * `RelationshipQuery` applies `entity__in` bounded at `MAX_ID_LIST` ids, and
+ * `TenantPageNumberPagination` honours `page_size` up to 200.
+ *
+ * WHY THE ANSWER IS CHECKED AND NOT ASSUMED. The tenant's response to a filter
+ * it does not recognise is an UNFILTERED PAGE with the parameter named in
+ * `ignored_filters` (bd startsim-768w.38.39) — not a 400 and not an empty list.
+ * So "send the filter and trust the rows" is the dangerous shape here: the reply
+ * to a narrowing request that was ignored looks exactly like a narrow answer
+ * with a lot of rows in it. start-simpli#154 set the precedent — read the
+ * server's own `applied_filters` and do not use an unconfirmed result — and the
+ * fakes below behave the way the wire behaves, ignoring what they do not support
+ * and answering as wide as they were asked.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { createCorpusApi } from '../corpus/client';
+import type { CorpusHttp } from '../corpus/client';
+import { startExtractionRun } from '../corpus/runs';
+import {
+  DEFAULT_RUN_KEY,
+  DEFAULT_TYPE_KEYS,
+  MAX_ID_LIST,
+  extractionRunToEntity,
+} from '../corpus/entities';
+import type { TenantEntity, TenantRelationship } from '../corpus/entities';
+import {
+  createFixtureCorpusApi,
+  createFixtureCorpusHttp,
+  createFixtureExtractor,
+  FIXTURE_ORG,
+  FIXTURE_SOURCE_LABELS,
+} from '../corpus/fixtures';
+import type { ExtractionRun, ExtractionRunStore } from '../corpus/types';
+
+const SCOPE = { orgId: FIXTURE_ORG };
+
+function apiOver(overrides: Parameters<typeof createFixtureCorpusHttp>[0] = {}) {
+  const { http, requests } = createFixtureCorpusHttp(overrides);
+  const api = createCorpusApi({ http, scope: SCOPE, sourceLabels: FIXTURE_SOURCE_LABELS });
+  return { api, requests };
+}
+
+// ---------------------------------------------------------------------------
+//  bd startsim-o0o6o.3 — the sweep record, past the fifth row
+// ---------------------------------------------------------------------------
+
+function run(id: string): ExtractionRun {
+  return {
+    runId: id,
+    scope: SCOPE,
+    status: 'succeeded',
+    cursor: 4,
+    totalDocuments: 4,
+    totals: {
+      documentsProcessed: 4, fromRules: 2, fromModel: 1, ungrounded: 0, unconfirmed: 0,
+      created: 3, merged: 0, resolved: 0, droppedOutOfScope: 0, modelCalls: 4, modelFailures: 0,
+    },
+    processedIds: [],
+    modelIncompleteIds: [],
+    needsReview: [],
+    provider: { provider: 'fixture', model: 'fixture-rules', live: false },
+    startedAt: '2026-08-01T10:00:00Z',
+    updatedAt: '2026-08-01T10:06:00Z',
+    finishedAt: '2026-08-01T10:06:00Z',
+    leaseOwner: null,
+    leaseUntil: null,
+    error: null,
+    lastModelFailure: null,
+    history: [],
+  };
+}
+
+/** The singleton row, exactly as `writeRun` lands it. */
+function singleton(): TenantEntity {
+  return {
+    id: 'run-singleton',
+    ...extractionRunToEntity(run('sweep-1'), DEFAULT_TYPE_KEYS.extractionRun, DEFAULT_RUN_KEY),
+  };
+}
+
+/**
+ * Rows that are NOT the singleton, and which is which is not a hypothetical.
+ *
+ * A second workspace key, a renamed `runKey`, a partial migration or a
+ * hand-written row all put `extraction_run` rows next to it, and the tenant
+ * orders entities `-created_at` — so the singleton, which is the OLDEST because
+ * it was written first and is rewritten in place, sorts LAST. Newest first is
+ * the order these arrive in.
+ */
+function noise(count: number): TenantEntity[] {
+  return Array.from({ length: count }, (_, index) => ({
+    id: `run-noise-${index}`,
+    entity_type: DEFAULT_TYPE_KEYS.extractionRun,
+    external_id: `corpus-extraction-sweep-other-${index}`,
+    name: `Extraction sweep other-${index}`,
+    data: { run: JSON.stringify(run(`other-${index}`)), _origin: 'tenant-extraction' },
+  }));
+}
+
+describe('readRun tells "nothing has ever run" apart from "I could not tell"', () => {
+  it('finds the singleton when it is NOT among the newest five rows', async () => {
+    // Six rows, singleton last: the exact corpus at which `page_size: 5` starts
+    // answering `null` — which every caller reads as "no sweep has ever run" and
+    // `startExtractionRun` acts on by starting a duplicate sweep.
+    const { api } = apiOver({ entities: [...noise(5), singleton()], relationships: [] });
+
+    const read = await api.readRun();
+
+    expect(read?.runId).toBe('sweep-1');
+  });
+
+  it('THROWS rather than reporting "never run" when the row could be past the cap', async () => {
+    // Past the server's own `max_page_size`, one read genuinely cannot see every
+    // row — and the honest answer to "has a sweep run here" is then neither the
+    // run nor `null`. `null` is a FACT in this contract; a truncated page is not
+    // evidence for it.
+    const { api } = apiOver({
+      entities: [...noise(MAX_ID_LIST + 20), singleton()],
+      relationships: [],
+    });
+
+    await expect(api.readRun()).rejects.toThrow(/could not/i);
+  });
+
+  it('still answers null for a workspace where nothing HAS run', async () => {
+    // The fact this whole contract exists to preserve: absence is reportable.
+    const { api } = apiOver({ entities: [], relationships: [] });
+
+    expect(await api.readRun()).toBeNull();
+  });
+
+  it('matches the singleton key in EITHER spelling the wire delivers it in', async () => {
+    // `@startsimpli/api`'s fetch wrapper transforms every response key
+    // snake_case -> camelCase, so a browser-side read of this row carries
+    // `externalId` and never `external_id`. This lookup read one spelling, so in
+    // the browser it matched nothing at ANY page size and reported "never run"
+    // over a workspace with a sweep in it — the same seam, and the same lie, as
+    // reading one spelling of `applied_filters`.
+    const { external_id: key, ...rest } = singleton();
+    const { api } = apiOver({
+      entities: [{ ...rest, externalId: key }],
+      relationships: [],
+    });
+
+    expect((await api.readRun())?.runId).toBe('sweep-1');
+  });
+
+  it('asks for the widest page the server will serve, not five rows', async () => {
+    const { api, requests } = apiOver({ entities: [singleton()], relationships: [] });
+    await api.readRun();
+
+    const read = requests.find(
+      (request) => request.params.type === DEFAULT_TYPE_KEYS.extractionRun,
+    );
+    expect(read?.params.page_size).toBe(MAX_ID_LIST);
+  });
+});
+
+// ---------------------------------------------------------------------------
+//  bd startsim-o0o6o.2 — the edges of ONE PAGE, not the whole edge table
+// ---------------------------------------------------------------------------
+
+const PARTY: TenantEntity = {
+  id: 'party_dana', entity_type: 'party', external_id: 'granola:dana@example.com',
+  name: 'Dana Reed',
+  data: { display_name: 'Dana Reed', email: 'dana@example.com', source: 'granola' },
+};
+
+function document(id: string): TenantEntity {
+  return {
+    id, entity_type: 'source_document', external_id: `granola:${id}`, name: `Record ${id}`,
+    data: { source: 'granola', title: `Record ${id}`, occurred_at: '2026-08-01T09:00:00Z' },
+  };
+}
+
+describe('the participant join reads the edges of a PAGE, not the edge table', () => {
+  it('names the page’s ids in entity__in instead of asking for everything', async () => {
+    const { api, requests } = apiOver();
+    await api.listDocuments({ page: 1, pageSize: 3 });
+
+    const edgeReads = requests.filter((request) => request.path.includes('relationships'));
+    expect(edgeReads.length).toBeGreaterThan(0);
+    // THE ASSERTION THIS FILE EXISTS FOR. `readAll(relationships, {})` sent no
+    // parameters at all and walked up to twenty pages of every edge in the
+    // workspace, on a comment claiming the endpoint had no filters.
+    for (const read of edgeReads) {
+      const named = String(read.params.entity__in ?? '').split(',').filter(Boolean);
+      expect(named.length).toBeGreaterThan(0);
+      expect(named.length).toBeLessThanOrEqual(MAX_ID_LIST);
+    }
+    expect(String(edgeReads[0].params.entity__in).split(',')).toHaveLength(3);
+  });
+
+  it('still resolves the people on the page it narrowed to', async () => {
+    const { api } = apiOver({
+      entities: [document('doc-1'), PARTY],
+      relationships: [{ id: 'e1', rel_type: 'authored_by', source: 'doc-1', target: 'party_dana' }],
+    });
+
+    const page = await api.listDocuments({ page: 1 });
+
+    expect(page.results[0].participants.map((party) => party.name)).toEqual(['Dana Reed']);
+  });
+
+  it('chunks a page wider than the server’s id bound rather than being refused', async () => {
+    // A fork whose `max_page_size` is larger than `MAX_ID_LIST` hands back more
+    // ids than one `entity__in` may carry, and `_uuid_list` answers a longer
+    // list with a 400 — so the ids are chunked. Truncating them instead would
+    // drop the people off the tail of the page silently, which is the failure
+    // this whole change is undoing.
+    const documents = Array.from({ length: MAX_ID_LIST + 40 }, (_, index) =>
+      document(`doc-${index}`),
+    );
+    const last = documents[documents.length - 1];
+    const { api, requests } = apiOver({
+      pageSize: documents.length,
+      entities: [...documents, PARTY],
+      relationships: [
+        { id: 'e-last', rel_type: 'involves', source: String(last.id), target: 'party_dana' },
+      ],
+    });
+
+    const page = await api.listDocuments({ page: 1 });
+
+    const edgeReads = requests.filter((request) => request.path.includes('relationships'));
+    expect(edgeReads.length).toBeGreaterThan(1);
+    for (const read of edgeReads) {
+      expect(String(read.params.entity__in).split(',').length).toBeLessThanOrEqual(MAX_ID_LIST);
+    }
+    const tail = page.results.find((record) => record.id === String(last.id));
+    expect(tail?.participants.map((party) => party.name)).toEqual(['Dana Reed']);
+  });
+});
+
+/**
+ * A fork that has NOT shipped `RelationshipQuery`.
+ *
+ * It does what the tenant documents itself as doing with a parameter it does not
+ * know: names it in `ignored_filters` and answers with the page exactly as wide
+ * as it was. A fake that returned `[]` here would let the client pass this suite
+ * while reading the whole edge table in production, which is the trap this test
+ * is written to spring.
+ */
+function unfilteredEdgeHttp(edges: TenantRelationship[], rows: TenantEntity[]) {
+  const requests: Array<{ path: string; params: Record<string, unknown> }> = [];
+  const http: CorpusHttp = {
+    async get<T>(path: string, init?: { params?: Record<string, unknown> }): Promise<T> {
+      const params = init?.params ?? {};
+      requests.push({ path, params });
+      if (path.includes('relationships')) {
+        return {
+          count: edges.length, next: null, previous: null, results: edges,
+          applied_filters: [],
+          ignored_filters: Object.keys(params).filter(
+            (key) => key !== 'page' && key !== 'page_size',
+          ),
+        } as T;
+      }
+      if (path.includes('entities')) {
+        const type = params.type ? String(params.type) : '';
+        const matching = type ? rows.filter((row) => row.entity_type === type) : rows;
+        return {
+          count: matching.length, next: null, previous: null, results: matching,
+          applied_filters: [],
+          ignored_filters: [],
+        } as T;
+      }
+      throw Object.assign(new Error(`${path} responded 404`), { status: 404 });
+    },
+  };
+  return { http, requests };
+}
+
+describe('an unconfirmed narrowing is not used', () => {
+  it('renders no participants rather than joining an unnarrowed page of edges', async () => {
+    // start-simpli#154's precedent, on the read that matters most: the server
+    // reported it did NOT apply `entity__in`, so the rows it sent are an
+    // arbitrary page of the whole edge table and joining them would put the
+    // wrong people — or a partial list of the right ones — on the record. The
+    // Library degrades to what it showed before the join existed.
+    const { http, requests } = unfilteredEdgeHttp(
+      [{ id: 'e1', rel_type: 'authored_by', source: 'doc-1', target: 'party_dana' }],
+      [document('doc-1'), PARTY],
+    );
+    const api = createCorpusApi({ http, scope: SCOPE, sourceLabels: FIXTURE_SOURCE_LABELS });
+
+    const page = await api.listDocuments({ page: 1 });
+
+    expect(page.results).toHaveLength(1);
+    expect(page.results[0].participants).toEqual([]);
+    // And it does not go on to read the party roster for a join it will not do.
+    expect(requests.filter((request) => request.params.type === 'party')).toHaveLength(0);
+  });
+});
+
+describe('a store that could not answer never becomes "no sweep has ever run"', () => {
+  it('refuses to start a second sweep over a cursor it was unable to read', async () => {
+    // THE REASON THE THIRD ANSWER HAD TO REACH THIS CALLER. `startExtractionRun`
+    // swallowed every `readRun` failure into `null` and `null` means "start a
+    // new sweep" one branch later, so an undetermined read put a SECOND driver
+    // on a live cursor — and two model calls over one document produce two
+    // differently-worded items dedupe cannot see are the same, which is how a
+    // live re-run once turned 82 commitments into 98.
+    let writes = 0;
+    const runs: ExtractionRunStore = {
+      async readRun() {
+        throw Object.assign(
+          new Error('Could not determine whether a sweep has run in this workspace.'),
+          { status: 409 },
+        );
+      },
+      async writeRun(run) {
+        writes += 1;
+        return run;
+      },
+    };
+
+    await expect(
+      startExtractionRun(
+        { scope: SCOPE },
+        {
+          corpus: createFixtureCorpusApi({ scope: SCOPE }),
+          extractor: createFixtureExtractor(),
+          runs,
+        },
+      ),
+    ).rejects.toThrow(/could not determine/i);
+    expect(writes).toBe(0);
+  });
+});

package/src/__tests__/corpus-source-strip.test.tsx

@@ -241,3 +241,228 @@ describe('the Library strip, rendered', () => {
     expect(screen.queryByText(/Dropbox/)).not.toBeInTheDocument();
   });
 });
+
+/**
+ * THE COUNT ON THE CARD IS A CORPUS FACT, AND IT WAS NEVER READ
+ * (bd startsim-jevtu RED, first filed as startsim-o0o6o.1).
+ *
+ * REPORTED ON THE LIVE TANDEM TENANT, 2026-08-26: Dropbox, Fathom, Granola and
+ * n8n each read "0 records" while the list directly beneath the strip read
+ * "208 records · page 1 of 11". `listSources()` computed the number as
+ * `connection.document_count ?? connection.documentCount ?? 0` and NO
+ * connections endpoint sends either spelling — `SubtreeConnectionsView`
+ * serialises id, connector_key, connector_name, name, status, account_label,
+ * the three timestamps, consecutive_failures and check_error, and no count. So
+ * every card has read `0` for every foundry since the strip shipped.
+ *
+ * WHY THE NUMBER COMES FROM THE TENANT CORPUS AND NOT FROM CENTRAL.
+ *
+ *   1. Central does not have the rows. The corpus lives in the fork; central
+ *      delivers INTO it (`corpus_delivery.py`) and keeps no copy. A count
+ *      annotated onto the connection would be a count of records central
+ *      believes it shipped — a different number from the one in the list under
+ *      the strip the moment an upsert collapses two records, a retention rule
+ *      trims, or a delivery half-lands. A strip that disagrees with the list
+ *      beneath it is the exact fault class this bead is about; a delivery
+ *      counter would re-open it in a new spelling.
+ *
+ *   2. Every other fact on the card already comes from central's connection
+ *      row — status, the three timestamps, the failure streak. The corpus count
+ *      is the ONLY corpus-side fact on a strip that sits on top of the corpus,
+ *      and that is what makes it worth its round trip: "central says it synced
+ *      an hour ago, the corpus holds nothing from it" is the delivery-hop
+ *      failure, and no connection field can say it.
+ *
+ * WHY THIS IS NOT A SCAN. The tenant's own `/api/v1/capabilities/` declares
+ * `"counts": "page-count"` and says in as many words that a focus card's
+ * "12 of 40 done" is "two `page_size=1` reads off the paginator's own `count` —
+ * said here so a client does not go looking for a group_by endpoint that
+ * deliberately does not exist". One narrowed request per source, asking for one
+ * row, reading the envelope's `count`: one SQL COUNT with the filter pushed
+ * down, which is the sanctioned idiom on this platform and not eleven pages.
+ *
+ * WHY IT IS UNBLOCKED. bd startsim-768w.38.12 shipped `?source=` and verified it
+ * on this very tenant ("source=granola 16 / stripe 0"). The vocabulary lines up
+ * by construction, not by luck: central serialises `connector_key` as
+ * `connection.connector.key`, `corpus_delivery` stamps `source_key =
+ * connector_cls.key` onto every projected record, and the catalog reconciler
+ * creates each `DestinationProvider` row AT the connector class's own key. The
+ * canonical mapping says it outright — "`source` is the connector key, so
+ * 'everything from Granola' is one filter".
+ *
+ * AND WHY `null` HAS TO EXIST. `0` today means "we never asked". After this it
+ * must mean "we asked and the answer is none" — otherwise the fix replaces a
+ * lie with a lie that happens to be right some of the time. A build that cannot
+ * narrow by source returns the WHOLE corpus for every card, which would print
+ * "208 records" four times over; the server's own `applied_filters` is what
+ * tells the two apart, and a count that cannot be trusted is not printed.
+ */
+
+/** Per-source totals as a tenant that really does honour `?source=` reports them. */
+function corpusOver(
+  rows: Array<Record<string, unknown>>,
+  counts: Record<string, number>,
+  options: { reports?: 'snake' | 'camel' | 'none' } = {},
+): Recorder {
+  const reports = options.reports ?? 'snake';
+  const whole = Object.values(counts).reduce((sum, n) => sum + n, 0);
+  const calls: Array<{ path: string; params?: Record<string, unknown> }> = [];
+  return {
+    calls,
+    http: {
+      async get<T>(path: string, init?: { params?: Record<string, unknown> }): Promise<T> {
+        const params = init?.params ?? {};
+        calls.push({ path, params });
+        if (path.includes('connections')) {
+          return { count: rows.length, next: null, previous: null, results: rows } as T;
+        }
+        const source = params.source === undefined ? '' : String(params.source);
+        // A build with no `?source=` narrows NOTHING and hands back the whole
+        // corpus — the failure mode that would print 208 on every card.
+        const narrowed = reports !== 'none' && Boolean(source);
+        const count = narrowed ? (counts[source] ?? 0) : whole;
+        const applied = narrowed ? ['type', 'source'] : ['type'];
+        return {
+          count,
+          next: null,
+          previous: null,
+          // Faithful to the wire: a `page_size=1` read over a non-empty match
+          // returns a row. A count read must not need it.
+          results: count > 0 ? [{ id: 'row', entity_type: 'source_document', data: {} }] : [],
+          ...(reports === 'snake' ? { applied_filters: applied } : {}),
+          ...(reports === 'camel' ? { appliedFilters: applied } : {}),
+        } as T;
+      },
+    },
+  };
+}
+
+/** A second shared connection, one that has delivered nothing — as tandem has. */
+const SHARED_N8N = {
+  id: 'shared-n8n',
+  connector_key: 'n8n',
+  connector_name: 'n8n',
+  status: 'connected',
+  check_error: '',
+  last_synced_at: AN_HOUR_AGO,
+  last_attempt_at: AN_HOUR_AGO,
+  last_checked_at: AN_HOUR_AGO,
+  consecutive_failures: 0,
+};
+
+const TANDEM_COUNTS = { granola: 208, n8n: 0 };
+
+function countedSources(options: { reports?: 'snake' | 'camel' | 'none' } = {}) {
+  const { http } = corpusOver([SHARED_GRANOLA, SHARED_N8N], TANDEM_COUNTS, options);
+  return createCorpusApi({ http, scope: SCOPE }).listSources();
+}
+
+describe('listSources — the record count is counted, not read off the connection', () => {
+  it('reports what each source actually put in the corpus', async () => {
+    const sources = await countedSources();
+    const byKey = Object.fromEntries(sources.map((source) => [source.source, source.documentCount]));
+
+    // The whole bug in one assertion: Granola holds 208 records and the card
+    // said 0, because it was reading a field central has never sent.
+    expect(byKey).toEqual({ granola: 208, n8n: 0 });
+  });
+
+  it('counts DOCUMENTS, so the strip agrees with the list beneath it', async () => {
+    // A count over every entity type would sweep in parties, money events and
+    // commitments and overshoot the list it sits above. Same type key, same
+    // read gate, same server — the two agree by construction or not at all.
+    const recorder = corpusOver([SHARED_GRANOLA, SHARED_N8N], TANDEM_COUNTS);
+    await createCorpusApi({ http: recorder.http, scope: SCOPE }).listSources();
+
+    const reads = recorder.calls.filter((call) => call.path.includes('entities'));
+    expect(reads.length).toBeGreaterThan(0);
+    for (const call of reads) expect(call.params?.type).toBe('source_document');
+  });
+
+  it('asks for ONE row per source and never pages the corpus', async () => {
+    // "Eleven pages per card" is the same wrong answer with worse latency. The
+    // count comes off the paginator's own envelope, which costs one row.
+    const recorder = corpusOver([SHARED_GRANOLA, SHARED_N8N], TANDEM_COUNTS);
+    await createCorpusApi({ http: recorder.http, scope: SCOPE }).listSources();
+
+    const reads = recorder.calls.filter((call) => call.path.includes('entities'));
+    expect(reads).toHaveLength(2);
+    expect(reads.map((call) => call.params?.source).sort()).toEqual(['granola', 'n8n']);
+    for (const call of reads) expect(call.params?.page_size).toBe(1);
+  });
+
+  it('counts a vendor once when two connections name it', async () => {
+    // A card is per CONNECTION, a count is per SOURCE. Central's page unions the
+    // foundry's shared connections with the member's own, so one vendor can
+    // arrive twice — and whose account it is does not narrow the corpus. Two
+    // reads for one answer, and both cards must report that answer rather than
+    // half of it each.
+    const MY_GRANOLA = { ...SHARED_GRANOLA, id: 'my-granola', owner: 'qosha@debugg.ai' };
+    const recorder = corpusOver([SHARED_GRANOLA, MY_GRANOLA, SHARED_N8N], TANDEM_COUNTS);
+    const sources = await createCorpusApi({ http: recorder.http, scope: SCOPE }).listSources();
+
+    const reads = recorder.calls.filter((call) => call.path.includes('entities'));
+    expect(reads.filter((call) => call.params?.source === 'granola')).toHaveLength(1);
+    expect(
+      sources.filter((source) => source.source === 'granola').map((s) => s.documentCount),
+    ).toEqual([208, 208]);
+  });
+
+  it('says 0 because the corpus answered 0, not because nobody asked', async () => {
+    const n8n = (await countedSources()).find((source) => source.source === 'n8n');
+
+    // n8n declares no corpus mapping at all (`corpus_delivery` returns early on
+    // it), so zero is the true answer — and it has to be distinguishable from
+    // the count nobody went and got.
+    expect(n8n?.documentCount).toBe(0);
+  });
+
+  it('reads the server’s report in either spelling', async () => {
+    // `@startsimpli/api` camelCases response keys in the browser and a plain
+    // server-side fetch does not. Reading one spelling made the deployed
+    // Tracker report the server was not filtering while it verifiably was; the
+    // same seam decides here whether a real count is thrown away.
+    const sources = await countedSources({ reports: 'camel' });
+
+    expect(sources.find((source) => source.source === 'granola')?.documentCount).toBe(208);
+  });
+
+  it('refuses to print the whole corpus when the server could not narrow by source', async () => {
+    // The regression this fix could otherwise introduce: an older fork ignores
+    // `?source=`, hands back the total, and every card reads "208 records". The
+    // server says what it applied; a count it did not narrow is not a count.
+    const sources = await countedSources({ reports: 'none' });
+
+    expect(sources.map((source) => source.documentCount)).toEqual([null, null]);
+  });
+});
+
+describe('the Library strip, counting', () => {
+  const strip = async () =>
+    within(await screen.findByRole('region', { name: 'Source freshness' }));
+
+  it('prints the count the corpus actually holds', async () => {
+    const { http } = corpusOver([SHARED_GRANOLA, SHARED_N8N], TANDEM_COUNTS);
+    render(<LibraryPage api={createCorpusApi({ http, scope: SCOPE })} scope={SCOPE} />);
+
+    expect((await strip()).getByText(/208 records/)).toBeInTheDocument();
+  });
+
+  it('says a source has delivered nothing, in words', async () => {
+    const { http } = corpusOver([SHARED_GRANOLA, SHARED_N8N], TANDEM_COUNTS);
+    render(<LibraryPage api={createCorpusApi({ http, scope: SCOPE })} scope={SCOPE} />);
+
+    expect((await strip()).getByText(/No records yet/)).toBeInTheDocument();
+  });
+
+  it('prints no number at all when the count is unknown', async () => {
+    const { http } = corpusOver([SHARED_GRANOLA, SHARED_N8N], TANDEM_COUNTS, { reports: 'none' });
+    render(<LibraryPage api={createCorpusApi({ http, scope: SCOPE })} scope={SCOPE} />);
+
+    const shown = await strip();
+    // The freshness half of the card is unaffected — a count it could not get
+    // costs the reader the count, not the sentence.
+    expect(shown.getAllByText(/synced/).length).toBeGreaterThan(0);
+    expect(shown.queryByText(/record/)).not.toBeInTheDocument();
+  });
+});

package/src/__tests__/corpus-storage.test.ts

@@ -191,8 +191,10 @@ describe('both storage shapes, because both are real', () => {
   });
 });
 
-describe('the graph read is bounded, cached and fails soft', () => {
-  it('costs ONE graph read across a list, a detail and a second page', async () => {
+describe('the graph read is narrowed, cached and fails soft', () => {
+  it('costs ONE edge read across a list, a detail and a second page', async () => {
+    // The records are remembered per row, so re-listing them and then opening
+    // one of them asks the server nothing further (bd startsim-o0o6o.2).
     const { api, requests } = apiOver();
     await api.listDocuments({ page: 1 });
     await api.listDocuments({ page: 1 });
@@ -220,17 +222,26 @@ describe('the graph read is bounded, cached and fails soft', () => {
     expect(page.results.every((document) => document.participants.length === 0)).toBe(true);
   });
 
-  it('walks every page of the graph, since the tenant ignores page_size', async () => {
-    // Two rows a page: the edges for the last document are only reachable by
-    // paging, which is exactly what the real PAGE_SIZE=50 does at scale.
+  it('narrows the edge read to the ids of the page it is rendering', async () => {
+    // THIS TEST USED TO ASSERT THE OPPOSITE, and its title said why: "walks
+    // every page of the graph, since the tenant ignores page_size". Neither half
+    // survived contact with the deployed server. `page_size` is honoured
+    // (`TenantPageNumberPagination`, bd startsim-768w.38.12) and the edge table
+    // is filterable (`RelationshipQuery`, bd startsim-te3r) — so a page deep in
+    // the corpus no longer reaches its people by reading every edge in the
+    // workspace and joining in the browser. It ASKS for the edges of the two
+    // rows it is rendering, which is the read that scales with the page instead
+    // of with the corpus (bd startsim-o0o6o.2).
     const { api, requests } = apiOver({ pageSize: 2 });
-    // `pageSize: 100` is ignored by the server, exactly as the tenant ignores
-    // it — so the Dropbox row is on page THREE however wide the caller asked.
-    const page = await api.listDocuments({ page: 3, pageSize: 100 });
+    const page = await api.listDocuments({ page: 3 });
     const dropbox = page.results.find((document) => document.id === 'dbx_9812f0');
 
     expect(dropbox?.participants.map((party) => party.name)).toEqual(['Acme Robotics', 'Dana Reed']);
-    expect(requests.filter((request) => request.path.includes('relationships')).length).toBeGreaterThan(1);
+    const edgeReads = requests.filter((request) => request.path.includes('relationships'));
+    expect(edgeReads).toHaveLength(1);
+    expect(String(edgeReads[0].params.entity__in).split(',')).toEqual(
+      page.results.map((document) => document.id),
+    );
   });
 });
 

package/src/components/pages/LibraryPage.tsx

@@ -519,6 +519,31 @@ const FRESHNESS_WORDS: Record<SourceFreshness['status'], string> = {
   never: 'Nothing yet',
 };
 
+/**
+ * The count clause of a source card, or nothing at all (bd startsim-jevtu).
+ *
+ * THREE STATES, NOT TWO. `null` is "this workspace's API could not narrow the
+ * corpus by source, so the only number available describes every source at
+ * once" — printing it would put the same total on every card, which is the
+ * failure this replaced wearing a bigger number. Saying nothing is the honest
+ * option, and it costs the reader the count rather than the card.
+ *
+ * `0` is spelled out in words rather than left as a bare digit because "0
+ * records" is exactly what the broken version printed for years; a source that
+ * has genuinely delivered nothing deserves a sentence that could not be
+ * produced by not asking.
+ *
+ * NOTE THE SCOPE. This is the source's WHOLE contribution, unfiltered — the
+ * strip describes sources, while the list beneath it answers the current query.
+ * A card reading "208 records" above a list reading "3 records" under an active
+ * search is the two questions being different, not a disagreement.
+ */
+function countClause(count: SourceFreshness['documentCount']): string {
+  if (count === null || count === undefined) return '';
+  if (count === 0) return 'No records yet · ';
+  return `${count} record${count === 1 ? '' : 's'} · `;
+}
+
 function FreshnessStrip({
   sources, classNames: cn, now,
 }: { sources: SourceFreshness[]; classNames: Record<LibrarySlot, string>; now: number }) {
@@ -537,8 +562,7 @@ function FreshnessStrip({
               </span>
             </div>
             <p className={cn.muted}>
-              {source.documentCount} record{source.documentCount === 1 ? '' : 's'} · synced{' '}
-              {relative(source.lastSyncedAt, now)}
+              {countClause(source.documentCount)}synced {relative(source.lastSyncedAt, now)}
             </p>
             {/* A source that is failing says so HERE, next to the corpus it is
                 supposed to be filling — not on a settings page nobody opens. */}