@startsimpli/integrations 0.2.30 → 0.2.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.30",
+  "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__/connections.test.tsx

@@ -813,9 +813,15 @@ describe('ConnectionCard — a connected account has settings', () => {
  *     — "there is no id here to substitute, no slug to swap". A client that
  *     takes a slug re-introduces, in the types, the exact affordance that URL
  *     space was designed not to have.
- *   * NO PATCH. `MyConnectionDetailView` serves GET and DELETE only, so the
- *     capability picker is informational and there is no Save beside it, and no
- *     settings form.
+ *   * NO GENERAL PATCH. `MyConnectionDetailView` still serves GET and DELETE
+ *     only, so a card's NAME and what it may DO stay the foundry's and the
+ *     capability picker is informational with no Save beside it. The one write
+ *     verb the member surface grew is `updateConnectionConfig` (bd
+ *     startsim-sfms2) — a personal connection's config is the member's own
+ *     privacy boundary — and it is a separate verb precisely so opening it does
+ *     not open the capability Save. This stub does not carry it, and this
+ *     connector declares no config fields, so no settings control renders here;
+ *     `member-connection-scope.test.tsx` drives the surface that does.
  *   * NO targets, choices, actions or tokens. Those are foundry-level and stay
  *     on the control-plane router, so the Workflows control is not rendered.
  *   * THE CATALOG IS THE SERVER'S ANSWER. `me/catalog/` returns only what the

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__/member-connection-scope.test.tsx

@@ -0,0 +1,314 @@
+/**
+ * RED: a member's own scope is theirs to set, on screen (bd startsim-sirp6).
+ *
+ * Quinn, 2026-08-27: "if people connect their dropbox, they will expect to be
+ * able to configure what they have access to. some may want root which would be
+ * everything, some may want to configure a subfolder. but our system should
+ * enable and enforce either / both."
+ *
+ * `connections.test.tsx` next door pins that personal mode has no PATCH, and
+ * that was right about what the router served. It is not right about a PERSONAL
+ * connection's config, which is not a pipeline setting: it decides which of the
+ * MEMBER's own files this platform reads. So the member surface grows exactly
+ * ONE write verb — `PATCH connections/me/<id>/config/`, beside `credential/`
+ * rather than on the detail route — and this file pins what that must look like
+ * from the browser.
+ *
+ * THREE THINGS IT IS EASY TO SHIP WITHOUT.
+ *
+ * 1. THE CONTROL HAS TO RENDER. `ConnectionCard` gates Settings on a verb
+ *    EXISTING on the bound api. A member write endpoint that the composer never
+ *    reaches is a change every backend test passes and no member can use, so the
+ *    first assertion here is positive: the control is on the card.
+ * 2. THE CAPABILITY SAVE MUST STAY ABSENT. The narrow verb is narrow. What a
+ *    member's account may DO is still the foundry's, and the picker stays
+ *    informational — which is why the composer must not gate both controls on
+ *    one verb.
+ * 3. THE MEMBER MUST BE TOLD THE WALK RESTARTS, and the SERVER must be what says
+ *    it. This composer refuses to name a vendor and cannot know which fields
+ *    bear the scope; only the connector knows. So the sentence arrives in the
+ *    response and is rendered verbatim.
+ */
+import * as React from 'react';
+import { render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ConnectionsPage } from '../components/pages/ConnectionsPage';
+import { CredentialSchemaForm } from '../components/CredentialSchemaForm';
+import type { MemberConnectionsApi } from '../components/pages/types';
+import { connectionsMe } from '../api/connections';
+import { setApiBase, setAuthTokenProvider } from '../api/_fetch';
+
+/**
+ * A connector whose config IS somebody's privacy boundary: a folder, a switch
+ * that widens it, and a claim on the widest setting of all.
+ *
+ * Not Dropbox. This composer knows about FIELDS and nothing about vendors, so a
+ * fixture that named one would be asserting Dropbox rather than the framework.
+ */
+const SCOPE_FIELDS = [
+  {
+    key: 'folder', label: 'Folder', type: 'string', required: false,
+    help: 'Leave blank for everything', placeholder: '', pattern: null, options: null,
+    default: '', write_only: false, mask: 'none', docs_url: '',
+  },
+  {
+    key: 'recursive', label: 'Include sub-folders', type: 'boolean', required: false,
+    help: 'Off by default', placeholder: '', pattern: null, options: null,
+    default: false, write_only: false, mask: 'none', docs_url: '',
+  },
+  {
+    key: 'whole_account_acknowledged_by', label: 'Whole-account read claimed by',
+    type: 'acknowledgement', required: false, help: 'Required to read everything',
+    placeholder: '', pattern: null, options: null, default: null,
+    write_only: false, mask: 'none', docs_url: '',
+  },
+];
+
+const MEMBER_CATALOG = {
+  results: [
+    {
+      key: 'filesvendor', name: 'File Vendor', description: 'Files', logo_url: '',
+      docs_url: '', capabilities: ['poll'], auth_mode: 'api_key',
+      credential_schema: {
+        version: 1,
+        fields: [{
+          key: 'api_key', label: 'API key', type: 'secret', required: true, help: '',
+          placeholder: '', pattern: null, options: null, default: null,
+          write_only: true, mask: 'last4', docs_url: '',
+        }],
+      },
+      config_schema: { version: 1, fields: SCOPE_FIELDS },
+      record_types: [], supports_webhooks: false,
+      availability: { available: true, reason: '' },
+    },
+  ],
+};
+
+const MY_CONNECTIONS = {
+  results: [
+    {
+      id: 'm1', public_id: 'mpub1', name: 'My files', connector_key: 'filesvendor',
+      connector_name: 'File Vendor', external_account_id: '',
+      account_label: 'me@example.com', capabilities_enabled: ['poll'],
+      config: { folder: '/Contracts', recursive: false }, status: 'connected',
+      health: 'ok', auth_mode: 'api_key',
+    },
+  ],
+  permissions: { view: true, manage: true, issue_tokens: false },
+};
+
+function stubMemberApi(overrides: Partial<MemberConnectionsApi> = {}): MemberConnectionsApi {
+  return {
+    connectorCatalog: vi.fn().mockResolvedValue(MEMBER_CATALOG),
+    connections: vi.fn().mockResolvedValue(MY_CONNECTIONS),
+    connect: vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]),
+    checkConnection: vi.fn().mockResolvedValue({ ok: true, account_label: '', detail: 'ok' }),
+    rotateCredential: vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]),
+    disconnect: vi.fn().mockResolvedValue(undefined),
+    connectionRuns: vi.fn().mockResolvedValue({ results: [] }),
+    updateConnectionConfig: vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]),
+    ...overrides,
+  } as MemberConnectionsApi;
+}
+
+async function myCard(api: MemberConnectionsApi = stubMemberApi()) {
+  render(<ConnectionsPage mode="personal" api={api} />);
+  const card = await screen.findByText('My files');
+  return (card.closest('div[data-connection]') ?? card.parentElement!) as HTMLElement;
+}
+
+// --------------------------------------------------------------------------
+//  the control exists, and it is the narrow one
+// --------------------------------------------------------------------------
+
+describe('the member card can change its own scope', () => {
+  it('offers Settings on a connector that declares config fields', async () => {
+    const section = await myCard();
+    expect(
+      within(section).getByRole('button', { name: /Settings/i }),
+    ).toBeInTheDocument();
+  });
+
+  it('still offers no Save beside the capability picker', async () => {
+    // The verb is narrow ON PURPOSE. What a member's account may DO stays the
+    // foundry's, so gating both controls on one verb would hand back exactly the
+    // decision this change did not make.
+    const section = await myCard();
+    expect(within(section).queryByRole('button', { name: /^Save$/i })).toBeNull();
+    expect(
+      within(section).getByText(/Ask an admin to change what this account may do/i),
+    ).toBeInTheDocument();
+  });
+
+  it('saves the fields the member changed, and nothing else', async () => {
+    const updateConnectionConfig = vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]);
+    const section = await myCard(stubMemberApi({ updateConnectionConfig }));
+
+    await userEvent.click(within(section).getByRole('button', { name: /Settings/i }));
+    await userEvent.clear(within(section).getByLabelText(/^Folder$/i));
+    await userEvent.type(within(section).getByLabelText(/^Folder$/i), '/Invoices');
+    await userEvent.click(within(section).getByRole('button', { name: /Save settings/i }));
+
+    await waitFor(() => expect(updateConnectionConfig).toHaveBeenCalled());
+    expect(updateConnectionConfig.mock.calls[0]).toEqual(['m1', { folder: '/Invoices' }]);
+  });
+
+  it('sends a real boolean when a switch is turned ON', async () => {
+    // `bool("false")` is `true`. A switch that travels as a string is the whole
+    // reason `type` exists on a field spec.
+    const updateConnectionConfig = vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]);
+    const section = await myCard(stubMemberApi({ updateConnectionConfig }));
+
+    await userEvent.click(within(section).getByRole('button', { name: /Settings/i }));
+    await userEvent.click(within(section).getByLabelText(/Include sub-folders/i));
+    await userEvent.click(within(section).getByRole('button', { name: /Save settings/i }));
+
+    await waitFor(() => expect(updateConnectionConfig).toHaveBeenCalled());
+    expect(updateConnectionConfig.mock.calls[0][1]).toEqual({ recursive: true });
+  });
+
+  it('sends a real boolean when a switch is turned OFF', async () => {
+    // Against a MERGING api, a client that drops falsy values makes the off
+    // position literally unreachable — for a scope switch that is the narrow
+    // setting nobody can get back to.
+    const updateConnectionConfig = vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]);
+    const api = stubMemberApi({
+      updateConnectionConfig,
+      connections: vi.fn().mockResolvedValue({
+        ...MY_CONNECTIONS,
+        results: [{
+          ...MY_CONNECTIONS.results[0],
+          config: { folder: '/Contracts', recursive: true },
+        }],
+      }),
+    });
+    const section = await myCard(api);
+
+    await userEvent.click(within(section).getByRole('button', { name: /Settings/i }));
+    await userEvent.click(within(section).getByLabelText(/Include sub-folders/i));
+    await userEvent.click(within(section).getByRole('button', { name: /Save settings/i }));
+
+    await waitFor(() => expect(updateConnectionConfig).toHaveBeenCalled());
+    expect(updateConnectionConfig.mock.calls[0][1]).toEqual({ recursive: false });
+  });
+});
+
+// --------------------------------------------------------------------------
+//  what the server says, the member reads
+// --------------------------------------------------------------------------
+
+describe('the member is told what the change costs', () => {
+  it('renders the notices the SERVER returned, verbatim', async () => {
+    const sentence =
+      'Changing what this connection covers restarts the walk: the next run '
+      + 're-reads this account from the beginning.';
+    const updateConnectionConfig = vi.fn().mockResolvedValue({
+      ...MY_CONNECTIONS.results[0], notices: [sentence],
+    });
+    const section = await myCard(stubMemberApi({ updateConnectionConfig }));
+
+    await userEvent.click(within(section).getByRole('button', { name: /Settings/i }));
+    await userEvent.click(within(section).getByLabelText(/Include sub-folders/i));
+    await userEvent.click(within(section).getByRole('button', { name: /Save settings/i }));
+
+    await waitFor(() => expect(screen.getByText(sentence)).toBeInTheDocument());
+  });
+
+  it('says nothing extra when the server said nothing', async () => {
+    const section = await myCard();
+    await userEvent.click(within(section).getByRole('button', { name: /Settings/i }));
+    await userEvent.click(within(section).getByLabelText(/Include sub-folders/i));
+    await userEvent.click(within(section).getByRole('button', { name: /Save settings/i }));
+    await waitFor(() =>
+      expect(within(section).getByText(/Settings saved/i)).toBeInTheDocument());
+    expect(within(section).queryByText(/from the beginning/i)).toBeNull();
+  });
+});
+
+// --------------------------------------------------------------------------
+//  an acknowledgement is a control, and it shows who claimed it
+// --------------------------------------------------------------------------
+
+describe('CredentialSchemaForm renders an acknowledgement as consent', () => {
+  function renderAck(stored: unknown, onChange = vi.fn()) {
+    render(
+      <CredentialSchemaForm
+        fields={SCOPE_FIELDS}
+        values={{ whole_account_acknowledged_by: stored }}
+        onChange={onChange}
+      />,
+    );
+    return onChange;
+  }
+
+  it('is a checkbox, not a box to type somebody’s name into', () => {
+    renderAck('');
+    const control = screen.getByLabelText(/Whole-account read claimed by/i);
+    expect(control).toHaveAttribute('type', 'checkbox');
+    expect((control as HTMLInputElement).checked).toBe(false);
+  });
+
+  it('emits a boolean, because the SERVER writes who and when', () => {
+    const onChange = renderAck('');
+    return userEvent.click(screen.getByLabelText(/Whole-account read claimed by/i)).then(() => {
+      expect(onChange).toHaveBeenCalledWith('whole_account_acknowledged_by', true);
+    });
+  });
+
+  it('shows the recorded attribution once somebody has claimed it', () => {
+    // A control that records nothing would be worse than the text box it
+    // replaced. The record has to be READABLE, or nobody can check it.
+    renderAck('dana.reed@example.com on 2026-08-27T09:00:00Z');
+    const control = screen.getByLabelText(/Whole-account read claimed by/i) as HTMLInputElement;
+    expect(control.checked).toBe(true);
+    expect(screen.getByText(/dana\.reed@example\.com/)).toBeInTheDocument();
+    expect(screen.getByText(/2026-08-27T09:00:00Z/)).toBeInTheDocument();
+  });
+});
+
+// --------------------------------------------------------------------------
+//  and the client lands on the narrow route
+// --------------------------------------------------------------------------
+
+describe('connectionsMe.updateConnectionConfig', () => {
+  interface Call { url: string; method: string; body: unknown }
+  let calls: Call[] = [];
+
+  beforeEach(() => {
+    calls = [];
+    setApiBase('/api/v1');
+    setAuthTokenProvider(null);
+    vi.stubGlobal('fetch', vi.fn(async (url: string, init: RequestInit = {}) => {
+      calls.push({
+        url: String(url),
+        method: init.method ?? 'GET',
+        body: init.body ? JSON.parse(String(init.body)) : undefined,
+      });
+      return new Response(JSON.stringify({ id: 'm1' }), {
+        status: 200, headers: { 'Content-Type': 'application/json' },
+      });
+    }));
+  });
+
+  afterEach(() => { vi.unstubAllGlobals(); });
+
+  it('PATCHes the CONFIG sub-route, not the detail route', async () => {
+    // Beside `credential/`, and for the same reason it is: a scope change has to
+    // pass the connector's own refusal before it replaces a working setting.
+    // The detail route keeps having no PATCH at all.
+    await connectionsMe.updateConnectionConfig!('abc', { folder: '/Invoices' });
+    expect(calls[0].url).toBe('/api/v1/connections/me/abc/config/');
+    expect(calls[0].method).toBe('PATCH');
+    expect(calls[0].body).toEqual({ config: { folder: '/Invoices' } });
+  });
+
+  it('names no slug, no foundry and no user', async () => {
+    await connectionsMe.updateConnectionConfig!('abc', { folder: '/Invoices' });
+    expect(calls[0].url.startsWith('/api/v1/connections/me/')).toBe(true);
+    expect(calls[0].url).not.toMatch(/[?&]/);
+    expect(JSON.stringify(calls[0].body)).not.toMatch(
+      /slug|foundry|tenant|company|owner|user_id/i);
+  });
+});

