@startsimpli/integrations 0.2.31 → 0.2.33

package/src/corpus/client.ts

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

package/src/corpus/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