@startsimpli/integrations 0.2.31 → 0.2.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.31",
+  "version": "0.2.32",
   "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-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/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. */}

package/src/corpus/client.ts

@@ -11,11 +11,16 @@
  * there must not be: it produces a list whose count disagrees with its rows and
  * that stops working at exactly the corpus size where it starts to matter.
  *
- * WHAT THE BACKEND HONOURS TODAY: `tenant-starter`'s `EntityViewSet` filters on
- * `?type=` and nothing else — no `search`, no `source`, no date window (see
- * `apps/api/views.py`). So `supportedFilters` defaults to `[]` and the composer
- * says so on screen rather than pretending. Pass the real list once the tenant
- * API gains them; the request already sends every parameter.
+ * WHAT THE BACKEND HONOURS IS THE BACKEND'S TO SAY, NOT THIS FILE'S. It once
+ * said here that `tenant-starter`'s `EntityViewSet` filters on `?type=` and
+ * nothing else; bd startsim-768w.38.12 shipped `search`, `source`, `party`, the
+ * date window and `order`, and the comment stayed behind — which is exactly why
+ * a hardcoded list is the wrong mechanism. Every list response carries the
+ * server's own `applied_filters`/`ignored_filters`, `/api/v1/capabilities/`
+ * describes the deployed build, and both are read in preference to anything
+ * declared client-side. `supportedFilters` remains only as the fallback for a
+ * fork too old to report, and a deployment that passes a stale one is corrected
+ * by the server rather than believed.
  *
  * PEOPLE ARE A SECOND READ, NOT A SECOND COPY (bd startsim-768w.38.22). The
  * corpus delivery writes participants as typed `authored_by` / `involves` edges
@@ -430,6 +435,42 @@ export function createCorpusApi(
     };
   }
 