package/src/api/connections.ts

@@ -18,11 +18,18 @@
  * token in flight decides which foundry answers, and nothing here can override
  * that.
  *
- * WHAT IS ABSENT IS ALSO THE CONTRACT. There is no `updateConnection` because
- * `MyConnectionDetailView` serves GET and DELETE only; no choices, targets,
- * actions or `ConnectionToken`s because those are foundry-level and stay
- * owner-exclusive on the control-plane router. Adding one here would be a client
- * for a route that does not exist.
+ * WHAT IS ABSENT IS ALSO THE CONTRACT. There is still no `updateConnection`:
+ * `MyConnectionDetailView` serves GET and DELETE only, so a card's name and what
+ * it may DO stay with the foundry. No choices, targets, actions or
+ * `ConnectionToken`s either — those are foundry-level and owner-exclusive on the
+ * control-plane router. Adding one here would be a client for a route that does
+ * not exist.
+ *
+ * `updateConnectionConfig` is the ONE write verb that was added (bd
+ * startsim-sfms2), and it points at `me/<id>/config/` rather than at the detail
+ * route for the same reason `rotateCredential` points at `credential/`: a change
+ * that has to pass a gate gets its own route instead of a field on a general
+ * PATCH.
  *
  * WHERE IT POINTS. Through `request()`, so `setApiBase` and
  * `setAuthTokenProvider` apply: a tenant app points the base at its own
