@startsimpli/integrations 0.2.32 → 0.2.34

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) {
@@ -798,6 +940,11 @@ export function createCorpusApi(
           Number(connection.consecutive_failures ?? connection.consecutiveFailures ?? 0) || 0;
         const documentCount = counts.get(key) ?? null;
         const error = String(connection.check_error ?? connection.checkError ?? '');
+        // WHY THE LAST POLL FAILED — not why the credential did (bd
+        // startsim-ei8gm.2). Both spellings for the same reason the three
+        // timestamps above read both: `@startsimpli/api` camelCases response
+        // keys in the browser and a plain server-side fetch does not.
+        const lastError = String(connection.last_error ?? connection.lastError ?? '');
         const status = connection.status ?? '';
 
         let health: SourceFreshness['status'] = 'ok';
@@ -805,7 +952,7 @@ export function createCorpusApi(
         if (error || status === 'error' || status === 'needs_reauth') {
           health = 'error';
           detail = error || `Connection status is ${String(status)}.`;
-        } else if (failures > 0 || (lastAttemptAt && !lastSyncedAt)) {
+        } else if (failures > 0 || lastError || (lastAttemptAt && !lastSyncedAt)) {
           // IT TRIED AND IT FAILED. Central's view exists partly so that "a card
           // cannot read 'nothing yet' while it is in fact failing on a
           // schedule" — a run that FINISHED while nothing has ever finished well
@@ -813,12 +960,33 @@ export function createCorpusApi(
           // when an older sync did land. Note what does NOT appear in this
           // condition: `lastCheckedAt`. A verified key is not a delivered
           // record, in either direction.
+          //
+          // `lastError` JOINS THAT CONDITION, because the two facts have
+          // different writers: `consecutive_failures` is a counter on the
+          // CONNECTION and the reason is derived from the newest RUN. Central
+          // sends a reason only while that newest run is the failed one, so a
+          // reason with a zero streak behind it is still a source whose last
+          // sync failed — and turning only on the counter reported that as
+          // `stale`, which reads as "nothing to do yet".
           health = 'error';
-          detail =
+          // THE COUNT SURVIVES; IT IS NO LONGER THE WHOLE SENTENCE. "One blip"
+          // and "sixteen days" are different problems, so the streak stays —
+          // what was missing was the half a reader can act on. Composed here
+          // rather than server-side because the streak is a connection field
+          // and the reason is a run field, and central sends them separately
+          // on purpose (bd startsim-1cow: conflating two facts is how a
+          // freshness strip lies).
+          const streak =
             failures > 0
-              ? `${failures} sync${failures === 1 ? '' : 's'} in a row failed` +
-                `${lastSyncedAt ? '' : ' and nothing has arrived yet'}.`
-              : 'A sync ran but nothing arrived.';
+              ? `${failures} sync${failures === 1 ? '' : 's'} in a row failed`
+              : lastError
+                ? 'The last sync failed'
+                : 'A sync ran but nothing arrived';
+          const nothingYet =
+            failures > 0 && !lastSyncedAt ? ' and nothing has arrived yet' : '';
+          // An em dash, not a colon: the server's reason usually contains its
+          // own colons ("[config_error] ...") and a second one reads as a typo.
+          detail = lastError ? `${streak}${nothingYet} — ${lastError}` : `${streak}${nothingYet}.`;
         } else if (!lastSyncedAt) {
           // `never` regardless of `lastCheckedAt`, which is the whole bead.
           health = 'never';
@@ -840,6 +1008,10 @@ export function createCorpusApi(
           consecutiveFailures: failures,
           status: health,
           ...(detail ? { detail } : {}),
+          // Carried separately as well as folded into `detail`, so a surface
+          // that wants the reason on its own — a tooltip, a copy button, the
+          // control plane's card — does not have to unpick a composed sentence.
+          ...(lastError ? { lastError } : {}),
         };
       });
     },

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) {

package/src/corpus/types.ts

@@ -222,6 +222,34 @@ export interface SourceFreshness {
   status: 'ok' | 'stale' | 'error' | 'never';
   /** Why it is not `ok`, in the words the server used. */
   detail?: string;
+  /**
+   * WHY THE LAST SYNC FAILED, in the vendor's own words, and a DIFFERENT FACT
+   * FROM THE CREDENTIAL'S VERDICT (bd startsim-ei8gm.2).
+   *
+   * The Tandem Granola card read "Failing — 20 syncs in a row failed, synced
+   * 16d ago" for sixteen days and nothing said why. It was our own 256 KiB
+   * egress cap — the per-note detail response peaked at 351 KB — which is a
+   * minutes-long diagnosis for anyone who could see the text and sixteen days
+   * for anyone who could not.
+   *
+   * `check_error` COULD NOT HAVE ANSWERED IT, which is why this is its own
+   * field rather than a wider read of that one. `check()` and `poll()` are
+   * different requests: Granola's check asks for `page_size=1` and passes,
+   * while its poll asks for thirty notes with transcripts and aborts. The
+   * credential verified cleanly throughout, so a strip built on `check_error`
+   * alone can count twenty failures and name none of them — and it sends the
+   * reader to re-enter a key that was never the problem.
+   *
+   * Central sends it only while the connection's NEWEST run is the failed one
+   * (`SubtreeConnectionsView._last_failure_reasons`), so it is never last
+   * Tuesday's error quoted over a fix that has already landed. It is SCRUBBED
+   * server-side against that connection's own stored credential plus the
+   * platform app_secret — a vendor can quote our key back inside its own error
+   * body — and a reason that could not be scrubbed arrives as a sentence saying
+   * so rather than as the raw text. Nothing here re-checks it; there is exactly
+   * one redaction path and it is not in the browser.
+   */
+  lastError?: string;
 }
 
 /** DRF PageNumberPagination, which is what the tenant data API speaks. */