@startsimpli/integrations 0.2.26 → 0.2.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "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-document-lookup.test.tsx

@@ -0,0 +1,319 @@
+/**
+ * OPENING ONE RECORD (bd startsim-4s4um RED / startsim-2lt8y GREEN).
+ *
+ * REPORTED, with a live URL:
+ * `https://tandem.ai.startsimpli.com/library?doc=5ab48b58-8573-4114-b408-215dd0eaf5d7`
+ * renders no document.
+ *
+ * WHAT THE TENANT ACTUALLY DOES, read out of
+ * `start-simpli-api/tenant-starter/apps/api/{views,filters}.py` @ origin/main
+ * rather than assumed:
+ *
+ *   - `/api/v1/entities/<id>/` is a real DRF detail route. It answers the ONE
+ *     row, or 404 when the row is absent for this reader — the read gate makes a
+ *     forbidden row ABSENT rather than refused, deliberately.
+ *   - `/api/v1/entities/` applies `?type=` plus a fixed vocabulary
+ *     (`search`, `source`, `party`, `occurred_after`, `occurred_before`,
+ *     `related_*`, `order`) and `attr.*`. `_note_unknown` sweeps EVERY OTHER
+ *     KEY into `ignored_filters` and returns the page unnarrowed. `id` is not in
+ *     that vocabulary, which is why `?id=<uuid>` comes back with count 180.
+ *
+ * SO THE FAKE BELOW IGNORES UNKNOWN PARAMETERS RATHER THAN ERRORING ON THEM,
+ * and that is the whole point of writing a new one instead of reaching for
+ * `createFixtureCorpusHttp`: that fixture applies `?search=` when a backend is
+ * named and never reports `ignored_filters`, so a lookup expressed as a filter
+ * would come back plausibly narrowed there. A fake that answers an unsupported
+ * filter with `[]` — or with a filtered page — makes this suite green while the
+ * deployed Library stays blank, which is the exact trap this bead names.
+ *
+ * WHAT IS NOT THE BUG, established before any of this was written. The DEPLOYED
+ * bundle on tandem.ai.startsimpli.com already asks the detail route:
+ *
+ *     getDocument(e){let[a,r]=await Promise.all([
+ *       t.get(`${m}/${encodeURIComponent(e)}`),f()]);...}
+ *
+ * and that slash-less path resolves — `curl` returns 401 with
+ * `allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS`, the detail route's own verb
+ * set, not a redirect and not the list's. The request shape is right. What is
+ * missing is everything that happens when it does not come back: the client
+ * accepts whatever it is handed without checking it is the record it asked for,
+ * and the composer turns every failure into an empty screen.
+ */
+import { describe, expect, it } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+
+import { LibraryPage } from '../components/pages/LibraryPage';
+import { createCorpusApi } from '../corpus/client';
+import type { CorpusHttp } from '../corpus/client';
+import type { TenantEntity } from '../corpus/entities';
+import type { CorpusScope } from '../corpus/types';
+
+const SCOPE: CorpusScope = { orgId: 'org_tandem' };
+
+/** The record the user deep-linked, live, when they reported this. */
+const OPENED = '5ab48b58-8573-4114-b408-215dd0eaf5d7';
+/** A well-formed id for a row that is simply not there. */
+const ABSENT = '00000000-0000-4000-8000-000000000000';
+
+function document(id: string, title: string, index: number): TenantEntity {
+  return {
+    id,
+    entity_type: 'source_document',
+    external_id: `granola:${id}`,
+    name: title,
+    org_id: SCOPE.orgId,
+    created_at: `2026-08-${String((index % 27) + 1).padStart(2, '0')}T10:00:00Z`,
+    data: {
+      source: 'granola',
+      title,
+      summary: `Summary of ${title}.`,
+      occurred_at: `2026-08-${String((index % 27) + 1).padStart(2, '0')}T09:00:00Z`,
+    },
+  };
+}
+
+/**
+ * A corpus the size of the reported one, with the deep-linked record buried
+ * where the composer's on-page shortcut cannot reach it.
+ *
+ * THE POSITION MATTERS. The record is 100 rows in, so page one does not contain
+ * it and `documents.find(...)` misses — which is precisely the state the
+ * reported URL lands in and the only state where the lookup is exercised at all.
+ */
+const CORPUS: TenantEntity[] = Array.from({ length: 180 }, (_, index) =>
+  index === 100
+    ? document(OPENED, 'Tandem <> Obwb quarterly review', index)
+    : document(`doc-${index}`, `Record ${index}`, index),
+);
+
+/** Parameters this tenant recognises on `/entities/`. Everything else is ignored. */
+const HONOURED = new Set([
+  'search', 'source', 'party', 'occurred_after', 'occurred_before',
+  'related_to', 'related_via', 'related_direction', 'related_depth', 'order',
+]);
+const RESERVED = new Set(['page', 'page_size', 'format', 'type']);
+
+interface Recorded {
+  path: string;
+  params: Record<string, unknown>;
+}
+
+/**
+ * The tenant, as the tenant is.
+ *
+ * `detailStatus` stands in for the read gate and the session: the tenant answers
+ * an absent row with 404 and an expired bearer with 401, and those are different
+ * facts that must not collapse into the same screen.
+ */
+function tenantHttp(options: {
+  entities?: TenantEntity[];
+  pageSize?: number;
+  detailStatus?: number;
+} = {}) {
+  const rows = options.entities ?? CORPUS;
+  const pageSize = options.pageSize ?? 20;
+  const requests: Recorded[] = [];
+
+  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: 0, next: null, previous: null, results: [] } as T;
+      }
+      if (path.includes('connections')) {
+        return { count: 0, next: null, previous: null, results: [] } as T;
+      }
+      if (!path.includes('entities')) {
+        throw Object.assign(new Error(`${path} responded 404`), { status: 404 });
+      }
+
+      // BOTH SPELLINGS OF THE DETAIL ROUTE, because both were measured to
+      // resolve on the live tenant. A fake that insisted on the trailing slash
+      // would manufacture evidence for a path change the wire does not ask for.
+      const detail = /entities\/([^/?]+)\/?$/.exec(path)?.[1];
+      if (detail) {
+        if (options.detailStatus) {
+          throw Object.assign(new Error(`${path} responded ${options.detailStatus}`), {
+            status: options.detailStatus,
+          });
+        }
+        const found = rows.find((row) => String(row.id) === decodeURIComponent(detail));
+        // ABSENT, NOT REFUSED — `readable_types_q` / `readable_rows_q` narrow the
+        // queryset, so a row this reader may not see 404s exactly like one that
+        // was never written.
+        if (!found) throw Object.assign(new Error(`${path} responded 404`), { status: 404 });
+        return found as T;
+      }
+
+      // The LIST. `?type=` narrows; every other key is swept into
+      // `ignored_filters` and the page comes back exactly as wide as it was.
+      const type = params.type ? String(params.type) : '';
+      const matching = type ? rows.filter((row) => row.entity_type === type) : rows;
+      const size = Number(params.page_size ?? pageSize) || pageSize;
+      const page = Number(params.page ?? 1) || 1;
+      const start = (page - 1) * size;
+      const applied: string[] = [];
+      const ignored: string[] = [];
+      for (const key of Object.keys(params)) {
+        if (RESERVED.has(key)) continue;
+        (HONOURED.has(key) ? applied : ignored).push(key);
+      }
+      return {
+        count: matching.length,
+        next: start + size < matching.length ? `?page=${page + 1}` : null,
+        previous: page > 1 ? `?page=${page - 1}` : null,
+        results: matching.slice(start, start + size),
+        applied_filters: applied,
+        ignored_filters: ignored,
+      } as T;
+    },
+  };
+
+  return { http, requests };
+}
+
+/**
+ * The tenant as it answers a lookup that was expressed as a FILTER.
+ *
+ * `GET /api/v1/entities/?id=5ab48b58-…` was checked against prod for this epic
+ * and returned 200 with count 180 — the whole corpus, unnarrowed, because `id`
+ * is not a filter this API has. Any client that reaches the entity list instead
+ * of the detail route gets THIS: a page envelope where it expected a row.
+ *
+ * The contract under test is that such a response is a FAILURE, not a document.
+ * Mapping it produces a record with no id and no title that renders as a blank
+ * panel — an arbitrary answer wearing a real record's clothes, which is worse
+ * than an error because nobody can tell it is wrong.
+ */
+function pageEnvelopeHttp() {
+  const { requests } = tenantHttp();
+  const http: CorpusHttp = {
+    async get<T>(path: string, init?: { params?: Record<string, unknown> }): Promise<T> {
+      requests.push({ path, params: init?.params ?? {} });
+      if (path.includes('entities')) {
+        return {
+          count: CORPUS.length,
+          next: '?page=2',
+          previous: null,
+          results: CORPUS.slice(0, 20),
+          ignored_filters: ['id'],
+        } as T;
+      }
+      return { count: 0, next: null, previous: null, results: [] } as T;
+    },
+  };
+  return { http, requests };
+}
+
+function corpusOver(http: CorpusHttp) {
+  return createCorpusApi({ http, scope: SCOPE, supportedFilters: [] });
+}
+
+// ---------------------------------------------------------------------------
+//  the client
+// ---------------------------------------------------------------------------
+
+describe('a document lookup returns THAT document', () => {
+  it('answers with the record that was asked for, not the first of many', async () => {
+    const api = corpusOver(tenantHttp().http);
+    const found = await api.getDocument(OPENED);
+    expect(found.id).toBe(OPENED);
+    expect(found.title).toBe('Tandem <> Obwb quarterly review');
+  });
+
+  it('asks the DETAIL route, and never expresses the id as a filter', async () => {
+    // The distinction the whole bead turns on. `?id=` is swept into
+    // `ignored_filters` by this API, so a lookup spelled that way is handed the
+    // unfiltered corpus and has to guess.
+    const { http, requests } = tenantHttp();
+    await corpusOver(http).getDocument(OPENED);
+
+    const lookup = requests.find((request) => request.path.includes(OPENED));
+    expect(lookup, 'the id belongs in the PATH').toBeTruthy();
+    expect(
+      requests.every((request) => !('id' in request.params)),
+      'no request may carry the id as a query parameter',
+    ).toBe(true);
+  });
+
+  it('refuses a page envelope instead of fabricating a record from it', async () => {
+    // A response that is a LIST is not the record, whatever produced it — an
+    // ignored `?id=`, a proxy that dropped the path segment, a deployment whose
+    // detail route is a list. Mapping it yields id `undefined` and the title
+    // "Untitled unknown record": a blank panel that claims to be the document.
+    const api = corpusOver(pageEnvelopeHttp().http);
+    await expect(api.getDocument(OPENED)).rejects.toMatchObject({ status: 404 });
+  });
+
+  it('surfaces a record that is genuinely absent as not-found', async () => {
+    const api = corpusOver(tenantHttp().http);
+    await expect(api.getDocument(ABSENT)).rejects.toMatchObject({ status: 404 });
+  });
+
+  it('never answers one id with a different record', async () => {
+    const api = corpusOver(tenantHttp().http);
+    const found = await api.getDocument('doc-3');
+    expect(found.id).toBe('doc-3');
+    await expect(api.getDocument(ABSENT)).rejects.toBeTruthy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+//  the screen
+// ---------------------------------------------------------------------------
+
+describe('the Library opens the record it was deep-linked to', () => {
+  it('renders a record that is not on the first page', async () => {
+    const api = corpusOver(tenantHttp().http);
+    render(<LibraryPage api={api} scope={SCOPE} initialDocumentId={OPENED} />);
+
+    expect(
+      await screen.findByRole('region', { name: 'Record detail' }),
+    ).toHaveTextContent('Tandem <> Obwb quarterly review');
+  });
+
+  it('SAYS SO when the record cannot be found, instead of rendering nothing', async () => {
+    // THE REPORTED SYMPTOM. `?doc=<id>` in the address bar, a list on screen,
+    // and no record and no explanation — the composer swallowed the failure into
+    // `setSelected(null)`. A screen that asked for a record and shows neither the
+    // record nor a reason is the one outcome the user cannot act on.
+    const api = corpusOver(tenantHttp().http);
+    render(<LibraryPage api={api} scope={SCOPE} initialDocumentId={ABSENT} />);
+
+    const notice = await screen.findByRole('region', { name: 'Record' });
+    expect(notice).toHaveTextContent(/could not be found/i);
+    expect(notice).toHaveTextContent(new RegExp(ABSENT));
+  });
+
+  it('calls an expired session an expired session, not a missing record', async () => {
+    // "Sign in again" and "that record is gone" send the reader to different
+    // places, and only one of them is true at a time.
+    const api = corpusOver(tenantHttp({ detailStatus: 401 }).http);
+    render(<LibraryPage api={api} scope={SCOPE} initialDocumentId={OPENED} />);
+
+    const notice = await screen.findByRole('region', { name: 'Record' });
+    expect(notice).toHaveTextContent(/session has expired/i);
+    expect(notice).not.toHaveTextContent(/could not be found/i);
+  });
+
+  it('calls a refusal a refusal', async () => {
+    const api = corpusOver(tenantHttp({ detailStatus: 403 }).http);
+    render(<LibraryPage api={api} scope={SCOPE} initialDocumentId={OPENED} />);
+
+    expect(await screen.findByRole('region', { name: 'Record' })).toHaveTextContent(
+      /do not have access/i,
+    );
+  });
+
+  it('lets the reader dismiss the notice and get back to the list', async () => {
+    // Without this the `?doc=` in the URL is a dead end: the panel cannot be
+    // closed because there is no panel, only a message.
+    const api = corpusOver(tenantHttp().http);
+    render(<LibraryPage api={api} scope={SCOPE} initialDocumentId={ABSENT} />);
+
+    const notice = await screen.findByRole('region', { name: 'Record' });
+    expect(within(notice).getByRole('button', { name: /close/i })).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,243 @@
+/**
+ * THE LIBRARY'S SOURCE STRIP MUST LIST THE SOURCES A MEMBER ACTUALLY HAS
+ * (bd startsim-pg8na RED / startsim-bu04n GREEN).
+ *
+ * REPORTED ON THE LIVE TANDEM TENANT, 2026-08-26: the strip showed Granola
+ * ("Failing", 20 syncs in a row failed) and n8n, while the records listed below
+ * it were Fathom and Granola documents, and the member's own Fathom and Dropbox
+ * connections never appeared at all.
+ *
+ * WHERE THE ROWS COME FROM, which the original diagnosis got wrong and which
+ * decides what may be tested here. There is no tenant-local connections table.
+ * `tenant-starter/config/urls.py` routes `api/v1/connections/` to
+ * `ConnectionsView`, whose only job is to forward the caller's already-verified
+ * bearer to CENTRAL's `/api/v1/subtree/connections/` and return the page
+ * envelope untouched ("proxied from central so the call stays same-origin",
+ * bd startsim-768w.38.19). So `listSources()` is already reading central — it is
+ * reading central's SHARED-only surface, and the two facts line up exactly:
+ *
+ *     TENANT  GET /api/v1/connections/   -> granola, n8n
+ *     CENTRAL Connection rows for tandem -> dropbox(owner qosha),
+ *                                           fathom(owner qosha),
+ *                                           granola(SHARED), n8n(SHARED)
+ *
+ * `SubtreeConnectionsView` resolves through `Connection.objects.for_scope(...)`,
+ * which is `owner IS NULL`. Granola and n8n are not stale junk: they are the
+ * foundry's real shared connections, and Granola really is failing. The two
+ * missing cards are missing because the server was never asked for them.
+ *
+ * THE DIVISION OF LABOUR THIS FILE ASSUMES.
+ *
+ *   Server: a member's OWN rows reach this endpoint. That is a union of
+ *           `for_scope(orgs) | for_owner(orgs, request.user)` in central — the
+ *           remedy `SubtreeConnectionsView` names in its own source, bounded to
+ *           the requesting user so the disclosure bd startsim-768w.22.25.11
+ *           closed stays closed. It cannot be done from this package, and it
+ *           must not be done by merging in `/api/v1/connections/me/`: that
+ *           surface's serializer carries `last_checked_at` and NOTHING ELSE of
+ *           the three freshness facts (no `last_synced_at`, no
+ *           `last_attempt_at`, no `consecutive_failures` — see
+ *           `ConnectionSerializer.Meta.fields`), so every personal card built
+ *           from it would report a verified credential as delivered data. That
+ *           is precisely the lie bd startsim-1cow removed.
+ *
+ *   Client: what arrives is rendered honestly. A connection carries an owner or
+ *           it does not and the strip treats both alike; a connection the member
+ *           DISCONNECTED is not a source of the corpus and must stop appearing
+ *           as one.
+ *
+ * The second half is the part that fails today, and it is the "legacy ones
+ * masquerading as sources" the report describes: `disconnect()` deliberately
+ * keeps the card as `status: 'disabled'` ("DISCONNECT, not delete … the card
+ * survives as `disabled`, so the record that this vendor was connected is not
+ * thrown away"), and `listSources()` has no case for that status, so a vendor
+ * nobody is connected to any more falls through and renders next to the live
+ * ones. Not a denylist of connector keys — `status` is data the server writes.
+ */
+import { describe, expect, it } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+
+import { LibraryPage } from '../components/pages/LibraryPage';
+import { createCorpusApi } from '../corpus/client';
+import type { CorpusHttp } from '../corpus/client';
+import { FIXTURE_ORG } from '../corpus/fixtures';
+
+const SCOPE = { orgId: FIXTURE_ORG };
+const EMPTY_PAGE = { count: 0, next: null, previous: null, results: [] };
+
+const NOW = Date.now();
+const ago = (ms: number) => new Date(NOW - ms).toISOString();
+const AN_HOUR_AGO = ago(60 * 60_000);
+const TEN_MINUTES_AGO = ago(10 * 60_000);
+
+/** Every path this adapter asked for, so a widening read cannot pass unnoticed. */
+interface Recorder {
+  http: CorpusHttp;
+  calls: Array<{ path: string; params?: Record<string, unknown> }>;
+}
+
+/**
+ * The WIRE, not the contract — rows go in exactly as central serialises them.
+ * Same convention as `corpus-freshness.test.tsx`, for the same reason: a fixture
+ * must never be more generous than the server that feeds it.
+ */
+function recorderOver(rows: Array<Record<string, unknown>>): Recorder {
+  const calls: Array<{ path: string; params?: Record<string, unknown> }> = [];
+  return {
+    calls,
+    http: {
+      async get<T>(path: string, options?: { params?: Record<string, unknown> }): Promise<T> {
+        calls.push({ path, params: options?.params });
+        if (path.includes('connections')) {
+          return { count: rows.length, next: null, previous: null, results: rows } as T;
+        }
+        return EMPTY_PAGE as T;
+      },
+    },
+  };
+}
+
+function sourcesFrom(rows: Array<Record<string, unknown>>) {
+  const { http } = recorderOver(rows);
+  return createCorpusApi({ http, scope: SCOPE }).listSources();
+}
+
+/** The foundry's shared Granola: real, connected, and genuinely failing. */
+const SHARED_GRANOLA = {
+  id: 'shared-granola',
+  connector_key: 'granola',
+  connector_name: 'Granola',
+  status: 'connected',
+  check_error: '',
+  last_synced_at: null,
+  last_attempt_at: TEN_MINUTES_AGO,
+  last_checked_at: null,
+  consecutive_failures: 20,
+};
+
+/**
+ * The member's OWN Fathom, as central serialises an owned row once the subtree
+ * read includes them. `owner` is the only structural difference, and the strip
+ * must not care: whose account it is decides who may SEE the row, server-side.
+ */
+const MY_FATHOM = {
+  id: 'my-fathom',
+  connector_key: 'fathom',
+  connector_name: 'Fathom',
+  owner: 'qosha@debugg.ai',
+  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,
+};
+
+/** A vendor the member has DISCONNECTED. The card survives; the source does not. */
+const DISCONNECTED_DROPBOX = {
+  id: 'old-dropbox',
+  connector_key: 'dropbox',
+  connector_name: 'Dropbox',
+  owner: 'qosha@debugg.ai',
+  status: 'disabled',
+  check_error: '',
+  last_synced_at: null,
+  last_attempt_at: null,
+  last_checked_at: null,
+  consecutive_failures: 0,
+};
+
+describe('listSources — a personal connection is a source like any other', () => {
+  it('lists the member’s own connection alongside the foundry’s shared ones', async () => {
+    const sources = await sourcesFrom([SHARED_GRANOLA, MY_FATHOM]);
+
+    expect(sources.map((source) => source.source).sort()).toEqual(['fathom', 'granola']);
+  });
+
+  it('keeps a personal connection’s freshness intact rather than flattening it', async () => {
+    const [fathom] = await sourcesFrom([MY_FATHOM]);
+
+    // The whole reason a merge from `/api/v1/connections/me/` is refused: that
+    // payload has no `last_synced_at` at all, so a card built from it could only
+    // ever say "nothing yet" over data that arrived an hour ago.
+    expect(fathom.lastSyncedAt).toBe(AN_HOUR_AGO);
+    expect(fathom.status).toBe('ok');
+    expect(fathom.label).toBe('Fathom');
+  });
+
+  it('reads one connections endpoint and does not widen the read to reach them', async () => {
+    // A single source of truth, stated as a test so a future "just also fetch
+    // everybody's" cannot be added quietly. The bound that actually keeps
+    // bd startsim-768w.22.25.11 closed is server-side; this pins that the client
+    // never asks for more than the member-scoped page it is handed.
+    const recorder = recorderOver([SHARED_GRANOLA, MY_FATHOM]);
+    await createCorpusApi({ http: recorder.http, scope: SCOPE }).listSources();
+
+    const connectionReads = recorder.calls.filter((call) => call.path.includes('connections'));
+    expect(connectionReads).toHaveLength(1);
+    expect(connectionReads[0].path).toBe('api/v1/connections');
+    // No owner, no user, no "all" — nothing that names a principal other than
+    // the bearer the proxy already forwarded.
+    expect(connectionReads[0].params ?? {}).toEqual({});
+  });
+});
+
+describe('listSources — a disconnected vendor is not a source', () => {
+  it('drops a connection the member has disconnected', async () => {
+    const sources = await sourcesFrom([SHARED_GRANOLA, MY_FATHOM, DISCONNECTED_DROPBOX]);
+
+    expect(sources.map((source) => source.source).sort()).toEqual(['fathom', 'granola']);
+    expect(sources.some((source) => source.source === 'dropbox')).toBe(false);
+  });
+
+  it('never renders a disconnected vendor as healthy', async () => {
+    const [source] = await sourcesFrom([DISCONNECTED_DROPBOX]);
+
+    // If it is listed at all it must not read as a working source. Today it
+    // falls through every branch and comes back `never` — "Connected, but
+    // nothing has arrived yet" about an account that is not connected.
+    expect(source).toBeUndefined();
+  });
+
+  it('keeps a broken-but-live connection, which is a different thing entirely', async () => {
+    // `needs_reauth` and `error` are still connected accounts with a credential
+    // on file and a member who can fix them. Only the lifecycle-ended row goes.
+    const sources = await sourcesFrom([
+      { ...MY_FATHOM, status: 'needs_reauth', check_error: 'The vendor rejected this key (401).' },
+      SHARED_GRANOLA,
+    ]);
+
+    expect(sources.map((source) => source.source).sort()).toEqual(['fathom', 'granola']);
+    expect(sources.find((source) => source.source === 'fathom')?.status).toBe('error');
+  });
+});
+
+describe('the Library strip, rendered', () => {
+  it('draws a card for the member’s own source and none for the disconnected one', async () => {
+    const { http } = recorderOver([SHARED_GRANOLA, MY_FATHOM, DISCONNECTED_DROPBOX]);
+    const api = createCorpusApi({ http, scope: SCOPE });
+
+    render(<LibraryPage api={api} scope={SCOPE} />);
+
+    // Scoped to the strip itself: `listSources` also feeds the source filter's
+    // options, so an unscoped query would match the same vendor twice and say
+    // nothing about which surface it appeared on.
+    const strip = within(await screen.findByRole('region', { name: 'Source freshness' }));
+    expect(strip.getByText('Fathom')).toBeInTheDocument();
+    expect(strip.getByText('Granola')).toBeInTheDocument();
+    expect(strip.queryByText('Dropbox')).not.toBeInTheDocument();
+  });
+
+  it('does not blame a disconnected vendor in the empty state', async () => {
+    // `EmptyState` names every source whose status is `error`. A vendor nobody
+    // is connected to must not be reported as "failing to sync" — the action
+    // that sentence asks for (go fix the connection) is the wrong action.
+    const { http } = recorderOver([DISCONNECTED_DROPBOX]);
+    const api = createCorpusApi({ http, scope: SCOPE });
+
+    render(<LibraryPage api={api} scope={SCOPE} />);
+
+    expect(await screen.findByText(/Nothing has been pulled in yet/i)).toBeInTheDocument();
+    expect(screen.queryByText(/Dropbox/)).not.toBeInTheDocument();
+  });
+});

package/src/components/pages/LibraryPage.tsx

@@ -85,6 +85,29 @@ function readFailureMessage(err: unknown): string {
   return (err as { message?: string })?.message || 'Could not load the library.';
 }
 
+/**
+ * Why the record the screen was asked to open is not on the screen
+ * (bd startsim-2lt8y).
+ *
+ * FOUR ANSWERS, NOT ONE, and the branch is the point: "sign in again", "you may
+ * not see this", "that record is not here" and "something went wrong" send the
+ * reader to four different places, and only one of them is true at a time.
+ * Calling an expired session a missing record is a different lie from the one
+ * this bead is fixing, not a smaller version of it.
+ *
+ * The id is NAMED because it came out of the address bar. A citation or a
+ * bookmark that no longer resolves is worth being able to quote back to
+ * somebody, and "a record" is not quotable.
+ */
+function openFailureMessage(err: unknown, id: string): string {
+  const status = (err as { status?: number })?.status;
+  if (status === 404) {
+    return `That record could not be found in this workspace (${id}). It may have been removed, or it may not be one you can see.`;
+  }
+  if (status === 401 || status === 403) return readFailureMessage(err);
+  return (err as { message?: string })?.message || `That record could not be opened (${id}).`;
+}
+
 function formatDate(value: string | null | undefined): string {
   if (!value) return 'No date';
   const at = Date.parse(value);
@@ -160,6 +183,13 @@ export function LibraryPage({
   const [parties, setParties] = React.useState<Party[]>([]);
   const [selectedId, setSelectedId] = React.useState<string | null>(initialDocumentId ?? null);
   const [selected, setSelected] = React.useState<SourceDocument | null>(null);
+  /**
+   * Why the open record is not open. Held separately from `loadError`, which is
+   * about the LIST: a Library that loaded fine and a citation that no longer
+   * resolves are different facts, and blanking the list for the second one would
+   * be a worse answer than the silence this replaces.
+   */
+  const [selectError, setSelectError] = React.useState('');
   const [loading, setLoading] = React.useState(true);
   const [loadError, setLoadError] = React.useState('');
   /**
@@ -216,18 +246,22 @@ export function LibraryPage({
   }, [api, filters, scope]);
 
   React.useEffect(() => {
-    if (!selectedId) { setSelected(null); return; }
+    if (!selectedId) { setSelected(null); setSelectError(''); return; }
     let live = true;
     void (async () => {
       // Prefer the row already on screen; fall back to a fetch so a citation
       // deep-link opens a record that is not on the current page.
       const onPage = documents.find((document) => document.id === selectedId);
-      if (onPage) { setSelected(onPage); return; }
+      if (onPage) { setSelected(onPage); setSelectError(''); return; }
       try {
         const fetched = await api.getDocument(selectedId);
-        if (live) setSelected(fetched);
-      } catch {
-        if (live) setSelected(null);
+        if (live) { setSelected(fetched); setSelectError(''); }
+      } catch (err) {
+        // THE REPORTED BUG (bd startsim-4s4um). This was `setSelected(null)` and
+        // nothing else, so `?doc=<id>` in the address bar produced a Library
+        // with no record and no explanation — the one outcome a reader cannot
+        // act on, and indistinguishable from a page that simply ignored them.
+        if (live) { setSelected(null); setSelectError(openFailureMessage(err, selectedId)); }
       }
     })();
     return () => { live = false; };
@@ -235,6 +269,7 @@ export function LibraryPage({
 
   const select = React.useCallback((id: string | null) => {
     setSelectedId(id);
+    if (!id) setSelectError('');
     onSelectDocument?.(id);
   }, [onSelectDocument]);
 
@@ -459,6 +494,16 @@ export function LibraryPage({
           onFilterByParty={(partyId) => update({ partyId })}
         />
       ) : null}
+
+      {/* Asked for, and not shown — said out loud rather than left blank. */}
+      {!selected && selectError ? (
+        <section className={cn.card} aria-label="Record">
+          <div className="flex items-start justify-between gap-4">
+            <p className={cn.warning} role="alert">{selectError}</p>
+            <button type="button" className={cn.button} onClick={() => select(null)}>Close</button>
+          </div>
+        </section>
+      ) : null}
     </div>
   );
 }

package/src/corpus/client.ts

@@ -292,6 +292,42 @@ function at(value: unknown): string | null {
   return typeof value === 'string' && value.trim() ? value : null;
 }
 
+/**
+ * Connection lifecycle states in which the account is NO LONGER CONNECTED
+ * (bd startsim-bu04n).
+ *
+ * `Connection.Status` is `connected | needs_reauth | error | disabled`, and only
+ * the last one has ended: the member disconnected it. Central's member surface
+ * documents what that leaves behind — "DISCONNECT, not delete. One transaction
+ * stops the scheduled fetches, revokes every token issued for the account and
+ * deletes the stored credential; the card survives as `disabled`, so the record
+ * that this vendor was connected is not thrown away."
+ *
+ * The card surviving is right for the connections screen, where a member manages
+ * it and may reconnect. It is wrong for the Library's source strip, whose whole
+ * question is "where is my corpus coming from, and is it current". A vendor with
+ * no credential and no schedule is not coming from anywhere, and it used to fall
+ * through every branch below to `never` — "Connected, but nothing has arrived
+ * yet" printed about an account that is not connected.
+ *
+ * A STATUS, NOT A VENDOR. This reads the lifecycle field central writes, so a
+ * connector added tomorrow is handled with no code change here. A list of
+ * connector keys would be exactly the per-vendor branch the DB-driven catalog
+ * exists to prevent, and the reported symptom ("it shows old, disconnected
+ * ones") is precisely the symptom such a list would paper over.
+ *
+ * AN UNRECOGNISED STATUS IS KEPT, deliberately. `needs_reauth` and `error` are
+ * live accounts with a credential on file and a member who can fix them; the
+ * failure mode of hiding one of those — a real source silently absent from the
+ * strip — is worse than the failure mode of showing a status this build has not
+ * heard of yet. A new terminal state is added here on purpose, not by default.
+ */
+const RETIRED_CONNECTION_STATUSES: ReadonlySet<string> = new Set(['disabled']);
+
+function isALiveSource(connection: Record<string, unknown>): boolean {
+  return !RETIRED_CONNECTION_STATUSES.has(String(connection.status ?? ''));
+}
+
 /** Rows written in parallel. Small enough not to look like a burst to the tenant. */
 const WRITE_CONCURRENCY = 6;
 
@@ -320,6 +356,38 @@ function appliedFilters(
   return requested.filter((key) => supported.includes(key));
 }
 
+/**
+ * Is this response the ROW that was asked for, or something else wearing a 200?
+ *
+ * Three things are refused, and each of them has been seen answering a
+ * single-record request somewhere: a DRF page (what an ignored `?id=` returns —
+ * verified on the live tenant, 200 with count 180), a body with no id at all,
+ * and a row whose id is somebody else's.
+ */
+function isRecord(value: unknown, id: string): value is TenantEntity {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  // A page is the shape a LIST answers with. It is never one record, whatever
+  // its count happens to be.
+  if (Array.isArray((value as { results?: unknown }).results)) return false;
+  const own = (value as TenantEntity).id;
+  if (own === undefined || own === null || String(own).trim() === '') return false;
+  // Case-insensitively, because a UUID has two legal spellings and the server
+  // answers in its own. Anything else different is a DIFFERENT RECORD, which is
+  // the entire reason this function exists.
+  return String(own).trim().toLowerCase() === String(id).trim().toLowerCase();
+}
+
+/**
+ * The tenant's own word for a row that is not there.
+ *
+ * 404 and not a bespoke error, because the tenant's read gate makes a row this
+ * principal may not see ABSENT rather than refused — so callers get one status
+ * to branch on, and "not found" is already the honest word for both.
+ */
+function notFound(id: string): Error & { status: number } {
+  return Object.assign(new Error(`No record ${id} in this workspace.`), { status: 404 });
+}
+
 export function createCorpusApi(
   options: CreateCorpusApiOptions,
 ): CorpusApi & CommitmentApi & ExtractionRunStore {
@@ -423,11 +491,34 @@ export function createCorpusApi(
       };
     },
 
+    /**
+     * ONE record, by the DETAIL ROUTE — never by a filter (bd startsim-2lt8y).
+     *
+     * `/api/v1/entities/<id>/` is a real route on the tenant and it answers the
+     * one row. The entity LIST has no `id` filter: `EntityQuery._note_unknown`
+     * sweeps every unrecognised parameter into `ignored_filters` and returns the
+     * page exactly as wide as it was, so `?id=<uuid>` comes back 200 with the
+     * whole corpus. A lookup spelled that way cannot fail — it just answers with
+     * somebody else's record.
+     *
+     * WHICH IS WHY THE RESPONSE IS CHECKED. Asking the right route is not the
+     * same as being answered by it: a proxy that drops the path segment, a
+     * deployment whose detail route lists, an `?id=` that got ignored upstream —
+     * all hand back a DRF page where a row was expected, and `toSourceDocument`
+     * will map it without complaint into a document with the id `undefined` and
+     * the title "Untitled unknown record". That renders as a blank panel that
+     * claims to be the record, which is worse than an error because nobody
+     * downstream can tell it is wrong. So a response that is not the row that
+     * was asked for is a 404, reported the same way the tenant reports an absent
+     * row — the read gate makes a forbidden row ABSENT rather than refused, so
+     * "not found" is already the honest word for both.
+     */
     async getDocument(id) {
       const [entity, byRecord] = await Promise.all([
         http.get<TenantEntity>(`${entities}/${encodeURIComponent(id)}`),
         participantGraph(),
       ]);
+      if (!isRecord(entity, id)) throw notFound(id);
       return toSourceDocument(entity, scope, sourceLabels, byRecord.get(String(entity.id)) ?? []);
     },
 
@@ -446,14 +537,6 @@ export function createCorpusApi(
       };
     },
 
-    /**
-     * Freshness per SOURCE, assembled from the connections the tenant has.
-     *
-     * It reads the connections API rather than the documents, because "Dropbox
-     * has not synced since Tuesday" is a true and useful statement even when
-     * Dropbox has contributed zero documents — and a count derived from the
-     * corpus alone can never say it.
-     */
     /**
      * The tracking surface's read (bd startsim-768w.38.25).
      *
@@ -557,6 +640,41 @@ export function createCorpusApi(
       return durable as ExtractionRun;
     },
 
+    /**
+     * Freshness per SOURCE, assembled from the connections behind this workspace.
+     *
+     * It reads the connections API rather than the documents, because "Dropbox
+     * has not synced since Tuesday" is a true and useful statement even when
+     * Dropbox has contributed zero documents — and a count derived from the
+     * corpus alone can never say it.
+     *
+     * WHERE THE ROWS ACTUALLY COME FROM (bd startsim-bu04n), because the name of
+     * the default path invites the wrong guess. `api/v1/connections` on a tenant
+     * fork is NOT a tenant table: `tenant-starter`'s `ConnectionsView` forwards
+     * the caller's already-verified bearer to central's
+     * `/api/v1/subtree/connections/` and returns the page envelope untouched
+     * (bd startsim-768w.38.19). This read is a central read wearing a
+     * same-origin path, which is why every field below is central's.
+     *
+     * WHICH CONNECTIONS THAT SURFACE HANDS BACK is central's decision and not
+     * this adapter's. `SubtreeConnectionsView` resolves through
+     * `Connection.objects.for_scope(...)` — the foundry's SHARED rows — and a
+     * member's own vendor accounts join the page only when central unions
+     * `for_owner(orgs, request.user)` in, bounded to the requesting user. That
+     * bound is what keeps a colleague's personal connection off this strip
+     * (bd startsim-768w.22.25.11), and it is the reason this adapter must not
+     * reach for `/api/v1/connections/me/` to fill the gap itself: besides
+     * splitting the answer across two servers, that serializer carries
+     * `last_checked_at` and NONE of the other freshness facts, so every personal
+     * card built from it would report a verified credential as delivered data —
+     * 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.
+     */
     async listSources(): Promise<SourceFreshness[]> {
       const [connectionPage, documentPage] = await Promise.all([
         http
@@ -570,7 +688,7 @@ export function createCorpusApi(
       void documentPage; // total count is per-source below; kept for the empty-corpus case
 
       const now = Date.now();
-      return (connectionPage.results ?? []).map((connection) => {
+      return (connectionPage.results ?? []).filter(isALiveSource).map((connection) => {
         const key = String(connection.connector_key ?? connection.connectorKey ?? 'unknown');
         // THREE FACTS, READ SEPARATELY (bd startsim-1cow). This was one `??`
         // chain ending in `last_checked_at`, and central's own view says of that