@@ -155,6 +162,37 @@ export const connectionsMe: MemberConnectionsApi = {
     });
   },
 
+  /**
+   * CHANGE THE SETTINGS OF MY OWN CARD (bd startsim-sfms2).
+   *
+   * The folder a Dropbox connection reads, and whether it recurses. On a
+   * personal connection that is not a pipeline setting — it is which of the
+   * member's own files this platform is allowed to see — so it is theirs to set,
+   * and the alternative was disconnect + re-consent, which throws a working
+   * token away to change a string.
+   *
+   * A SUB-ROUTE, not a PATCH on the detail view. `credential/` is the precedent
+   * one door down: rotation is not on PATCH either, because a new key has to
+   * pass `check()` before it replaces a working one. A scope change has the same
+   * shape — it must pass the connector's own refusal, and it restarts the walk.
+   *
+   * PARTIAL and MERGING, exactly like `rotateCredential`: send the fields that
+   * changed and the stored values fill in the rest. `null` unsets one. The server
+   * refuses any key the connector does not declare, and refuses any TOP-LEVEL key
+   * that is not `config` — a body naming `capabilities_enabled` is a 400 and not
+   * a silent no-op.
+   *
+   * The response may carry `notices`: sentences the server wrote about what the
+   * change costs. Rendered verbatim, never composed in the browser.
+   */
+  updateConnectionConfig(
+    id: string, config: Record<string, unknown>,
+  ): Promise<Connection> {
+    return request<Connection>(`${BASE}/${id}/config/`, {
+      method: 'PATCH', body: { config },
+    });
+  },
+
   /**
    * DISCONNECT, not delete. One transaction stops the scheduled fetches, revokes
    * every token issued for the account and deletes the stored credential; the

package/src/components/CredentialSchemaForm.tsx

@@ -51,6 +51,9 @@ export interface CredentialSchemaFormProps {
 /** Field types this build renders natively. Anything else becomes text. */
 const NATIVE_TYPES = new Set(['text', 'url', 'email', 'number', 'select', 'textarea']);
 