+  /**
+   * How many DOCUMENTS one source has put in the corpus, or `null` when the
+   * server did not confirm it narrowed by source.
+   *
+   * ONE ROW, AND THE ENVELOPE'S OWN `count`. `page_size=1` is not a sample: the
+   * DRF paginator counts the filtered queryset in SQL and reports it beside the
+   * page, so this is one COUNT with `?source=` pushed down, not eleven pages
+   * added up. `types.document` is passed for the same reason the list below the
+   * strip passes it — a count over every entity type would sweep in parties,
+   * money events and commitments and stop agreeing with the list it sits above.
+   *
+   * THE GUARD IS THE SERVER'S OWN REPORT, in both spellings for the reason
+   * `ServerFilterReport` documents. A fork that predates bd startsim-768w.38.12
+   * accepts `?source=` and ignores it, so the honest-looking `count` that comes
+   * back is the whole corpus — the same number on every card. `applied_filters`
+   * naming `source` is what separates "none from this source" from "I could not
+   * ask", and only the first of those is a number worth printing.
+   */
+  async function countDocumentsFrom(source: string): Promise<number | null> {
+    if (!source || source === 'unknown') return null;
+    try {
+      const response = await http.get<DrfPage<TenantEntity> & ServerFilterReport>(entities, {
+        params: { type: types.document, source, page_size: 1 },
+      });
+      const applied = response.applied_filters ?? response.appliedFilters;
+      if (!applied?.includes('source')) return null;
+      const count = Number(response.count);
+      return Number.isFinite(count) ? count : null;
+    } catch {
+      // A count is an ornament on a card whose point is freshness. Losing it
+      // costs the reader a number; failing the whole strip would cost the four
+      // facts the card exists for.
+      return null;
+    }
+  }
+
   /** Every page of a DRF list, up to the cap. Stops on the first failure. */
   async function readAll<T>(path: string, extra: Record<string, unknown>): Promise<T[]> {
     const rows: T[] = [];
@@ -670,26 +711,72 @@ export function createCorpusApi(
      * exactly the lie bd startsim-1cow removed. Rows are read from one endpoint,
      * as handed.
      *
-     * `documentCount` is whatever the connections payload says and is therefore
-     * `0` today: no connections endpoint sends `document_count`, and a per-source
-     * count from the corpus needs the `?source=` filter bd startsim-768w.38.12
-     * is still open on. Tracked as bd startsim-o0o6o.1.
+     * `documentCount` IS THE ONE CORPUS-SIDE FACT ON THIS CARD, and it is
+     * counted here rather than read off the connection (bd startsim-jevtu, first
+     * filed as startsim-o0o6o.1). It used to be
+     * `connection.document_count ?? connection.documentCount ?? 0` over a
+     * payload that has never carried either spelling, so every card on every
+     * foundry read "0 records" — on tandem, four of them, directly above a list
+     * reading "208 records".
+     *
+     * CENTRAL CANNOT ANSWER IT. The corpus lives in the fork; central delivers
+     * INTO it and keeps no copy, so a count annotated onto the connection would
+     * be a count of what central believes it shipped — a different number from
+     * the list under the strip as soon as an upsert collapses two records or a
+     * delivery half-lands. A strip that disagrees with its own list is the fault
+     * being fixed, not a fix for it. And the disagreement is the POINT: every
+     * other field on this card comes from central's connection row, so "central
+     * says it synced an hour ago, the corpus holds nothing from it" is the
+     * delivery-hop failure made visible, which no connection field can say.
+     *
+     * ONE COUNT PER SOURCE, NOT A SCAN. `page_size=1` and the paginator's own
+     * `count` — one SQL COUNT with `?source=` pushed down. That is the idiom the
+     * tenant's `/api/v1/capabilities/` declares (`"counts": "page-count"`, and
+     * "a focus card's '12 of 40 done' is two `page_size=1` reads … so a client
+     * does not go looking for a group_by endpoint that deliberately does not
+     * exist"). Paging the corpus per card would be the same wrong answer with
+     * worse latency.
+     *
+     * `null`, NEVER A GUESSED `0`. A fork that predates the `?source=` filter
+     * (bd startsim-768w.38.12) narrows nothing and hands back the WHOLE corpus,
+     * which would print the same total on every card. The server's own
+     * `applied_filters` is the only thing that tells a narrowed count from an
+     * unnarrowed one, so a count it did not confirm is not reported at all —
+     * and `0` is left free to mean what it says.
      */
     async listSources(): Promise<SourceFreshness[]> {
-      const [connectionPage, documentPage] = await Promise.all([
-        http
-          .get<DrfPage<Record<string, unknown>>>(connections)
-          .catch(() => EMPTY_PAGE as DrfPage<Record<string, unknown>>),
-        http
-          .get<DrfPage<TenantEntity>>(entities, { params: { type: types.document, page_size: 1 } })
-          .catch(() => EMPTY_PAGE as DrfPage<TenantEntity>),
-      ]);
+      const connectionPage = await http
+        .get<DrfPage<Record<string, unknown>>>(connections)
+        .catch(() => EMPTY_PAGE as DrfPage<Record<string, unknown>>);
 
-      void documentPage; // total count is per-source below; kept for the empty-corpus case
+      const live = (connectionPage.results ?? []).filter(isALiveSource).map((connection) => ({
+        connection,
+        key: String(connection.connector_key ?? connection.connectorKey ?? 'unknown'),
+      }));
+      // ONE READ PER DISTINCT SOURCE KEY, in parallel — the cards are
+      // independent and a slow source must not hold up the rest of the strip.
+      //
+      // Distinct, because a card is per CONNECTION and a count is per SOURCE,
+      // and those are not the same thing. Central's page unions the foundry's
+      // shared connections with the member's own (bd startsim-768w.22.25.11),
+      // so a shared Granola and a personal Granola arrive as two rows naming one
+      // vendor. Whose account it is belongs on the card; it does not narrow the
+      // corpus, so counting it twice would be two identical queries for one
+      // answer. Both cards then report the same total, which is the true one:
+      // the corpus does not record which of two accounts a document came in
+      // through.
+      const pending = new Map<string, Promise<number | null>>();
+      for (const { key } of live) {
+        if (!pending.has(key)) pending.set(key, countDocumentsFrom(key));
+      }
+      const counts = new Map(
+        await Promise.all(
+          [...pending].map(async ([key, count]) => [key, await count] as const),
+        ),
+      );
 
       const now = Date.now();
-      return (connectionPage.results ?? []).filter(isALiveSource).map((connection) => {
-        const key = String(connection.connector_key ?? connection.connectorKey ?? 'unknown');
+      return live.map(({ connection, key }) => {
         // THREE FACTS, READ SEPARATELY (bd startsim-1cow). This was one `??`
         // chain ending in `last_checked_at`, and central's own view says of that
         // column that it "is a far more optimistic fact than either and is never
@@ -709,7 +796,7 @@ export function createCorpusApi(
         const lastCheckedAt = at(connection.last_checked_at ?? connection.lastCheckedAt);
         const failures =
           Number(connection.consecutive_failures ?? connection.consecutiveFailures ?? 0) || 0;
-        const documentCount = Number(connection.document_count ?? connection.documentCount ?? 0);
+        const documentCount = counts.get(key) ?? null;
         const error = String(connection.check_error ?? connection.checkError ?? '');
         const status = connection.status ?? '';
 

package/src/corpus/fixtures.ts

@@ -869,7 +869,12 @@ export function createFixtureCorpusApi(options: FixtureCorpusOptions = {}): Corp
  *     search since this was written (bd startsim-768w.38.12) and a retrieval
  *     test must be written against the real semantics, but the suites that
  *     predate it are still testing what they were written to test. `source` and
- *     `party` are still accepted and ignored, exactly as `EntityViewSet` does;
+ *     `party` are accepted and ignored HERE, and this fixture no longer claims
+ *     that is what `EntityViewSet` does: 768w.38.12 shipped both, along with the
+ *     `applied_filters` report that names what the server narrowed by. So this
+ *     stands in for an OLDER fork — which is a useful thing to have a stand-in
+ *     for, since that is the fork `listSources` refuses to print a count for
+ *     (bd startsim-jevtu), but it is a lagging stub and not the contract;
  *   • `page_size` is IGNORED (`PageNumberPagination` with no
  *     `page_size_query_param`), so a caller asking for 200 gets `pageSize`;
  *   • `/api/v1/relationships/` returns every edge in the org, unfiltered,

package/src/corpus/types.ts

@@ -172,8 +172,22 @@ export interface MoneyEvent {
 export interface SourceFreshness {
   source: SourceKey;
   label: string;
-  /** How many documents this source has contributed to the corpus. */
-  documentCount: number;
+  /**
+   * How many documents this source has contributed to the corpus — counted OUT
+   * OF THE CORPUS, per source, and the only fact on a freshness card that is
+   * not central's connection bookkeeping (bd startsim-jevtu). That is what
+   * makes it worth its round trip: a source central reports as freshly synced
+   * that holds nothing here is the delivery hop failing, and no timestamp on
+   * the connection can say so.
+   *
+   * `null` means NOT COUNTED — the server did not confirm it narrowed by
+   * source, so the number it returned describes the whole corpus rather than
+   * this card. A screen renders nothing at all for `null`. `0` therefore means
+   * exactly what it says, which it did not before: the field was read off a
+   * connections payload that has never carried it, so every card everywhere
+   * reported `0` by accident.
+   */
+  documentCount: number | null;
   /**
    * THREE FACTS, AND CONFLATING ANY TWO OF THEM IS HOW A FRESHNESS STRIP LIES
    * (bd startsim-1cow). Central's `SubtreeConnectionsView` computes them