@startsimpli/integrations 0.1.4 → 0.1.6

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

@@ -0,0 +1,216 @@
+/**
+ * SCOPE ISOLATION — the test bd startsim-768w.38.7 asks for by name.
+ *
+ * "An AI that retrieves across a scope boundary leaks data in the most
+ * convincing possible format. Write a deliberate test for this — do not just
+ * assume the query layer handles it."
+ *
+ * So this file assumes the query layer DOES NOT handle it. Every case below runs
+ * against a corpus API deliberately configured to leak (`leakScope: true`),
+ * which is what a mis-scoped serializer, a forgotten `org_id` filter or a
+ * cached response would look like from the client's side. If the pipeline is
+ * only safe because the server is, these tests fail — which is the point.
+ *
+ * The bait is `nw_contract_44` in `FIXTURE_OTHER_ORG`: a document that answers
+ * the tandem question BETTER than anything tandem owns. A ranker with no guard
+ * puts it first.
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+import { askCorpus } from '../corpus/ask';
+import {
+  createFixtureCorpusApi,
+  createFixtureLlm,
+  FIXTURE_DOCUMENTS,
+  FIXTURE_ORG,
+  FIXTURE_OTHER_ORG,
+} from '../corpus/fixtures';
+import { enforceScope, isInScope, rankDocuments, retrieveForQuestion } from '../corpus/retrieval';
+import type { AskRequest, CorpusLlm, SourceDocument } from '../corpus/types';
+
+const TANDEM = { orgId: FIXTURE_ORG };
+const NORTHWIND = { orgId: FIXTURE_OTHER_ORG };
+
+/** The question whose most attractive answer lives in the OTHER workspace. */
+const BAIT = 'What did we agree with Acme Robotics on renewal rate and seats?';
+
+function foreignDocuments(documents: SourceDocument[], orgId: string) {
+  return documents.filter((document) => document.scope.orgId !== orgId);
+}
+
+describe('isInScope — the boundary itself', () => {
+  const row = { scope: { orgId: 'tandem', ownerSub: 'usr_dana' } };
+
+  it('admits a row from the same workspace', () => {
+    expect(isInScope(row, { orgId: 'tandem' })).toBe(true);
+  });
+
+  it('refuses a row from another workspace', () => {
+    expect(isInScope(row, { orgId: 'northwind' })).toBe(false);
+  });
+
+  it('refuses everything when the scope carries no org claim', () => {
+    // A principal with no org_id must read NOTHING, not everything. This is the
+    // failure mode where a missing claim reads as "unscoped" and returns the world.
+    expect(isInScope(row, { orgId: '' })).toBe(false);
+  });
+
+  it('enforces the per-row owner only when the caller asked for it', () => {
+    expect(isInScope(row, { orgId: 'tandem', ownerSub: 'usr_dana' })).toBe(true);
+    expect(isInScope(row, { orgId: 'tandem', ownerSub: 'usr_sam' })).toBe(false);
+    // Not asking for an owner is the tenant API's real posture (org + readable
+    // type), so the guard must not silently claim a narrower one.
+    expect(isInScope(row, { orgId: 'tandem' })).toBe(true);
+  });
+
+  it('refuses a row whose org is a PREFIX of the caller’s, not a match', () => {
+    // Guards written with startsWith leak between `acme` and `acme-eu`.
+    expect(isInScope({ scope: { orgId: 'tandem-eu' } }, { orgId: 'tandem' })).toBe(false);
+    expect(isInScope({ scope: { orgId: 'tandem' } }, { orgId: 'tandem-eu' })).toBe(false);
+  });
+});
+
+describe('enforceScope — nothing is dropped silently', () => {
+  it('partitions a mixed set and reports what it removed', () => {
+    const { kept, dropped } = enforceScope(FIXTURE_DOCUMENTS, TANDEM);
+    expect(kept.length + dropped.length).toBe(FIXTURE_DOCUMENTS.length);
+    expect(dropped.length).toBe(foreignDocuments(FIXTURE_DOCUMENTS, FIXTURE_ORG).length);
+    expect(dropped.every((document) => document.scope.orgId === FIXTURE_OTHER_ORG)).toBe(true);
+  });
+});
+
+describe('retrieval refuses the bait', () => {
+  it('ranks the foreign document FIRST when the guard is removed', () => {
+    // Establishes that the guard is doing real work: without it, the leak wins.
+    const unguarded = rankDocuments(FIXTURE_DOCUMENTS, BAIT, { limit: 5 });
+    expect(unguarded[0]?.document.id).toBe('nw_contract_44');
+  });
+
+  it('never returns it once the guard runs', () => {
+    const { retrieved, droppedOutOfScope } = retrieveForQuestion(FIXTURE_DOCUMENTS, BAIT, TANDEM, {
+      limit: 5,
+    });
+    expect(retrieved.length).toBeGreaterThan(0);
+    expect(retrieved.map((item) => item.document.id)).not.toContain('nw_contract_44');
+    expect(retrieved.every((item) => item.document.scope.orgId === FIXTURE_ORG)).toBe(true);
+    expect(droppedOutOfScope).toBeGreaterThan(0);
+  });
+});
+
+describe('askCorpus — the leak never reaches the model', () => {
+  /** A model that records exactly what it was shown. */
+  function spyLlm(): { llm: CorpusLlm; seen: string[][] } {
+    const seen: string[][] = [];
+    const inner = createFixtureLlm();
+    return {
+      seen,
+      llm: {
+        describe: inner.describe,
+        async answer(input) {
+          seen.push(input.documents.map((document) => document.id));
+          return inner.answer(input);
+        },
+      },
+    };
+  }
+
+  const request = (question = BAIT): AskRequest => ({ question, mode: 'ask', scope: TANDEM });
+
+  it('does not put a foreign document in the prompt even when the API returns one', async () => {
+    const corpus = createFixtureCorpusApi({ scope: TANDEM, leakScope: true });
+    const { llm, seen } = spyLlm();
+
+    const result = await askCorpus(request(), { corpus, llm });
+
+    expect(seen).toHaveLength(1); // ONE call, not one per document
+    expect(seen[0]).not.toContain('nw_contract_44');
+    expect(result.droppedOutOfScope).toBeGreaterThan(0);
+    expect(result.citations.every((citation) => citation.document.scope.orgId === FIXTURE_ORG)).toBe(true);
+  });
+
+  it('never cites a foreign document, and says the API returned some', async () => {
+    const corpus = createFixtureCorpusApi({ scope: TANDEM, leakScope: true });
+    const result = await askCorpus(request(), { corpus, llm: createFixtureLlm() });
+
+    expect(result.answer).not.toContain('Northwind');
+    expect(result.answer).not.toContain('2,750');
+    expect(result.citations.map((citation) => citation.documentId)).not.toContain('nw_contract_44');
+    // The count is surfaced so a leaking API is visible rather than absorbed.
+    expect(result.droppedOutOfScope).toBeGreaterThan(0);
+  });
+
+  it('answers a cross-scope question with NOTHING rather than someone else’s records', async () => {
+    // "Northwind" is the one term in the fixture set that appears ONLY in the
+    // other workspace's document, so a question built on it has no honest answer
+    // inside tandem. The wrong outcome here is not an error — it is a fluent,
+    // confident, correctly-formatted answer sourced from another customer.
+    const corpus = createFixtureCorpusApi({ scope: TANDEM, leakScope: true });
+    const result = await askCorpus(
+      { question: 'Northwind', mode: 'ask', scope: TANDEM },
+      { corpus, llm: createFixtureLlm() },
+    );
+
+    expect(result.status).toBe('no_evidence');
+    expect(result.citations).toHaveLength(0);
+    expect(result.considered).toHaveLength(0);
+    expect(result.answer).not.toMatch(/2,?750|unlimited/i);
+  });
+
+  it('answers a shared-term question from its OWN records, never the other workspace’s', async () => {
+    // The subtler half: the question is answerable in both workspaces. Silence
+    // would be over-blocking; the requirement is that the answer is tandem's.
+    const corpus = createFixtureCorpusApi({ scope: TANDEM, leakScope: true });
+    const result = await askCorpus(
+      { question: 'What notice period do we have for termination for convenience?', mode: 'ask', scope: TANDEM },
+      { corpus, llm: createFixtureLlm() },
+    );
+
+    expect(result.status).toBe('answered');
+    expect(result.citations.length).toBeGreaterThan(0);
+    expect(result.citations.every((citation) => citation.document.scope.orgId === FIXTURE_ORG)).toBe(true);
+    expect(result.considered.every((item) => item.document.scope.orgId === FIXTURE_ORG)).toBe(true);
+    expect(result.answer).not.toMatch(/2,?750|unlimited|Northwind/i);
+  });
+
+  it('gives the OTHER workspace its own answer — isolation, not blanket denial', async () => {
+    const corpus = createFixtureCorpusApi({ scope: NORTHWIND, leakScope: true });
+    const result = await askCorpus(
+      { question: 'What renewal rate did we agree with Acme Robotics?', mode: 'ask', scope: NORTHWIND },
+      { corpus, llm: createFixtureLlm() },
+    );
+
+    expect(result.status).toBe('answered');
+    expect(result.citations.map((citation) => citation.documentId)).toEqual(['nw_contract_44']);
+    expect(result.citations.every((citation) => citation.document.scope.orgId === FIXTURE_OTHER_ORG)).toBe(true);
+  });
+
+  it('refuses outright when the session carries no workspace claim', async () => {
+    const corpus = createFixtureCorpusApi({ leakScope: true });
+    const listDocuments = vi.spyOn(corpus, 'listDocuments');
+
+    const result = await askCorpus(
+      { question: BAIT, mode: 'ask', scope: { orgId: '' } },
+      { corpus, llm: createFixtureLlm() },
+    );
+
+    expect(result.status).toBe('no_evidence');
+    expect(result.citations).toHaveLength(0);
+    // It does not even ASK — an unscoped read is not made and then filtered.
+    expect(listDocuments).not.toHaveBeenCalled();
+  });
+
+  it('honours a per-owner scope when one is supplied', async () => {
+    const corpus = createFixtureCorpusApi({ scope: TANDEM, leakScope: true });
+    const result = await askCorpus(
+      {
+        question: 'ad-hoc call with no calendar invite',
+        mode: 'ask',
+        scope: { orgId: FIXTURE_ORG, ownerSub: 'usr_dana' },
+      },
+      { corpus, llm: createFixtureLlm() },
+    );
+
+    // `not_Pd9wLs3EhY6cQz` is owned by usr_sam and is the only match.
+    expect(result.citations.map((citation) => citation.documentId)).not.toContain('not_Pd9wLs3EhY6cQz');
+  });
+});

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