+/** The server's spelling for a consent record. See `isAcknowledgement`. */
+const ACKNOWLEDGEMENT = 'acknowledgement';
+
 /**
  * A boolean is a CHECKBOX, and this is not a cosmetic preference.
  *
@@ -61,12 +64,37 @@ const NATIVE_TYPES = new Set(['text', 'url', 'email', 'number', 'select', 'texta
  * conversations are stored, and in a text box the way you turn it off is to type
  * the word "false" — which `bool()` reads as ON.
  */
-const BOOLEAN_TYPES = new Set(['boolean', 'checkbox', 'bool']);
+const BOOLEAN_TYPES = new Set(['boolean', 'checkbox', 'bool', ACKNOWLEDGEMENT]);
 
 export function isBoolean(spec: ConnectorFieldSpec): boolean {
   return !isSecret(spec) && BOOLEAN_TYPES.has(String(spec.type || '').toLowerCase());
 }
 
+/**
+ * An ACKNOWLEDGEMENT is a consent record, not a setting (bd startsim-sfms2).
+ *
+ * It marks the fields that say a named human claimed a disclosure that is legal,
+ * large, and much bigger than most people mean — Dropbox's
+ * `whole_account_acknowledged_by`, which gates reading metadata for every file
+ * in somebody's account.
+ *
+ * Two things follow, and both are why it is not merely `boolean`. What the
+ * person DOES is tick a claim, so this emits `true`/`false` and the SERVER
+ * writes `<who> on <when>` from the authenticated caller — there is no box to
+ * type somebody else's name into, and no request body that can attribute a claim
+ * to anyone but its sender. And what the field HOLDS is that attribution, so it
+ * is rendered beside the control: a claim nobody can read is a record in name
+ * only, which is worse than the text box it replaced.
+ */
+export function isAcknowledgement(spec: ConnectorFieldSpec): boolean {
+  return !isSecret(spec) && String(spec.type || '').toLowerCase() === ACKNOWLEDGEMENT;
+}
+
+/** What the server wrote into an acknowledgement, or '' when nobody has claimed it. */
+export function acknowledgedBy(value: unknown): string {
+  return typeof value === 'string' && asBoolean(value) ? value.trim() : '';
+}
+
 /** The spellings of "off" that can arrive from a stored config or a form. */
 export function asBoolean(value: unknown): boolean {
   if (typeof value === 'string') {
@@ -185,6 +213,15 @@ export function CredentialSchemaForm({
               />
             )}
 
+            {/* THE RECORD, beside the control that made it. `who` and `when`
+                are written by the server; nothing here can author or edit them.
+                Rendered because a consent record nobody can read is not one. */}
+            {isAcknowledgement(spec) && acknowledgedBy(stored) ? (
+              <p className={classNames.help ?? 'mt-1 text-xs text-gray-500'}>
+                Claimed by {acknowledgedBy(stored)}
+              </p>
+            ) : null}
+
             {spec.help ? (
               <p className={classNames.help ?? 'mt-1 text-xs text-gray-500'}>{spec.help}</p>
             ) : null}

package/src/components/pages/ConnectionsPage.tsx

@@ -111,6 +111,20 @@ interface BoundApi {
   updateConnection?(id: string, input: {
     name?: string; capabilities_enabled?: string[]; config?: Record<string, unknown>;
   }): Promise<Connection>;
+  /**
+   * SETTINGS ALONE, and separate from `updateConnection` on purpose
+   * (bd startsim-sfms2).
+   *
+   * Both surfaces have it; only the control plane has `updateConnection`. A
+   * personal connection's config is the MEMBER's privacy boundary — which of
+   * their own files this platform reads — while its name and what it may DO are
+   * the foundry's. One verb carrying all three would have made the Settings
+   * control and the capability Save appear together, so opening the first would
+   * have opened the second by accident.
+   */
+  updateConnectionConfig?(
+    id: string, config: Record<string, unknown>,
+  ): Promise<Connection>;
   connectionChoices?(id: string, params?: { kind?: string; cursor?: string }):
     Promise<ConnectionChoicePage>;
   wireTarget?(id: string, input: {
@@ -177,6 +191,12 @@ function bindApi(props: ConnectionsPageProps): BoundApi {
     rotateCredential: (id, credentials) => api.rotateCredential(slug, id, credentials),
     disconnect: (id) => api.disconnect(slug, id),
     updateConnection: (id, input) => api.updateConnection(slug, id, input),
+    // The control plane reaches settings through the same PATCH it reaches
+    // everything else with; the narrow verb is a property of the MEMBER router,
+    // not of the form. Both modes therefore satisfy the same bound signature and
+    // the settings form never learns which surface it is on.
+    updateConnectionConfig: (id, config) =>
+      api.updateConnection(slug, id, { config }),
     connectionChoices: (id, params) => api.connectionChoices(slug, id, params),
     wireTarget: (id, input) => api.wireTarget(slug, id, input),
     confirmTarget: (id, destinationId) => api.confirmTarget(slug, id, destinationId),
@@ -971,7 +991,8 @@ function ConnectionSettingsForm({
   connection: Connection;
   fields: ConnectorFieldSpec[];
   classNames: typeof DEFAULTS;
-  onDone: () => void;
+  /** Handed whatever the SERVER said about the change, so the card can say it. */
+  onDone: (notices: string[]) => void;
 }) {
   const stored = React.useMemo(
     () => (connection.config ?? {}) as Record<string, unknown>,
@@ -1001,8 +1022,15 @@ function ConnectionSettingsForm({
             ? Number(value)
             : value;
       }
-      await api.updateConnection!(connection.id, { config });
-      onDone();
+      const saved = await api.updateConnectionConfig!(connection.id, config);
+      // WHAT THE SERVER WANTS THEM TO KNOW, handed up rather than rendered here.
+      // The live case is a scope change restarting the walk, and this file
+      // cannot work that out: it names no vendor and therefore cannot know which
+      // fields bear the scope. A heuristic on field names would be both a vendor
+      // branch and untestable at the level that matters. Handed to the CARD
+      // because saving closes this panel, and a sentence that unmounts with the
+      // form is one nobody reads.
+      onDone(saved?.notices ?? []);
     } catch (err) {
       setError((err as { message?: string })?.message || 'Those settings were not saved.');
     } finally {
@@ -1055,6 +1083,8 @@ function ConnectionCard({
   const [busy, setBusy] = React.useState('');
   const [error, setError] = React.useState('');
   const [notice, setNotice] = React.useState('');
+  /** Sentences the SERVER wrote about the last settings save. Never composed here. */
+  const [notices, setNotices] = React.useState<string[]>([]);
   const [replacing, setReplacing] = React.useState(false);
   const [settingsOpen, setSettingsOpen] = React.useState(false);
   const [confirmingDisconnect, setConfirmingDisconnect] = React.useState(false);
@@ -1164,8 +1194,16 @@ function ConnectionCard({
                 all, which for Granola means the switch deciding whether verbatim
                 recordings of people's conversations are stored was reachable
                 only by editing the database. `ReplaceKeyForm` already pointed at
-                "the connection's own settings" as if this existed. */}
-            {configFields.length && api.updateConnection ? (
+                "the connection's own settings" as if this existed.
+
+                GATED ON THE SETTINGS VERB, not on the general one (bd
+                startsim-sfms2). The member surface has `updateConnectionConfig`
+                and deliberately not `updateConnection`, because a personal
+                connection's config is the MEMBER's privacy boundary while its
+                name and what it may do stay the foundry's. One gate for both
+                would have made opening this control open the capability Save
+                beside it, which is a decision this change did not make. */}
+            {configFields.length && api.updateConnectionConfig ? (
               <button
                 type="button"
                 className={cn.button}
@@ -1202,7 +1240,12 @@ function ConnectionCard({
           connection={connection}
           fields={configFields}
           classNames={cn}
-          onDone={() => { setSettingsOpen(false); setNotice('Settings saved.'); onChanged(); }}
+          onDone={(said) => {
+            setSettingsOpen(false);
+            setNotice('Settings saved.');
+            setNotices(said);
+            onChanged();
+          }}
         />
       ) : null}
 
@@ -1308,6 +1351,11 @@ function ConnectionCard({
       </CapabilityPicker>
 
       {notice ? <p className={cn.muted}>{notice}</p> : null}
+      {/* WHAT THE CHANGE COSTS, in the server's words. Rendered verbatim: this
+          file names no vendor and cannot know which settings restart a walk. */}
+      {notices.map((said) => (
+        <p key={said} className={cn.muted}>{said}</p>
+      ))}
       {error ? <p className={cn.error} role="alert">{error}</p> : null}
 
       {choices ? (

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/components/pages/types.ts

@@ -29,7 +29,12 @@ export interface ConnectorFieldSpec {
   help?: string;
   placeholder?: string;
   options?: Array<{ value: string; label: string }> | null;
-  default?: string | null;
+  /**
+   * What happens if nobody touches this field. `unknown`, not `string`: a config
+   * schema declares booleans and numbers, and a `default: false` typed as a
+   * string is the same class of lie as a checkbox rendered as a text box.
+   */
+  default?: unknown;
   pattern?: string | null;
   docs_url?: string;
 }
@@ -148,6 +153,16 @@ export interface Connection {
   auth_mode: string;
   check_error?: string;
   last_checked_at?: string | null;
+  /**
+   * WHAT THE SERVER WANTS THE PERSON WHO JUST SAVED TO KNOW. Present on the
+   * response to a config write and NOWHERE else — never stored, never on a GET.
+   *
+   * The live case is a scope change: it restarts the walk, because the connector
+   * discards a sync cursor whose scope no longer matches. This composer refuses
+   * to name a vendor and cannot know which fields bear the scope; only the
+   * connector does, so only the server can say it. Rendered verbatim.
+   */
+  notices?: string[];
 }
 
 /** What to RENDER, never what to allow. The server refuses on its own. */
@@ -389,11 +404,37 @@ export interface MemberConnectionsApi {
     config?: Record<string, unknown>;
     /**
      * Chosen once, at connect time, and not editable afterwards on this
-     * surface — there is no PATCH. The picker on an existing card is therefore
-     * informational, and saying so is the honest rendering of both halves.
+     * surface — the detail route has no PATCH and `config/` accepts nothing
+     * else. The picker on an existing card is therefore informational, and
+     * saying so is the honest rendering of both halves.
      */
     capabilities_enabled?: string[];
   }): Promise<Connection>;
+  /**
+   * CHANGE THE SETTINGS OF A CONNECTION I OWN (bd startsim-sfms2).
+   *
+   * The one write verb this surface grew, and it is narrow on purpose. A
+   * personal connection's config is not a pipeline setting: it names the folder
+   * of somebody's own account this platform may read. Routing that through an
+   * admin makes another person the author of that member's privacy boundary,
+   * and the only re-scope available without it was disconnect + re-consent —
+   * throwing away a working token to change a string.
+   *
+   * NOT `updateConnection`, and the difference is load-bearing: the foundry
+   * verb of that name also carries `name` and `capabilities_enabled`, which stay
+   * the foundry's. A composer that gated both controls on one verb would hand
+   * back a decision this change did not make.
+   *
+   * PARTIAL and MERGING: send the fields that changed. `null` unsets one. The
+   * server refuses any key the connector does not declare.
+   *
+   * Optional so an app pinned to an older `@startsimpli/api` keeps
+   * type-checking; the card renders the Settings control only when the verb is
+   * present, so a stale client degrades to no control rather than a dead button.
+   */
+  updateConnectionConfig?(
+    id: string, config: Record<string, unknown>,
+  ): Promise<Connection>;
   checkConnection(id: string): Promise<{
     ok: boolean; account_label: string; detail: string;
   }>;

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