@startsimpli/integrations 0.2.32 → 0.2.33

package/package.json

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

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

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

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

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

package/src/corpus/client.ts

@@ -34,6 +34,7 @@ import {
   DEFAULT_PARTICIPANT_EDGES,
   DEFAULT_RUN_KEY,
   DEFAULT_TYPE_KEYS,
+  MAX_ID_LIST,
   commitmentToEntity,
   extractionRunToEntity,
   indexParticipants,
@@ -143,17 +144,20 @@ export interface CreateCorpusApiOptions {
   /** Which edge types mean "this party is on this record". Data, not an enum. */
   participantEdges?: readonly string[];
   /**
-   * Bound on the graph read, in PAGES.
+   * Bound on a walked list, in PAGES.
    *
-   * The tenant relationships endpoint has no `?source=` filter today
-   * (`tenant-starter/apps/api/views.py` — see also bd startsim-768w.38.12 for
-   * the same gap on entities), so the edges for a page of documents cannot be
-   * requested directly and the graph is read in bulk and cached. This cap is
-   * what keeps that bounded rather than unbounded: past it, participants simply
-   * stop resolving for the older tail instead of the page hanging.
+   * IT USED TO BE THE ONLY BOUND THERE WAS. This said the tenant relationships
+   * endpoint "has no `?source=` filter today", so the edges for a page of
+   * documents could not be requested directly and the whole edge table was read
+   * in bulk — twenty pages of it — and joined in the browser. That stopped being
+   * true with bd startsim-te3r: `RelationshipQuery` applies `entity__in`, whose
+   * own docstring says what it is for ("a comma list of ids is how a client asks
+   * for the edges of ONE PAGE of records"). The edge read is now narrowed to the
+   * ids on screen (bd startsim-o0o6o.2) and this cap is a backstop on the walk
+   * within that narrowing, and on the party roster read that names the far ends.
    */
   maxGraphPages?: number;
-  /** How long a loaded graph is reused before it is read again. */
+  /** How long a resolved roster and a record's people are reused before re-reading. */
   graphTtlMs?: number;
   /**
    * The `external_id` the singleton extraction-run row lives at. One per
@@ -393,6 +397,26 @@ function notFound(id: string): Error & { status: number } {
   return Object.assign(new Error(`No record ${id} in this workspace.`), { status: 404 });
 }
 
+/**
+ * "I could not tell", which is the third answer and not a variant of the second.
+ *
+ * A read that could not see every candidate row is not evidence of absence, and
+ * `null` in this adapter is a claim of absence that callers ACT on: a sweep
+ * reported as never-run is started again, over the same cursor, by a second
+ * driver. Thrown rather than returned so the existing `ExtractionRun | null`
+ * contract keeps meaning what it says — the two answers a caller may act on are
+ * a run and no run, and everything else is a failure to answer.
+ */
+function undetermined(what: string): Error & { status: number } {
+  return Object.assign(
+    new Error(
+      `Could not determine ${what}: this workspace has more rows of that type ` +
+        `than one page can cover, and no filter on the tenant can name the one row.`,
+    ),
+    { status: 409 },
+  );
+}
+
 export function createCorpusApi(
   options: CreateCorpusApiOptions,
 ): CorpusApi & CommitmentApi & ExtractionRunStore {
@@ -487,43 +511,132 @@ export function createCorpusApi(
   //  the participant graph
   // ---------------------------------------------------------------------
   //
-  // ONE read for a page of documents, not one per document — and cached, so a
-  // screen that lists, opens a record and then asks a question spends it once.
+  // THE EDGES OF THE RECORDS ON SCREEN, AND NO OTHERS (bd startsim-o0o6o.2).
+  // This used to be `readAll(relationships, {})` — every edge in the workspace,
+  // twenty pages of it, on a comment saying the endpoint had no filters. It has
+  // them: `entity__in` takes the ids of one page, bounded at `MAX_ID_LIST`,
+  // which is the shape `RelationshipQuery`'s own docstring says it exists for.
+  //
+  // ONE read for a page of records, not one per record — and cached per record,
+  // so a screen that lists, opens a row and then asks a question spends it once.
   // It FAILS SOFT: a tenant whose relationships endpoint is missing or refused
   // renders exactly what it rendered before this existed, rather than an error
   // where a Library used to be.
-  let graph: { at: number; value: Promise<Map<string, PartyRef[]>> } | null = null;
+  let roster: { at: number; value: Promise<Party[]> } | null = null;
+  const known = new Map<string, { at: number; value: PartyRef[] }>();
 
-  async function loadGraph(): Promise<Map<string, PartyRef[]>> {
-    const empty = new Map<string, PartyRef[]>();
-    if (!resolveParticipants) return empty;
-    try {
-      const partyRows = await readAll<TenantEntity>(entities, { type: types.party });
-      // No parties means no edge can resolve to a name, so the second read is
-      // pure cost — which is the common case on a freshly connected workspace.
-      if (partyRows.length === 0) return empty;
-      const parties = partyRows.map((entity) => toParty(entity, scope));
-      const edges = await readAll<TenantRelationship>(relationships, {});
-      return indexParticipants(edges, parties, participantEdges);
-    } catch {
-      return empty;
+  /**
+   * The people an edge can point AT, read once and reused.
+   *
+   * Still a walked list, because there is no id filter on `/entities/`: the
+   * recognised set is `search`, `source`, `party`, the occurred window,
+   * `related_*`, `order` and `attr.*`, and an unrecognised `id__in` would be
+   * swept into `ignored_filters` and answered with the whole page. It is at
+   * least a TYPED read — `?type=party` is applied server-side — and it is only
+   * reached when the narrowed edge read came back with edges to resolve.
+   */
+  function partyRoster(): Promise<Party[]> {
+    const now = Date.now();
+    if (!roster || now - roster.at > graphTtlMs) {
+      roster = {
+        at: now,
+        value: readAll<TenantEntity>(entities, { type: types.party })
+          .then((rows) => rows.map((entity) => toParty(entity, scope)))
+          .catch(() => []),
+      };
     }
+    return roster.value;
   }
 
-  function participantGraph(): Promise<Map<string, PartyRef[]>> {
+  /**
+   * The edges touching these records, or `null` when the server did not confirm
+   * it narrowed by them.
+   *
+   * `null` IS NOT "NO EDGES", and the difference is the whole point. A fork
+   * without `RelationshipQuery` accepts `entity__in`, names it in
+   * `ignored_filters` and answers with an arbitrary page of the WHOLE edge table
+   * (bd startsim-768w.38.39) — rows that look exactly like a narrow answer and
+   * would put the wrong people, or a fraction of the right ones, on a record.
+   * start-simpli#154 settled what to do with a result the server did not
+   * confirm: do not use it. So this reports that it could not ask, and the
+   * caller renders what it rendered before the join existed.
+   *
+   * `rel_type` rides along unchecked on purpose: it only ever makes the answer
+   * SMALLER, and `indexParticipants` ranks by edge type anyway. A fork that
+   * ignores it pays in PAGES rather than in correctness — a record with many
+   * non-participant edges can push its people onto a second page, and the walk
+   * below follows `next` until it has them.
+   */
+  async function edgesFor(recordIds: string[]): Promise<TenantRelationship[] | null> {
+    const rows: TenantRelationship[] = [];
+    for (let start = 0; start < recordIds.length; start += MAX_ID_LIST) {
+      // CHUNKED, because `_uuid_list` answers a longer list with a 400 rather
+      // than truncating it. Truncating here instead would drop the people off
+      // the tail of a wide page silently, which is the failure being undone.
+      const chunk = recordIds.slice(start, start + MAX_ID_LIST);
+      const extra: Record<string, unknown> = {
+        entity__in: chunk.join(','),
+        page_size: MAX_ID_LIST,
+      };
+      if (participantEdges.length) extra.rel_type = participantEdges.join(',');
+      for (let index = 1; index <= maxGraphPages; index += 1) {
+        const response = await http.get<DrfPage<TenantRelationship> & ServerFilterReport>(
+          relationships,
+          { params: { ...extra, page: index } },
+        );
+        const applied = response.applied_filters ?? response.appliedFilters;
+        if (!applied?.includes('entity__in')) return null;
+        const results = response.results ?? [];
+        rows.push(...results);
+        if (!response.next || results.length === 0) break;
+      }
+    }
+    return rows;
+  }
+
+  async function participantsFor(
+    records: Array<string | number>,
+  ): Promise<Map<string, PartyRef[]>> {
+    const out = new Map<string, PartyRef[]>();
+    if (!resolveParticipants) return out;
     const now = Date.now();
-    if (!graph || now - graph.at > graphTtlMs) {
-      graph = { at: now, value: loadGraph() };
+    const wanted: string[] = [];
+    for (const record of records) {
+      const id = String(record ?? '').trim();
+      if (!id || out.has(id) || wanted.includes(id)) continue;
+      const cached = known.get(id);
+      if (cached && now - cached.at <= graphTtlMs) out.set(id, cached.value);
+      else wanted.push(id);
     }
-    return graph.value;
+    if (wanted.length === 0) return out;
+    try {
+      const edges = await edgesFor(wanted);
+      // Could not ask. Nothing is cached, so the next page asks again rather
+      // than remembering an answer that was never given.
+      if (!edges) return out;
+      const parties = edges.length ? await partyRoster() : [];
+      const indexed = edges.length
+        ? indexParticipants(edges, parties, participantEdges)
+        : new Map<string, PartyRef[]>();
+      for (const id of wanted) {
+        // A record the server confirmed has no participant edges is REMEMBERED
+        // as having none — otherwise every page re-asks for the same silence.
+        const people = indexed.get(id) ?? [];
+        known.set(id, { at: now, value: people });
+        out.set(id, people);
+      }
+    } catch {
+      // The Library renders without its Parties block rather than not at all.
+    }
+    return out;
   }
 
   return {
     async listDocuments(query) {
       const documents = await page<TenantEntity>(types.document, query, (entity) => entity);
-      // Skip the graph entirely for an empty page: an empty corpus should cost
-      // exactly the one request it costs today.
-      const byRecord = documents.results.length ? await participantGraph() : new Map();
+      // Skip the edge read entirely for an empty page: an empty corpus should
+      // cost exactly the one request it costs today.
+      const byRecord = await participantsFor(documents.results.map((entity) => entity.id));
       return {
         ...documents,
         results: documents.results.map((entity) =>
@@ -557,7 +670,10 @@ export function createCorpusApi(
     async getDocument(id) {
       const [entity, byRecord] = await Promise.all([
         http.get<TenantEntity>(`${entities}/${encodeURIComponent(id)}`),
-        participantGraph(),
+        // The edges of ONE record, which is what this screen needs — it no
+        // longer waits on a read of the whole workspace's graph to render a
+        // record it already named (bd startsim-o0o6o.2).
+        participantsFor([id]),
       ]);
       if (!isRecord(entity, id)) throw notFound(id);
       return toSourceDocument(entity, scope, sourceLabels, byRecord.get(String(entity.id)) ?? []);
@@ -569,7 +685,7 @@ export function createCorpusApi(
 
     async listMoneyEvents(query = {}) {
       const events = await page<TenantEntity>(types.moneyEvent, query, (entity) => entity);
-      const byRecord = events.results.length ? await participantGraph() : new Map();
+      const byRecord = await participantsFor(events.results.map((entity) => entity.id));
       return {
         ...events,
         results: events.results.map((entity) =>
@@ -641,21 +757,38 @@ export function createCorpusApi(
     /**
      * The sweep record, read back (bd startsim-768w.38.28).
      *
-     * ONE ROW PER WORKSPACE, at a fixed `external_id`, because the tenant entity
-     * API filters on `?type=` and nothing else — there is no way to ask for "the
-     * newest run", so a row per sweep would mean scanning a list that grows
-     * forever on every poll. A singleton is one deterministic read that never
-     * grows, and the last few sweeps ride along inside it.
+     * ONE ROW PER WORKSPACE, at a fixed `external_id`, because a row per sweep
+     * would mean scanning a list that grows forever on every poll. A singleton
+     * is one read that never grows, and the last few sweeps ride along inside it.
+     *
+     * THE LOOKUP CANNOT BE PUSHED DOWN, AND SAYING SO IS THE POINT. `external_id`
+     * is not among the parameters `/entities/` recognises — `search`, `source`,
+     * `party`, the occurred window, `related_*`, `order`, `attr.*` — so the match
+     * happens here. `attr.external_id` is NOT the way around that: an attribute
+     * nobody declared has no `core_attribute` rows, and `EntityQuery._attribute`
+     * reports the filter as APPLIED before any row matches, so the reply to it is
+     * an empty page that the envelope swears was narrowed. A filter that cannot
+     * be told apart from "no such record" is worse than no filter.
+     *
+     * SO THE BOUND IS WHAT HAS TO BE HONEST (bd startsim-o0o6o.3). This asked for
+     * five rows, because the singleton "is" a singleton — but nothing enforces
+     * that, entities come back `-created_at`, and the singleton is the OLDEST row
+     * of its type because it is rewritten in place. Six `extraction_run` rows and
+     * the read stopped seeing it, returned `null`, and every caller read that as
+     * "no sweep has ever run" — which `startExtractionRun` acts on by starting a
+     * duplicate sweep over a live cursor. It now asks for the widest page the
+     * paginator will serve and, when the row could still be past the end of it,
+     * says it could not tell instead of saying no.
      *
      * FAIL-SOFT ON ABSENCE, NOT ON FAILURE. No run yet is `null`, which is a
-     * fact. A 5xx is thrown, because "we could not reach the workspace" and
-     * "nothing has ever run" are different answers and the screen renders them
-     * differently.
+     * fact. Everything else throws, because "we could not reach the workspace",
+     * "we could not see far enough" and "nothing has ever run" are different
+     * answers and only the last one is safe to act on.
      */
     async readRun() {
       const response = await http
         .get<DrfPage<TenantEntity>>(entities, {
-          params: { type: types.extractionRun, page: 1, page_size: 5 },
+          params: { type: types.extractionRun, page: 1, page_size: MAX_ID_LIST },
         })
         .catch((err: { status?: number }) => {
           // An undeclared type is a 403 from the read gate, and it means exactly
@@ -664,9 +797,18 @@ export function createCorpusApi(
           throw err;
         });
       const row = (response.results ?? []).find(
-        (entity) => String(entity.external_id ?? '') === runKey,
+        // BOTH SPELLINGS, for the reason `ServerFilterReport` documents: the
+        // `@startsimpli/api` fetch wrapper turns `external_id` into `externalId`
+        // on the way in, so a browser-side read matched nothing at ANY page size
+        // and reported "never run" over a workspace with a sweep in it. Every
+        // other reader in `./entities` already takes both; this one did not.
+        (entity) => String(entity.external_id ?? entity.externalId ?? '') === runKey,
       );
-      return row ? toExtractionRun(row) : null;
+      if (row) return toExtractionRun(row);
+      // A page with more behind it did not fail to find the row — it failed to
+      // look at every row, and those are not the same answer.
+      if (response.next) throw undetermined(`whether a sweep has run in this workspace`);
+      return null;
     },
 
     async writeRun(run: ExtractionRun) {

package/src/corpus/entities.ts

@@ -54,6 +54,47 @@ export interface TenantRelationship {
   createdAt?: string | null;
 }
 
+/**
+ * The most ids one `__in` list may carry, and it is the SERVER's number.
+ *
+ * `apps/api/filters.py::MAX_ID_LIST` is 200 and `_uuid_list` answers a longer
+ * list with a 400 rather than truncating it — "bounded so the parameter cannot
+ * become an unpaginated read by another name". A client that sends more does not
+ * get a wider answer, it gets no answer, so the ids of a page are CHUNKED at
+ * this number rather than sent in one request and hoped for.
+ */
+export const MAX_ID_LIST = 200;
+
+/**
+ * Parameters `/api/v1/relationships/` really applies (`RelationshipQuery._FILTERS`).
+ *
+ * Named here rather than inside either the adapter or the fixture, because both
+ * have to agree about it and a second copy is how they stop agreeing. It is a
+ * DESCRIPTION of a deployed server, not a contract this package enforces: a fork
+ * that has not shipped `RelationshipQuery` ignores every one of these, which is
+ * why `applied_filters` is read on the response rather than this list being
+ * trusted.
+ */
+export const RELATIONSHIP_FILTERS: ReadonlySet<string> = new Set([
+  'rel_type',
+  'source',
+  'target',
+  'entity',
+  'source__in',
+  'target__in',
+  'entity__in',
+  'source_type',
+  'target_type',
+]);
+
+/** Consumed by pagination and negotiation, never a filter (`filters.py::_RESERVED`). */
+export const RESERVED_PARAMS: ReadonlySet<string> = new Set([
+  'page',
+  'page_size',
+  'format',
+  'type',
+]);
+
 /**
  * Edges that mean "this party is ON this record", in the order they should be
  * listed. DATA, not a closed set: a tenant that models its own edge passes its

package/src/corpus/fixtures.ts

@@ -42,6 +42,7 @@ import {
   toParty,
   toSourceDocument,
 } from './entities';
+import { MAX_ID_LIST, RELATIONSHIP_FILTERS, RESERVED_PARAMS } from './entities';
 import type { TenantEntity, TenantRelationship } from './entities';
 import { splitSections, stem } from './text';
 import type {
@@ -875,10 +876,22 @@ export function createFixtureCorpusApi(options: FixtureCorpusOptions = {}): Corp
  *     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,
- *     because the tenant has no `?source=` on it either.
+ *   • `page_size` IS honoured, capped at 200. It was written here as ignored,
+ *     citing a `PageNumberPagination` with no `page_size_query_param`, and that
+ *     stopped being true with `TenantPageNumberPagination` (bd
+ *     startsim-768w.38.12): "a client asking for one row to read a count got
+ *     fifty, and a client asking for two hundred to walk a graph got fifty and
+ *     no indication that its request had been overruled". A fixture that keeps
+ *     ignoring it manufactures evidence for a cap the wire does not impose;
+ *   • `/api/v1/relationships/` FILTERS — `rel_type`, `source`, `target`,
+ *     `entity` and the `__in` forms of the last three, bounded at
+ *     `MAX_ID_LIST` ids and reported in `applied_filters`. This too was written
+ *     here as "every edge in the org, unfiltered, because the tenant has no
+ *     `?source=` on it either", and bd startsim-te3r shipped `RelationshipQuery`
+ *     for exactly the read that comment was excusing. An UNRECOGNISED parameter
+ *     is still ignored and the page comes back as wide as it was — that part is
+ *     real, it is what makes an unconfirmed filter dangerous, and it is what
+ *     `applied_filters` exists to let a client detect.
  *
  * Every request is recorded, so "did the browser filter it" and "how many round
  * trips did one screen cost" are both assertable.
@@ -886,7 +899,7 @@ export function createFixtureCorpusApi(options: FixtureCorpusOptions = {}): Corp
 export function createFixtureCorpusHttp(options: {
   entities?: TenantEntity[];
   relationships?: TenantRelationship[];
-  /** Rows per page, matching the tenant's own `PAGE_SIZE`. */
+  /** Rows per page when the caller does not ask, matching the tenant's `PAGE_SIZE`. */
   pageSize?: number;
   /** Endpoints to fail, so the fail-soft paths are exercised. */
   missing?: string[];
@@ -906,15 +919,90 @@ export function createFixtureCorpusHttp(options: {
 
   function slice<T>(rows: T[], params: Record<string, unknown>) {
     const page = Number(params.page ?? 1) || 1;
-    const start = (page - 1) * pageSize;
+    // `TenantPageNumberPagination.page_size_query_param` is `page_size` and its
+    // `max_page_size` is 200 — an OVERRULED request is served at the cap, not
+    // refused, which is the behaviour a client that walks a page has to survive.
+    const asked = Number(params.page_size);
+    const size = Number.isFinite(asked) && asked > 0 ? Math.min(asked, MAX_ID_LIST) : pageSize;
+    const start = (page - 1) * size;
     return {
       count: rows.length,
-      next: start + pageSize < rows.length ? `?page=${page + 1}` : null,
+      next: start + size < rows.length ? `?page=${page + 1}` : null,
       previous: page > 1 ? `?page=${page - 1}` : null,
-      results: rows.slice(start, start + pageSize),
+      results: rows.slice(start, start + size),
     };
   }
 
+  /**
+   * `/api/v1/relationships/`, as `RelationshipQuery.apply` really answers it.
+   *
+   * THE SHAPE THAT MATTERS IS THE ONE IT REFUSES TO NARROW. A parameter this
+   * endpoint does not recognise is swept into `ignored_filters` and the page
+   * comes back exactly as wide as it was — so a fixture that returned `[]` for
+   * an unsupported filter would let a client pass here and read the whole edge
+   * table in production. Every filter below is one the server really applies,
+   * and everything else is really ignored.
+   */
+  function edgeQuery(rows: TenantRelationship[], params: Record<string, unknown>) {
+    const applied: string[] = [];
+    const ignored: string[] = [];
+    const idList = (key: string): Set<string> => {
+      const parts = String(params[key]).split(',').map((part) => part.trim()).filter(Boolean);
+      // `_uuid_list` refuses a longer list with a 400 rather than truncating it,
+      // which is what keeps `__in` from becoming an unpaginated read by another
+      // name — and what a client that chunks its ids has to be tested against.
+      if (parts.length > MAX_ID_LIST) {
+        throw Object.assign(new Error(`${key}: at most ${MAX_ID_LIST} ids`), { status: 400 });
+      }
+      return new Set(parts);
+    };
+    const typeOf = (id: unknown): string =>
+      String(entities.find((entity) => String(entity.id) === String(id))?.entity_type ?? '');
+    let out = rows;
+
+    for (const [key, field] of [['source', 'source'], ['target', 'target']] as const) {
+      if (key in params) {
+        const wanted = String(params[key]);
+        out = out.filter((edge) => String(edge[field]) === wanted);
+        applied.push(key);
+      }
+      const listed = `${key}__in`;
+      if (listed in params) {
+        const wanted = idList(listed);
+        out = out.filter((edge) => wanted.has(String(edge[field])));
+        applied.push(listed);
+      }
+    }
+    if ('entity' in params) {
+      const wanted = String(params.entity);
+      out = out.filter((edge) => String(edge.source) === wanted || String(edge.target) === wanted);
+      applied.push('entity');
+    }
+    if ('entity__in' in params) {
+      const wanted = idList('entity__in');
+      out = out.filter((edge) => wanted.has(String(edge.source)) || wanted.has(String(edge.target)));
+      applied.push('entity__in');
+    }
+    if ('rel_type' in params) {
+      const wanted = new Set(
+        String(params.rel_type).split(',').map((part) => part.trim()).filter(Boolean),
+      );
+      out = out.filter((edge) => wanted.has(String(edge.rel_type ?? edge.relType ?? '')));
+      applied.push('rel_type');
+    }
+    for (const [key, end] of [['source_type', 'source'], ['target_type', 'target']] as const) {
+      if (key in params) {
+        const wanted = String(params[key]);
+        out = out.filter((edge) => typeOf(edge[end]) === wanted);
+        applied.push(key);
+      }
+    }
+    for (const key of Object.keys(params)) {
+      if (!RESERVED_PARAMS.has(key) && !RELATIONSHIP_FILTERS.has(key)) ignored.push(key);
+    }
+    return { rows: out, applied, ignored };
+  }
+
   const http = {
     async get<T>(path: string, init?: { params?: Record<string, unknown> }): Promise<T> {
       const params = init?.params ?? {};
@@ -925,7 +1013,12 @@ export function createFixtureCorpusHttp(options: {
         throw Object.assign(new Error(`${path} responded 404`), { status: 404 });
       }
       if (path.includes('relationships')) {
-        return slice(relationships, params) as T;
+        const query = edgeQuery(relationships, params);
+        return {
+          ...slice(query.rows, params),
+          applied_filters: query.applied.slice().sort(),
+          ignored_filters: query.ignored.slice().sort(),
+        } as T;
       }
       if (path.includes('entities')) {
         const id = /entities\/(.+)$/.exec(path)?.[1];

package/src/corpus/runs.ts

@@ -303,7 +303,16 @@ export async function startExtractionRun(
   const at = now();
   const driver = request.driverId ?? options.driverId ?? defaultDriverId();
 
-  const existing = await deps.runs.readRun().catch(() => null);
+  // NOT `.catch(() => null)`. A store that could not answer is not a store that
+  // said "nothing has ever run", and this is the one place where confusing them
+  // is expensive: the branch below reads `null` as "start a new sweep", so a
+  // transient failure — or a read that could not see far enough (bd
+  // startsim-o0o6o.3) — put a SECOND driver on a live cursor, and two model
+  // calls over one document produce two items identity resolution cannot see are
+  // the same. `readRun` reports absence as `null` and everything else as a
+  // throw, precisely so this caller can tell them apart; swallowing the throw
+  // here threw that distinction away one line after it was made.
+  const existing = await deps.runs.readRun();
 
   if (existing && !COMPLETE.has(existing.status) && !request.restart) {
     if (isLeaseLive(existing, at) && existing.leaseOwner !== driver) {