@startsimpli/integrations 0.1.4 → 0.1.6

package/src/corpus/fixtures.ts

@@ -0,0 +1,726 @@
+/**
+ * A multi-source fixture corpus, shipped as a TESTING UTILITY.
+ *
+ * WHY IT IS IN THE PACKAGE and not in a test file or a harness app: the vitest
+ * suite and the browser harness must exercise the same corpus, or "it renders"
+ * and "it passes" are claims about two different things. Same reasoning as
+ * `startsimpli_connectors.testing.load_fixture` on the backend.
+ *
+ * PROVENANCE. The Granola rows carry the note ids, titles, timestamps,
+ * attendees and transcript lines from
+ * `start-simpli-api/packages/startsimpli-connectors/tests/fixtures/granola/`,
+ * and the money rows carry the ids, amounts and currencies from the `stripe/`
+ * set next to it. Those upstream fixtures are themselves CONSTRUCTED, not
+ * captured — Granola publishes no sandbox — and their README says so; nothing
+ * here is more real than they are.
+ *
+ * THE DROPBOX AND DRIVE ROWS ARE NOT DECORATION. bd startsim-768w.38.6's
+ * standing test is "would this row, badge, filter or empty state still make
+ * sense if the only connected source were Dropbox?". A fixture set containing
+ * only meeting notes cannot answer that question, so this one contains a signed
+ * contract from Dropbox and a pricing sheet from Drive, with their long-form
+ * text in `sections` exactly the way a transcript arrives. Any screen that
+ * renders the Granola rows well and these badly has failed the test visibly.
+ *
+ * THE SECOND ORG IS THE SCOPE TEST. `northwind` holds a document that answers a
+ * `tandem` question BETTER than anything `tandem` owns. That is deliberate: it
+ * is the shape of the leak that matters — not a random foreign row, but the one
+ * a ranker would happily pick if nothing stopped it.
+ *
+ * THE FIXTURES START AT THE STORAGE, NOT AT THE DOMAIN OBJECT. `FIXTURE_TENANT_*`
+ * are raw tenant `Entity` and `Relationship` rows in the shape the corpus
+ * delivery really writes; `FIXTURE_DOCUMENTS` and friends are DERIVED from them
+ * by the real mapper in `./entities`. That inversion is the whole lesson of bd
+ * startsim-768w.38.22: hand-written domain fixtures carried an inline
+ * `participants` array the pipeline never produces, so a green suite proved
+ * nothing about the corpus the product actually renders. If the mapper stops
+ * agreeing with the pipeline, everything downstream of here goes red.
+ */
+import {
+  indexParticipants,
+  toMoneyEvent,
+  toParty,
+  toSourceDocument,
+} from './entities';
+import type { TenantEntity, TenantRelationship } from './entities';
+import type {
+  CorpusApi,
+  CorpusPage,
+  CorpusScope,
+  DocumentQuery,
+  MoneyEvent,
+  Party,
+  PartyRef,
+  SourceDocument,
+  SourceFreshness,
+} from './types';
+
+/** The tenant every fixture document belongs to unless stated otherwise. */
+export const FIXTURE_ORG = 'tandem';
+/** A DIFFERENT customer workspace under the same foundry (bd startsim-768w.34.4). */
+export const FIXTURE_OTHER_ORG = 'northwind';
+
+const OWNER_A = 'usr_dana';
+const OWNER_B = 'usr_sam';
+
+const scope = (orgId: string, ownerSub: string): CorpusScope => ({ orgId, ownerSub });
+
+/** Human names per source key, as an app reads them off the connector catalog. */
+export const FIXTURE_SOURCE_LABELS: Record<string, string> = {
+  granola: 'Granola',
+  dropbox: 'Dropbox',
+  gdrive: 'Google Drive',
+  stripe: 'Stripe',
+};
+
+// ---------------------------------------------------------------------------
+//  THE TENANT'S OWN STORAGE — the shape the pipeline really writes
+// ---------------------------------------------------------------------------
+//
+// EVERYTHING BELOW THIS LINE IS RAW, and everything above the derivation at the
+// bottom is produced from it by the REAL mapper (`./entities`). That is the
+// whole point of this section, and it was added because the previous fixtures
+// were domain objects handed straight to the composers: they carried an inline
+// `participants` array that `declare_canonical()` never writes, so every test
+// passed against a corpus shape production does not produce, and the Library
+// shipped with an empty Parties block on every document the pipeline had ever
+// delivered (bd startsim-768w.38.22).
+//
+// WHAT "REAL" MEANS HERE, checked against the live rehearsal
+// (bd startsim-768w.38.10) and against `startsimpli_connectors.canonical`:
+//
+//   • `data` holds the CANONICAL ATTRIBUTES and nothing else, plus `_origin`.
+//     A document carries `participant_count` — a NUMBER — and no names.
+//   • people are typed EDGES: `authored_by` and `involves` from the document to
+//     a `party`, `billed_to` from a money event to a `party`.
+//   • `external_id` is always `<connector_key>:<vendor id>`.
+//   • a `derived_from` edge exists and points at another DOCUMENT — anything
+//     that treats every edge as a person will put a document in the Parties row.
+//
+// TWO KNOWN DEPARTURES, stated rather than hidden. Entity ids here are readable
+// (`not_1d3tmYTlCICgjy`) where a tenant mints UUIDs — the id FORMAT is opaque to
+// every consumer and readable ids make a failing assertion legible. And these
+// rows carry `org_id`/`owner_sub`, which `EntitySerializer` does not echo today
+// (`tenant-starter/apps/api/views.py`), so on a real tenant `scopeOf` falls back
+// to the caller's scope; keeping them here is what lets the scope-guard suite
+// model a server that lies.
+
+/** The marker the corpus delivery stamps on every pipeline-written row. */
+const ORIGIN = 'central-connector';
+
+/** `<connector_key>:<vendor id>`, exactly as `canonical_external_id()` builds it. */
+const ref = (source: string, vendorId: string) => `${source}:${vendorId}`;
+
+function row(options: {
+  type: string;
+  id: string;
+  source: string;
+  vendorId: string;
+  name?: string;
+  data: Record<string, unknown>;
+  ownerSub: string;
+  createdAt?: string;
+  orgId?: string;
+}): TenantEntity {
+  return {
+    id: options.id,
+    entity_type: options.type,
+    external_id: ref(options.source, options.vendorId),
+    name: options.name ?? '',
+    data: { ...options.data, source: options.source, source_ref: options.vendorId, _origin: ORIGIN },
+    created_at: options.createdAt ?? null,
+    org_id: options.orgId ?? FIXTURE_ORG,
+    owner_sub: options.ownerSub,
+  };
+}
+
+const edge = (relType: string, source: string, target: string): TenantRelationship => ({
+  id: `rel_${relType}_${source}_${target}`,
+  rel_type: relType,
+  source,
+  target,
+});
+
+const GRANOLA_TRANSCRIPT = [
+  'Dana Reed: Morning — let’s start with the connector.',
+  'Sam Ortiz: Sounds good. I pulled the OpenAPI shapes yesterday.',
+  'Dana Reed: The transcript is going on its own entity.',
+  'Sam Ortiz: Agreed — fifty transcripts a page is not a page.',
+  'Dana Reed: On renewal, Acme want the same rate for another twelve months.',
+  'Sam Ortiz: Then we hold at four thousand a month and cap the seats at forty.',
+].join('\n');
+
+/**
+ * `party` rows. `display_name` rather than `name` inside `data`, because that is
+ * the attribute the canonical party schema declares.
+ */
+export const FIXTURE_TENANT_PARTIES: TenantEntity[] = [
+  row({
+    type: 'party', id: 'party_dana', source: 'granola', vendorId: 'dana.reed@example.com',
+    name: 'Dana Reed', ownerSub: OWNER_A,
+    data: { subtype: 'person', display_name: 'Dana Reed', email: 'dana.reed@example.com', domain: 'example.com' },
+  }),
+  row({
+    type: 'party', id: 'party_sam', source: 'granola', vendorId: 'sam.ortiz@example.com',
+    name: 'Sam Ortiz', ownerSub: OWNER_A,
+    data: { subtype: 'person', display_name: 'Sam Ortiz', email: 'sam.ortiz@example.com', domain: 'example.com' },
+  }),
+  row({
+    type: 'party', id: 'party_kim', source: 'granola', vendorId: 'kim.li@example.com',
+    name: 'Kim Li', ownerSub: OWNER_A,
+    data: { subtype: 'person', display_name: 'Kim Li', email: 'kim.li@example.com', domain: 'example.com' },
+  }),
+  row({
+    type: 'party', id: 'party_acme', source: 'stripe', vendorId: 'cus_RedSuite01Acme',
+    name: 'Acme Robotics', ownerSub: OWNER_A,
+    data: { subtype: 'company', display_name: 'Acme Robotics', email: 'ada@example.com', domain: 'example.com' },
+  }),
+  row({
+    type: 'party', id: 'party_beta', source: 'stripe', vendorId: 'cus_RedSuite02Beta',
+    name: 'Beta Foods', ownerSub: OWNER_A,
+    data: { subtype: 'company', display_name: 'Beta Foods', email: 'bo@example.com', domain: 'example.com' },
+  }),
+];
+
+/**
+ * `source_document` rows.
+ *
+ * The Dropbox and Drive rows are not decoration. bd startsim-768w.38.6's
+ * standing test is "would this row, badge, filter or empty state still make
+ * sense if the only connected source were Dropbox?", and a fixture set of
+ * meeting notes cannot answer it — so a signed contract and a pricing sheet are
+ * here, with their long-form text under the key their own connector would use.
+ *
+ * The `northwind` row is the SCOPE test: it answers a `tandem` question BETTER
+ * than anything `tandem` owns, which is the shape of the leak that matters.
+ */
+export const FIXTURE_TENANT_DOCUMENTS: TenantEntity[] = [
+  row({
+    type: 'source_document', id: 'not_1d3tmYTlCICgjy', source: 'granola',
+    vendorId: 'not_1d3tmYTlCICgjy', name: 'Acme <> StartSimpli weekly sync',
+    ownerSub: OWNER_A, createdAt: '2026-01-27T16:10:00Z',
+    data: {
+      subtype: 'meeting',
+      title: 'Acme <> StartSimpli weekly sync',
+      summary:
+        'Agreed to ship the connector RED suite first. Acme asked to renew at the same rate for another twelve months.',
+      occurred_at: '2026-01-27T15:30:00Z',
+      url: 'https://notes.granola.ai/d/9f1c2b7e-2a44-4f3e-9a0d-6c1b8e5d4a21',
+      // A COUNT, and no names. This is the whole of what the document knows
+      // about who was there; everyone else is an edge.
+      participant_count: 4,
+      transcript: GRANOLA_TRANSCRIPT,
+    },
+  }),
+  row({
+    type: 'source_document', id: 'not_7Kq2ZbVnRt4aXm', source: 'granola',
+    vendorId: 'not_7Kq2ZbVnRt4aXm', name: 'Design review',
+    ownerSub: OWNER_A, createdAt: '2026-01-26T11:52:00Z',
+    data: {
+      subtype: 'meeting',
+      title: 'Design review',
+      summary:
+        'Reviewed the two-entity split. Note and transcript become separate records so a page of fifty stays a page.',
+      occurred_at: '2026-01-26T11:00:00Z',
+      url: 'https://notes.granola.ai/d/2b7d41ce-8f05-4a19-b3d2-77e4c0a9f118',
+      participant_count: 2,
+    },
+  }),
+  row({
+    // The upstream fixture has `title: null` and no calendar event, so the
+    // canonical row carries NEITHER a title attribute nor a name. A row with no
+    // title is a real row and must still render.
+    type: 'source_document', id: 'not_Pd9wLs3EhY6cQz', source: 'granola',
+    vendorId: 'not_Pd9wLs3EhY6cQz', ownerSub: OWNER_B, createdAt: '2026-01-25T09:40:00Z',
+    data: {
+      subtype: 'meeting',
+      summary: 'Ad-hoc call, no calendar invite.',
+      occurred_at: '2026-01-25T09:15:00Z',
+      participant_count: 1,
+    },
+  }),
+  row({
+    // The transcript was auto-deleted upstream and the summary is empty. A
+    // document with no readable text is the emptiest real row the Library will
+    // ever be handed.
+    type: 'source_document', id: 'not_Xa4mB8vTuN2kRe', source: 'granola',
+    vendorId: 'not_Xa4mB8vTuN2kRe', name: 'Board prep (transcript auto-deleted upstream)',
+    ownerSub: OWNER_A, createdAt: '2026-01-24T08:05:00Z',
+    data: {
+      subtype: 'meeting',
+      title: 'Board prep (transcript auto-deleted upstream)',
+      occurred_at: '2026-01-20T13:00:00Z',
+      participant_count: 1,
+    },
+  }),
+  row({
+    type: 'source_document', id: 'dbx_9812f0', source: 'dropbox', vendorId: 'id:9812f0a4b1',
+    name: 'Acme Robotics — Master Services Agreement (signed)',
+    ownerSub: OWNER_A, createdAt: '2026-02-02T06:00:00Z',
+    data: {
+      subtype: 'file',
+      title: 'Acme Robotics — Master Services Agreement (signed)',
+      summary:
+        'Signed MSA between StartSimpli and Acme Robotics, effective 1 February 2026, initial term twelve months.',
+      occurred_at: '2026-02-01T00:00:00Z',
+      url: 'https://www.dropbox.example/scl/fi/9812f0a4b1/acme-msa-signed.pdf',
+      participant_count: 2,
+      extracted_text: [
+        'MASTER SERVICES AGREEMENT',
+        '1. Term. This Agreement begins on 1 February 2026 and continues for twelve (12) months.',
+        '2. Fees. Customer shall pay USD 4,000 per month, invoiced monthly in advance.',
+        '3. Seats. The subscription covers up to forty (40) named seats.',
+        '4. Renewal. This Agreement renews for successive twelve-month terms unless either party gives sixty (60) days notice.',
+        '5. Termination for convenience requires ninety (90) days written notice.',
+      ].join('\n'),
+    },
+  }),
+  row({
+    type: 'source_document', id: 'gdrive_1QpZ', source: 'gdrive', vendorId: '1QpZv7t9kR',
+    name: 'Rate card 2026', ownerSub: OWNER_A, createdAt: '2026-01-06T07:30:00Z',
+    data: {
+      subtype: 'file',
+      title: 'Rate card 2026',
+      summary:
+        'Standard pricing for 2026. Platform tier USD 4,000 per month up to forty seats; overage USD 90 per seat per month.',
+      occurred_at: '2026-01-05T00:00:00Z',
+      url: 'https://docs.google.example/document/d/1QpZv7t9kR',
+      participant_count: 1,
+      extracted_text:
+        'Platform: USD 4,000/mo (40 seats). Overage: USD 90/seat/mo. Discounts require VP approval above 15%.',
+    },
+  }),
+  row({
+    // ---- A DIFFERENT CUSTOMER WORKSPACE ----
+    // Deliberately the BEST answer to "what did we agree with Acme on renewal":
+    // more specific, more recent, and full of exactly the terms a ranker loves.
+    // Nothing but the scope guard stands between it and a convincing leak.
+    type: 'source_document', id: 'nw_contract_44', source: 'dropbox', vendorId: 'id:nw44a2',
+    name: 'Acme Robotics renewal — Northwind terms (CONFIDENTIAL)',
+    ownerSub: 'usr_northwind', orgId: FIXTURE_OTHER_ORG, createdAt: '2026-02-10T09:00:00Z',
+    data: {
+      subtype: 'file',
+      title: 'Acme Robotics renewal — Northwind terms (CONFIDENTIAL)',
+      summary:
+        'Northwind renewed Acme Robotics at USD 2,750 per month with unlimited seats and a ninety-day out. Do not share outside Northwind.',
+      occurred_at: '2026-02-10T00:00:00Z',
+      participant_count: 1,
+      extracted_text:
+        'Renewal rate USD 2,750/mo. Unlimited seats. Ninety (90) day termination for convenience. Acme renewal signed 2026-02-10.',
+    },
+  }),
+];
+
+/** `money_event` rows — amounts in MINOR units, under the declared attribute. */
+export const FIXTURE_TENANT_MONEY_EVENTS: TenantEntity[] = [
+  row({
+    type: 'money_event', id: 'in_RedSuiteUsd0001', source: 'stripe', vendorId: 'in_RedSuiteUsd0001',
+    name: 'Invoice in_RedSuiteUsd0001', ownerSub: OWNER_A,
+    data: {
+      subtype: 'invoice', amount_minor: 500, currency: 'usd', status: 'paid',
+      occurred_at: '2026-08-01T00:00:00Z',
+      url: 'https://invoice.stripe.example/i/in_RedSuiteUsd0001',
+      description: 'Subscription update proration',
+    },
+  }),
+  row({
+    type: 'money_event', id: 'ch_RedSuiteJpy0001', source: 'stripe', vendorId: 'ch_RedSuiteJpy0001',
+    name: 'Charge ch_RedSuiteJpy0001', ownerSub: OWNER_A,
+    data: {
+      subtype: 'charge', amount_minor: 1500, currency: 'jpy', status: 'refunded',
+      occurred_at: '2026-07-31T00:01:00Z',
+      description: 'Invoice REDSUITE-0001 — refunded in full',
+    },
+  }),
+  row({
+    type: 'money_event', id: 'sub_RedSuite01Acme', source: 'stripe', vendorId: 'sub_RedSuite01Acme',
+    name: 'Subscription sub_RedSuite01Acme', ownerSub: OWNER_A,
+    data: {
+      subtype: 'subscription', amount_minor: 400000, currency: 'usd', status: 'active',
+      occurred_at: '2026-07-31T00:00:00Z',
+      description: 'Platform tier, monthly, forty seats',
+    },
+  }),
+];
+
+/**
+ * The graph. WHERE THE PEOPLE ACTUALLY LIVE.
+ *
+ * The `derived_from` row is deliberate: it is a real canonical edge whose target
+ * is a DOCUMENT, so anything that treats every edge as a person puts a meeting
+ * note in the Parties block and fails here rather than in a browser.
+ */
+export const FIXTURE_TENANT_RELATIONSHIPS: TenantRelationship[] = [
+  edge('authored_by', 'not_1d3tmYTlCICgjy', 'party_dana'),
+  edge('involves', 'not_1d3tmYTlCICgjy', 'party_sam'),
+  edge('involves', 'not_1d3tmYTlCICgjy', 'party_kim'),
+  edge('involves', 'not_1d3tmYTlCICgjy', 'party_acme'),
+  edge('authored_by', 'not_7Kq2ZbVnRt4aXm', 'party_dana'),
+  edge('involves', 'not_7Kq2ZbVnRt4aXm', 'party_sam'),
+  edge('authored_by', 'not_Pd9wLs3EhY6cQz', 'party_dana'),
+  edge('authored_by', 'not_Xa4mB8vTuN2kRe', 'party_dana'),
+  edge('involves', 'dbx_9812f0', 'party_acme'),
+  edge('involves', 'dbx_9812f0', 'party_dana'),
+  edge('involves', 'gdrive_1QpZ', 'party_dana'),
+  edge('involves', 'nw_contract_44', 'party_acme'),
+  edge('derived_from', 'not_1d3tmYTlCICgjy', 'not_7Kq2ZbVnRt4aXm'),
+  edge('billed_to', 'in_RedSuiteUsd0001', 'party_beta'),
+  edge('billed_to', 'ch_RedSuiteJpy0001', 'party_acme'),
+  edge('billed_to', 'sub_RedSuite01Acme', 'party_acme'),
+];
+
+// ---------------------------------------------------------------------------
+//  DERIVED THROUGH THE REAL MAPPER
+// ---------------------------------------------------------------------------
+//
+// Not hand-written domain objects. If `./entities` stops reading the storage the
+// pipeline writes, these go wrong and every suite that consumes them goes red —
+// which is the property that was missing when the Parties block shipped empty.
+
+const FALLBACK_SCOPE = scope(FIXTURE_ORG, OWNER_A);
+
+export const FIXTURE_PARTIES: Party[] = FIXTURE_TENANT_PARTIES.map((entity) =>
+  toParty(entity, FALLBACK_SCOPE),
+);
+
+/** documentId / moneyEventId -> the people on it, resolved from the edges. */
+export const FIXTURE_PARTICIPANTS: Map<string, PartyRef[]> = indexParticipants(
+  FIXTURE_TENANT_RELATIONSHIPS,
+  FIXTURE_PARTIES,
+);
+
+export const FIXTURE_DOCUMENTS: SourceDocument[] = FIXTURE_TENANT_DOCUMENTS.map((entity) =>
+  toSourceDocument(
+    entity,
+    FALLBACK_SCOPE,
+    FIXTURE_SOURCE_LABELS,
+    FIXTURE_PARTICIPANTS.get(String(entity.id)) ?? [],
+  ),
+);
+
+export const FIXTURE_MONEY_EVENTS: MoneyEvent[] = FIXTURE_TENANT_MONEY_EVENTS.map((entity) =>
+  toMoneyEvent(
+    entity,
+    FALLBACK_SCOPE,
+    FIXTURE_SOURCE_LABELS,
+    FIXTURE_PARTICIPANTS.get(String(entity.id)) ?? [],
+  ),
+);
+
+/**
+ * One row per connected source, including one that is broken and one that has
+ * never delivered — because a freshness strip that only ever says "ok" has never
+ * been looked at.
+ */
+export const FIXTURE_SOURCES: SourceFreshness[] = [
+  {
+    source: 'granola',
+    label: 'Granola',
+    documentCount: 4,
+    lastSyncedAt: '2026-08-07T06:00:00Z',
+    status: 'ok',
+  },
+  {
+    source: 'dropbox',
+    label: 'Dropbox',
+    documentCount: 1,
+    lastSyncedAt: '2026-08-02T06:00:00Z',
+    status: 'stale',
+    detail: 'Last sync was more than 26 hours ago.',
+  },
+  {
+    source: 'gdrive',
+    label: 'Google Drive',
+    documentCount: 1,
+    lastSyncedAt: '2026-08-06T07:30:00Z',
+    status: 'error',
+    detail: 'The vendor rejected this key (401). Reconnect Google Drive.',
+  },
+  {
+    source: 'stripe',
+    label: 'Stripe',
+    documentCount: 0,
+    lastSyncedAt: null,
+    status: 'never',
+    detail: 'Connected, but nothing has arrived yet.',
+  },
+];
+
+// ---------------------------------------------------------------------------
+//  a CorpusApi over the fixtures
+// ---------------------------------------------------------------------------
+
+export interface FixtureCorpusOptions {
+  documents?: SourceDocument[];
+  moneyEvents?: MoneyEvent[];
+  parties?: Party[];
+  sources?: SourceFreshness[];
+  /** Page size when the caller does not ask for one. Small, to exercise paging. */
+  defaultPageSize?: number;
+  /**
+   * The scope this "server" enforces. Omit to model a CORRECT server that
+   * scopes every read; set `leakScope` to model a broken one and prove the
+   * client-side guard catches what the server should have.
+   */
+  scope?: CorpusScope;
+  /** Return rows from every org, as an over-broad server would. */
+  leakScope?: boolean;
+  /** Record every query the composers made, for assertions about server-side filtering. */
+  onQuery?: (endpoint: string, query: unknown) => void;
+}
+
+function haystack(document: SourceDocument): string {
+  return [
+    document.title,
+    document.body,
+    ...document.sections.map((section) => section.text),
+    ...document.participants.map((party) => `${party.name} ${party.email ?? ''}`),
+    document.sourceLabel,
+  ]
+    .join(' ')
+    .toLowerCase();
+}
+
+function paginate<T>(rows: T[], page: number, pageSize: number, applied: string[]): CorpusPage<T> {
+  const start = (page - 1) * pageSize;
+  return {
+    count: rows.length,
+    next: start + pageSize < rows.length ? String(page + 1) : null,
+    previous: page > 1 ? String(page - 1) : null,
+    results: rows.slice(start, start + pageSize),
+    appliedFilters: applied,
+  };
+}
+
+/**
+ * A `CorpusApi` that behaves the way the tenant API is SUPPOSED to: it filters
+ * and pages server-side and reports which filters it applied. It is the "server"
+ * in the harness and in the tests, which is what makes both of them a fair test
+ * of a composer that must never filter in the browser.
+ */
+export function createFixtureCorpusApi(options: FixtureCorpusOptions = {}): CorpusApi {
+  const {
+    documents = FIXTURE_DOCUMENTS,
+    moneyEvents = FIXTURE_MONEY_EVENTS,
+    parties = FIXTURE_PARTIES,
+    sources = FIXTURE_SOURCES,
+    defaultPageSize = 5,
+    scope: serverScope,
+    leakScope = false,
+    onQuery,
+  } = options;
+
+  const inScope = <T extends { scope: CorpusScope }>(rows: T[]): T[] => {
+    if (leakScope || !serverScope) return rows;
+    return rows.filter(
+      (row) =>
+        row.scope.orgId === serverScope.orgId &&
+        (!serverScope.ownerSub || row.scope.ownerSub === serverScope.ownerSub),
+    );
+  };
+
+  return {
+    async listDocuments(query: DocumentQuery) {
+      onQuery?.('documents', query);
+      const applied: string[] = [];
+      let rows = inScope(documents);
+
+      if (query.source) {
+        applied.push('source');
+        rows = rows.filter((document) => document.source === query.source);
+      }
+      if (query.partyId) {
+        applied.push('partyId');
+        rows = rows.filter((document) =>
+          document.participants.some((party) => party.id === query.partyId),
+        );
+      }
+      if (query.occurredAfter) {
+        applied.push('occurredAfter');
+        rows = rows.filter((d) => (d.occurredAt ?? '') >= query.occurredAfter!);
+      }
+      if (query.occurredBefore) {
+        applied.push('occurredBefore');
+        rows = rows.filter((d) => (d.occurredAt ?? '') <= query.occurredBefore!);
+      }
+      if (query.search) {
+        applied.push('search');
+        const needles = query.search.toLowerCase().split(/\s+/).filter(Boolean);
+        rows = rows.filter((document) => {
+          const text = haystack(document);
+          return needles.some((needle) => text.includes(needle));
+        });
+      }
+
+      rows = [...rows].sort((a, b) => (b.occurredAt ?? '').localeCompare(a.occurredAt ?? ''));
+      return paginate(rows, query.page ?? 1, query.pageSize ?? defaultPageSize, applied);
+    },
+
+    async getDocument(id: string) {
+      const found = inScope(documents).find((document) => document.id === id);
+      if (!found) {
+        // A row outside the caller's scope is ABSENT, not forbidden — same
+        // convention as the tenant API, where a cross-scope id is a 404.
+        const error = new Error('No such document.') as Error & { status?: number };
+        error.status = 404;
+        throw error;
+      }
+      return found;
+    },
+
+    async listParties(query = {}) {
+      onQuery?.('parties', query);
+      let rows = inScope(parties);
+      const applied: string[] = [];
+      if (query.search) {
+        applied.push('search');
+        const needle = query.search.toLowerCase();
+        rows = rows.filter((party) => `${party.name} ${party.email ?? ''}`.toLowerCase().includes(needle));
+      }
+      return paginate(rows, query.page ?? 1, query.pageSize ?? 50, applied);
+    },
+
+    async listMoneyEvents(query = {}) {
+      onQuery?.('money', query);
+      let rows = inScope(moneyEvents);
+      const applied: string[] = [];
+      if (query.partyId) {
+        applied.push('partyId');
+        rows = rows.filter((event) => event.party?.id === query.partyId);
+      }
+      if (query.search) {
+        applied.push('search');
+        const needles = query.search.toLowerCase().split(/\s+/).filter(Boolean);
+        rows = rows.filter((event) => {
+          const text = `${event.subtype} ${event.status} ${event.description ?? ''} ${event.party?.name ?? ''}`.toLowerCase();
+          return needles.some((needle) => text.includes(needle));
+        });
+      }
+      return paginate(rows, query.page ?? 1, query.pageSize ?? 20, applied);
+    },
+
+    async listSources() {
+      return sources;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+//  a fake TENANT, one level lower
+// ---------------------------------------------------------------------------
+
+/**
+ * A `CorpusHttp` that answers like the tenant data plane itself.
+ *
+ * `createFixtureCorpusApi` above fakes the CONTRACT, which is the right thing to
+ * hand a composer. This fakes the WIRE, which is the only way to test the
+ * adapter that turns storage into the contract — the seam where the Parties
+ * block was lost (bd startsim-768w.38.22). It reproduces the tenant's real
+ * behaviour, including the parts that are inconvenient:
+ *
+ *   • `?type=` is the ONLY filter honoured — `search`, `source` and `party` are
+ *     accepted and ignored, exactly as `EntityViewSet` does today;
+ *   • `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.
+ *
+ * Every request is recorded, so "did the browser filter it" and "how many round
+ * trips did one screen cost" are both assertable.
+ */
+export function createFixtureCorpusHttp(options: {
+  entities?: TenantEntity[];
+  relationships?: TenantRelationship[];
+  /** Rows per page, matching the tenant's own `PAGE_SIZE`. */
+  pageSize?: number;
+  /** Endpoints to fail, so the fail-soft paths are exercised. */
+  missing?: string[];
+  onRequest?: (path: string, params: Record<string, unknown>) => void;
+} = {}) {
+  const entities = options.entities ?? [
+    ...FIXTURE_TENANT_DOCUMENTS,
+    ...FIXTURE_TENANT_PARTIES,
+    ...FIXTURE_TENANT_MONEY_EVENTS,
+  ];
+  const relationships = options.relationships ?? FIXTURE_TENANT_RELATIONSHIPS;
+  const pageSize = options.pageSize ?? 50;
+  const missing = options.missing ?? [];
+  const requests: Array<{ path: string; params: Record<string, unknown> }> = [];
+
+  function slice<T>(rows: T[], params: Record<string, unknown>) {
+    const page = Number(params.page ?? 1) || 1;
+    const start = (page - 1) * pageSize;
+    return {
+      count: rows.length,
+      next: start + pageSize < rows.length ? `?page=${page + 1}` : null,
+      previous: page > 1 ? `?page=${page - 1}` : null,
+      results: rows.slice(start, start + pageSize),
+    };
+  }
+
+  const http = {
+    async get<T>(path: string, init?: { params?: Record<string, unknown> }): Promise<T> {
+      const params = init?.params ?? {};
+      requests.push({ path, params });
+      options.onRequest?.(path, params);
+
+      if (missing.some((fragment) => path.includes(fragment))) {
+        throw Object.assign(new Error(`${path} responded 404`), { status: 404 });
+      }
+      if (path.includes('relationships')) {
+        return slice(relationships, params) as T;
+      }
+      if (path.includes('entities')) {
+        const id = /entities\/(.+)$/.exec(path)?.[1];
+        if (id) {
+          const found = entities.find((entity) => String(entity.id) === decodeURIComponent(id));
+          if (!found) throw Object.assign(new Error('not found'), { status: 404 });
+          return found as T;
+        }
+        const type = params.type ? String(params.type) : '';
+        // `search`/`source`/`party` are deliberately NOT applied.
+        const rows = type ? entities.filter((entity) => entity.entity_type === type) : entities;
+        return slice(rows, params) as T;
+      }
+      throw Object.assign(new Error(`${path} responded 404`), { status: 404 });
+    },
+  };
+
+  return { http, requests };
+}
+
+/**
+ * A `CorpusLlm` that answers WITHOUT a provider, by quoting the documents it was
+ * handed and citing every one it quoted.
+ *
+ * It exists so the retrieval, citation-resolution and scope machinery can be
+ * driven end to end — in vitest and in a browser — with no API key. It reports
+ * `live: false` from `describe()`, and every surface renders that, so a run
+ * powered by this can never be mistaken on screen for a run powered by a model.
+ */
+export function createFixtureLlm(): import('./types').CorpusLlm {
+  return {
+    describe: () => ({ provider: 'fixture', model: 'fixture-echo', live: false }),
+    async answer(input) {
+      if (input.documents.length === 0) {
+        return { answer: '', citations: [], unanswerable: true };
+      }
+      const lines = input.documents.map((document) => {
+        const first = document.text.split('\n').find((line) => line.trim()) ?? document.title;
+        return `- ${document.title} (${document.source}): ${first.trim().slice(0, 180)}`;
+      });
+      const heading =
+        input.mode === 'generate'
+          ? `Draft assembled from ${input.documents.length} record(s):`
+          : `From ${input.documents.length} record(s) in your corpus:`;
+      return {
+        answer: [heading, ...lines].join('\n'),
+        citations: input.documents.map((document) => ({
+          documentId: document.id,
+          quote: document.text.slice(0, 120).trim(),
+        })),
+        unanswerable: false,
+      };
+    },
+  };
+}