@@ -0,0 +1,301 @@
+/**
+ * THE SEAM: tenant storage -> `SourceDocument` (bd startsim-768w.38.22).
+ *
+ * WHY THIS FILE EXISTS. Every other suite in this package starts from a domain
+ * object. That is correct for a composer — it should be handed a contract — but
+ * it meant nothing in the package had ever run against the shape the pipeline
+ * really writes. The corpus delivery lands people as typed EDGES and puts only a
+ * `participant_count` on the document; the mapper read an inline
+ * `data.participants` array that `declare_canonical()` never emits. Both halves
+ * were individually correct, both were tested, and the Library shipped with an
+ * empty Parties block on every document the pipeline had ever delivered.
+ *
+ * So the assertions below start at the WIRE — raw `Entity` rows and raw
+ * `Relationship` rows, through `createCorpusApi`, out as documents — and they
+ * are the ones that go red if the two halves ever disagree again.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { createCorpusApi } from '../corpus/client';
+import {
+  indexParticipants,
+  toMoneyEvent,
+  toParty,
+  toSourceDocument,
+} from '../corpus/entities';
+import type { TenantEntity, TenantRelationship } from '../corpus/entities';
+import {
+  createFixtureCorpusHttp,
+  FIXTURE_ORG,
+  FIXTURE_SOURCE_LABELS,
+  FIXTURE_TENANT_DOCUMENTS,
+  FIXTURE_TENANT_MONEY_EVENTS,
+  FIXTURE_TENANT_PARTIES,
+  FIXTURE_TENANT_RELATIONSHIPS,
+} from '../corpus/fixtures';
+import { rankDocuments } from '../corpus/retrieval';
+
+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 };
+}
+
+/** The exact row the corpus delivery writes, as read back on live tandem. */
+const DELIVERED_DOCUMENT: TenantEntity = {
+  id: '6c2f1e40-0000-4000-8000-000000000001',
+  entity_type: 'source_document',
+  external_id: 'granola:not_RHRSLnote00003',
+  name: 'Initech — security review',
+  data: {
+    url: 'https://notes.granola.ai/d/initech',
+    title: 'Initech — security review',
+    source: 'granola',
+    _origin: 'central-connector',
+    subtype: 'meeting',
+    summary: '## Blocker\n- **SAML SSO has not shipped**, and Initech will not sign without it.',
+    source_ref: 'not_RHRSLnote00003',
+    occurred_at: '2026-07-20T16:00:00Z',
+    participant_count: 2,
+  },
+  created_at: '2026-08-09T23:35:00Z',
+};
+
+const DELIVERED_PARTIES: TenantEntity[] = [
+  {
+    id: '6c2f1e40-0000-4000-8000-0000000000a1',
+    entity_type: 'party',
+    external_id: 'granola:priya@example.com',
+    name: 'Priya Nakamura',
+    data: {
+      source: 'granola', _origin: 'central-connector', subtype: 'person',
+      display_name: 'Priya Nakamura', email: 'priya@example.com', domain: 'example.com',
+      source_ref: 'priya@example.com',
+    },
+  },
+  {
+    id: '6c2f1e40-0000-4000-8000-0000000000a2',
+    entity_type: 'party',
+    external_id: 'granola:lena@example.com',
+    name: 'Lena Fischer',
+    data: {
+      source: 'granola', _origin: 'central-connector', subtype: 'person',
+      display_name: 'Lena Fischer', email: 'lena@example.com', domain: 'example.com',
+      source_ref: 'lena@example.com',
+    },
+  },
+];
+
+const DELIVERED_EDGES: TenantRelationship[] = [
+  { id: 'e1', rel_type: 'authored_by', source: DELIVERED_DOCUMENT.id, target: DELIVERED_PARTIES[0].id },
+  { id: 'e2', rel_type: 'involves', source: DELIVERED_DOCUMENT.id, target: DELIVERED_PARTIES[1].id },
+];
+
+// ---------------------------------------------------------------------------
+
+describe('the row the pipeline actually delivers', () => {
+  it('has NO inline participants — only a count', () => {
+    // If this ever stops being true the bug class has changed, and the rest of
+    // this file is testing the wrong thing.
+    const data = DELIVERED_DOCUMENT.data as Record<string, unknown>;
+    expect(data.participants).toBeUndefined();
+    expect(data.participant_count).toBe(2);
+  });
+
+  it('renders its people from the EDGES', async () => {
+    const { api } = apiOver({
+      entities: [DELIVERED_DOCUMENT, ...DELIVERED_PARTIES],
+      relationships: DELIVERED_EDGES,
+    });
+
+    const page = await api.listDocuments({ page: 1 });
+    const document = page.results[0];
+
+    expect(document.title).toBe('Initech — security review');
+    expect(document.participants.map((party) => party.name)).toEqual([
+      'Priya Nakamura',
+      'Lena Fischer',
+    ]);
+    // The AUTHOR leads, whatever order the edges paged in.
+    expect(document.participants[0].email).toBe('priya@example.com');
+  });
+
+  it('resolves people on the DETAIL fetch too, not only in the list', async () => {
+    const { api } = apiOver({
+      entities: [DELIVERED_DOCUMENT, ...DELIVERED_PARTIES],
+      relationships: DELIVERED_EDGES,
+    });
+    const document = await api.getDocument(String(DELIVERED_DOCUMENT.id));
+    expect(document.participants.map((party) => party.name)).toContain('Lena Fischer');
+  });
+
+  it('keeps a canonical party readable — `display_name`, not `name`', () => {
+    const party = toParty(DELIVERED_PARTIES[0], SCOPE);
+    expect(party.name).toBe('Priya Nakamura');
+    expect(party.kind).toBe('person');
+    expect(party.source).toBe('granola');
+  });
+});
+
+describe('both storage shapes, because both are real', () => {
+  it('still reads an inline participants array', () => {
+    const inline: TenantEntity = {
+      id: 'doc_inline',
+      entity_type: 'source_document',
+      data: {
+        source: 'upload', title: 'Hand-entered note',
+        participants: [{ id: 'p1', name: 'Ada Byron', email: 'ada@example.com' }],
+      },
+    };
+    expect(toSourceDocument(inline, SCOPE).participants.map((p) => p.name)).toEqual(['Ada Byron']);
+  });
+
+  it('unions the two without listing anyone twice', () => {
+    const both: TenantEntity = {
+      id: 'doc_both',
+      entity_type: 'source_document',
+      data: { source: 'upload', participants: [{ id: 'party_dana', name: 'Dana Reed' }] },
+    };
+    const merged = toSourceDocument(both, SCOPE, {}, [
+      { id: 'party_dana', name: 'Dana Reed', kind: 'person' },
+      { id: 'party_sam', name: 'Sam Ortiz', kind: 'person' },
+    ]);
+    expect(merged.participants.map((party) => party.name)).toEqual(['Dana Reed', 'Sam Ortiz']);
+  });
+
+  it('never puts a DOCUMENT in the parties list — `derived_from` is not a person', () => {
+    const byRecord = indexParticipants(FIXTURE_TENANT_RELATIONSHIPS, [
+      { id: 'party_dana', name: 'Dana Reed' },
+    ]);
+    // `not_7Kq2ZbVnRt4aXm` is the TARGET of a derived_from edge from doc one.
+    expect(byRecord.get('not_1d3tmYTlCICgjy')?.map((p) => p.id)).toEqual(['party_dana']);
+  });
+
+  it('drops an edge whose far end is not a party it can name', () => {
+    const byRecord = indexParticipants(
+      [{ rel_type: 'involves', source: 'doc_1', target: 'party_nobody' }],
+      [{ id: 'party_dana', name: 'Dana Reed' }],
+    );
+    expect(byRecord.size).toBe(0);
+  });
+
+  it('reads a money event’s party from its `billed_to` edge', async () => {
+    const { api } = apiOver();
+    const page = await api.listMoneyEvents!({ page: 1 });
+    const subscription = page.results.find((event) => event.id === 'sub_RedSuite01Acme')!;
+    expect(subscription.party?.name).toBe('Acme Robotics');
+    // …and the amount is still MINOR units off the canonical attribute.
+    expect(subscription.amount).toBe(400000);
+  });
+});
+
+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 () => {
+    const { api, requests } = apiOver();
+    await api.listDocuments({ page: 1 });
+    await api.listDocuments({ page: 1 });
+    await api.getDocument('dbx_9812f0');
+
+    const relationshipReads = requests.filter((request) => request.path.includes('relationships'));
+    expect(relationshipReads).toHaveLength(1);
+  });
+
+  it('does not read the graph at all for an EMPTY corpus', async () => {
+    const { api, requests } = apiOver({ entities: [], relationships: [] });
+    const page = await api.listDocuments({ page: 1 });
+
+    expect(page.results).toEqual([]);
+    expect(requests.filter((request) => request.path.includes('relationships'))).toHaveLength(0);
+  });
+
+  it('still renders the corpus when the relationships endpoint is missing', async () => {
+    // A tenant one deploy behind must degrade to what it showed before this
+    // existed — not to an error where a Library used to be.
+    const { api } = apiOver({ missing: ['relationships'] });
+    const page = await api.listDocuments({ page: 1 });
+
+    expect(page.results.length).toBeGreaterThan(0);
+    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.
+    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 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);
+  });
+});
+
+describe('retrieval scores the people, not an empty string', () => {
+  it('finds a meeting by an attendee’s name that appears nowhere in its text', () => {
+    // `FIELD_WEIGHTS.participants` is 2 — second only to title. Before the edge
+    // join it scored an empty string on every row the pipeline delivered, so a
+    // question naming a person only landed if the prose happened to repeat it.
+    const documents = [
+      toSourceDocument(
+        DELIVERED_DOCUMENT,
+        SCOPE,
+        FIXTURE_SOURCE_LABELS,
+        indexParticipants(DELIVERED_EDGES, DELIVERED_PARTIES.map((row) => toParty(row, SCOPE))).get(
+          String(DELIVERED_DOCUMENT.id),
+        ) ?? [],
+      ),
+      toSourceDocument(FIXTURE_TENANT_DOCUMENTS[1], SCOPE, FIXTURE_SOURCE_LABELS),
+    ];
+    expect(documents[0].body).not.toContain('Lena');
+
+    const ranked = rankDocuments(documents, 'What did Lena Fischer raise?', { limit: 2 });
+    expect(ranked[0]?.document.id).toBe(String(DELIVERED_DOCUMENT.id));
+    expect(ranked[0]?.matchedTerms).toContain('lena');
+  });
+});
+
+describe('the fixtures are the pipeline’s shape, not a friendlier one', () => {
+  it('holds no inline participants anywhere in the raw rows', () => {
+    for (const entity of [...FIXTURE_TENANT_DOCUMENTS, ...FIXTURE_TENANT_MONEY_EVENTS]) {
+      const data = (entity.data ?? {}) as Record<string, unknown>;
+      expect(data.participants).toBeUndefined();
+      expect(data.attendees).toBeUndefined();
+      expect(data.party).toBeUndefined();
+    }
+  });
+
+  it('namespaces every external_id as `<connector_key>:<vendor id>`', () => {
+    for (const entity of [...FIXTURE_TENANT_DOCUMENTS, ...FIXTURE_TENANT_PARTIES]) {
+      const data = (entity.data ?? {}) as Record<string, unknown>;
+      expect(entity.external_id).toBe(`${String(data.source)}:${String(data.source_ref)}`);
+      expect(data._origin).toBe('central-connector');
+    }
+  });
+
+  it('serves them through the adapter with people on every meeting', async () => {
+    const { api } = apiOver();
+    const page = await api.listDocuments({ page: 1 });
+    const weekly = page.results.find((document) => document.sourceRef === 'not_1d3tmYTlCICgjy')!;
+
+    expect(weekly.participants.map((party) => party.name)).toEqual([
+      'Dana Reed', 'Sam Ortiz', 'Kim Li', 'Acme Robotics',
+    ]);
+    expect(weekly.sourceLabel).toBe('Granola');
+  });
+});
+
+describe('the tenant’s filters are still not honoured, and are still not faked', () => {
+  it('reports search as unapplied because the entities endpoint ignores it', async () => {
+    const { api, requests } = apiOver();
+    const page = await api.listDocuments({ search: 'SAML', page: 1 });
+
+    // The parameter IS sent — the day the API learns it, nothing here changes.
+    expect(requests[0].params.search).toBe('SAML');
+    expect(page.appliedFilters).toEqual([]);
+    expect(page.count).toBe(FIXTURE_TENANT_DOCUMENTS.length);
+  });
+});