@startsimpli/integrations 0.2.18 → 0.2.20

package/package.json

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

package/src/__tests__/corpus-field-gate.test.ts

@@ -217,6 +217,35 @@ describe('askCorpus — the withheld text never reaches the model', () => {
     expect(result.answer).not.toContain('relapsed');
   });
 
+  it('does not retrieve on a withheld term carried in on a LOOSER query', async () => {
+    // The widening in bd startsim-768w.38.36 is the obvious way to reopen this.
+    // A question is no longer sent as a conjunction — it is sent as a
+    // DISJUNCTION of its content words — so "lease" is now enough to bring this
+    // record back on its own, and the withheld word rides along in the same
+    // query. If the ranker ever scored on what the SERVER matched rather than on
+    // what the reader may see, that record would arrive with the withheld term
+    // in its matched set and the model would be invited to answer about it.
+    //
+    // The fixture server here is the leaking one and searches the withheld
+    // `body` too, so the row genuinely comes back on this query. Everything
+    // after that has to hold on its own.
+    const { llm, seen } = spyLlm();
+    const result = await askCorpus(
+      { question: 'was anything said about the lease or relapsed treatment?', mode: 'ask', scope: SCOPE },
+      { corpus: apiFor([leakingEntity()]), llm },
+    );
+
+    // It DID retrieve — on `lease`, which is in the summary and always was.
+    expect(result.status).toBe('answered');
+    expect(seen[0]).toContain('lease');
+    // ...and the withheld word reached neither the prompt, the answer, nor the
+    // evidence the surface will show for it.
+    expect(seen[0]).not.toContain('relapsed');
+    expect(JSON.stringify(result.citations)).not.toContain('relapsed');
+    expect(JSON.stringify(result.considered)).not.toContain('relapsed');
+    expect(result.considered.flatMap((item) => item.matchedTerms)).not.toContain('relapsed');
+  });
+
   it('answers identically whether the server leaked or behaved', async () => {
     // The falsifiable version of "the client does not depend on the server
     // getting it right": same question, one API stripping the field and one

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

@@ -0,0 +1,318 @@
+/**
+ * A QUESTION IS NOT A BOOLEAN AND OF ITS WORDS (bd startsim-768w.38.36).
+ *
+ * `corpus-ask.test.ts` next door protects the honesty rules — that an untraceable
+ * answer can never be rendered as a traceable one. This file protects the stage
+ * BEFORE any of that is reachable: whether the records that would answer the
+ * question are still in the candidate set by the time the ranker runs.
+ *
+ * WHAT WENT WRONG, MEASURED ON THE LIVE TANDEM TENANT. `loadCandidates` sent the
+ * WHOLE question as `?search=`. The tenant compiles that with
+ * `websearch_to_tsquery('english', …)`, which joins bare words with `&` — so
+ * "What did we agree about the parking allocation?" only retrieved a document
+ * containing `agree` AND `parking` AND `allocation`, and 18 documents and 63,208
+ * characters of summary were discarded before ranking ever happened. A single
+ * rare word still answered, which is what made it look like a corpus problem;
+ * the surface said so out loud, blaming the connector for a query bug.
+ *
+ * SO THE FIXTURE HERE RUNS THE TENANT'S OWN SEARCH (`searchBackend:
+ * 'postgres_fulltext'`). Against the permissive fixture this package shipped
+ * with — whitespace-split substrings, OR'd — every case below passes on the
+ * broken client. A fixture easier to satisfy than production does not fail safe.
+ *
+ * THE TWO FAILURES ARE OPPOSITE, and both are here on purpose:
+ *
+ *   TOO NARROW is the bug: an ordinary question retrieves nothing.
+ *   TOO WIDE is the tempting fix: match everything, put the whole corpus in the
+ *   prompt and let the model sort it out. That trades a visible failure for an
+ *   invisible one — a confident answer assembled from whatever happened to be
+ *   recent. So a rare single term must still retrieve exactly its own record.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { askCorpus } from '../corpus/ask';
+import { createCorpusApi } from '../corpus/client';
+import type { TenantEntity } from '../corpus/entities';
+import { createFixtureCorpusHttp, createFixtureLlm, FIXTURE_ORG } from '../corpus/fixtures';
+import { searchTermFor } from '../corpus/retrieval';
+import type { AskResult, CorpusHttp, CorpusScope } from '../corpus/types';
+
+const SCOPE: CorpusScope = { orgId: FIXTURE_ORG };
+
+/**
+ * A corpus shaped like the real one: meeting notes whose whole substance is a
+ * long `summary`, written the way a note-taker writes rather than the way a
+ * query is typed. No document contains every word of any question asked below,
+ * which is the entire point.
+ */
+function meeting(
+  id: string,
+  title: string,
+  occurredAt: string,
+  summary: string,
+): TenantEntity {
+  return {
+    id,
+    entity_type: 'source_document',
+    external_id: `granola:${id}`,
+    name: title,
+    org_id: FIXTURE_ORG,
+    created_at: `${occurredAt.slice(0, 10)}T12:00:00Z`,
+    data: { source: 'granola', subtype: 'meeting', title, summary, occurred_at: occurredAt },
+  };
+}
+
+const CORPUS: TenantEntity[] = [
+  meeting(
+    'doc_office',
+    'Office move — landlord terms and fit-out',
+    '2026-07-28T09:00:00Z',
+    [
+      'Landlord came back on the renewal. We agreed to a twelve month extension on the',
+      'lease at the current rate, with a three month break clause either side.',
+      'Fit-out costs are split, capped at 20k. Signature target is the 15th.',
+    ].join(' '),
+  ),
+  meeting(
+    'doc_site',
+    'Site walkthrough — Lamar building',
+    '2026-07-21T09:00:00Z',
+    [
+      'Walked the Lamar building with the broker. Six parking bays come with the unit;',
+      'two are currently used by the ground floor tenant and nobody has written down',
+      'who gets what. Broker to send the site plan so we can settle it before signing.',
+    ].join(' '),
+  ),
+  meeting(
+    'doc_july',
+    'July financials, tenders strategy, staffing update',
+    '2026-07-14T09:00:00Z',
+    [
+      'Collections are ahead of plan. On the patent dispute, a filing action tying up',
+      'the IP could block the funding round, so we hold the interest notice until Jeff',
+      'has reviewed it. Staffing: two offers out, one accepted.',
+    ].join(' '),
+  ),
+  meeting(
+    'doc_insurance',
+    'Property finances — loan renewals and insurance',
+    '2026-06-30T09:00:00Z',
+    [
+      'The insurance renewal is with the broker and we are waiting on their revised',
+      'quote before we can sign anything. Loan renewals for two of the properties are',
+      'due in September; the bank wants updated valuations first.',
+    ].join(' '),
+  ),
+  meeting(
+    'doc_rent',
+    'Rent Manager Express setup and Zillow posting',
+    '2026-06-16T09:00:00Z',
+    [
+      'Rent Manager Express is configured for the two smaller properties. Zillow',
+      'postings go up Monday. The QUIBBLETRON migration script is still the only',
+      'blocker on moving the rest of the portfolio across.',
+    ].join(' '),
+  ),
+  meeting(
+    'doc_mcr',
+    'MCR platform demo — streaming data and task automation',
+    '2026-05-19T09:00:00Z',
+    [
+      'Demoed the streaming ingest. Fuga integration is behind a vendor key we do not',
+      'have yet. Task automation from Granola notes is the piece they cared about.',
+    ].join(' '),
+  ),
+];
+
+function corpusFor(entities: TenantEntity[] = CORPUS) {
+  const { http, requests } = createFixtureCorpusHttp({
+    entities,
+    relationships: [],
+    searchBackend: 'postgres_fulltext',
+  });
+  return {
+    requests,
+    api: createCorpusApi({ http: http as CorpusHttp, scope: SCOPE, supportedFilters: [] }),
+  };
+}
+
+function askWith(question: string, entities?: TenantEntity[]): Promise<AskResult> {
+  return askCorpus(
+    { question, mode: 'ask', scope: SCOPE },
+    { corpus: corpusFor(entities).api, llm: createFixtureLlm() },
+  );
+}
+
+const citedIds = (result: AskResult) => result.citations.map((citation) => citation.documentId);
+
+// ---------------------------------------------------------------------------
+
+describe('an ordinary question retrieves', () => {
+  /**
+   * The three the user reproduced on prod, plus the phrasings people actually
+   * type. Every one of these returned `no_evidence` with zero citations against
+   * a corpus that answers them.
+   */
+  const cases: Array<[question: string, expected: string]> = [
+    ['What did we agree about the lease?', 'doc_office'],
+    ['what is blocked?', 'doc_july'],
+    ['What did we agree about the parking allocation?', 'doc_site'],
+    ['who are we waiting on for the insurance renewal?', 'doc_insurance'],
+    ['what did we decide about staffing?', 'doc_july'],
+    ['when are the loan renewals due?', 'doc_insurance'],
+    ['did we sort out the parking bays', 'doc_site'],
+    ['whats the story with the landlord', 'doc_office'],
+  ];
+
+  for (const [question, expected] of cases) {
+    it(`answers "${question}" and cites ${expected}`, async () => {
+      const result = await askWith(question);
+      expect(result.status).toBe('answered');
+      expect(result.citations.length).toBeGreaterThan(0);
+      expect(citedIds(result)).toContain(expected);
+    });
+  }
+
+  it('retrieves a question whose words are stemmed apart from the record’s', async () => {
+    // The tenant's `english` configuration folds `blocked` and `block` to one
+    // lexeme, so the SERVER matches. The client ranker tokenizes exactly, so it
+    // used to throw the row away again on the way to the prompt — two retrieval
+    // layers disagreeing about what a match is, which is invisible from either
+    // side alone.
+    const result = await askWith('what is blocked?');
+    expect(citedIds(result)).toContain('doc_july');
+  });
+
+  it('does not need every word of the question to appear in one record', async () => {
+    // No document contains `allocation` at all. Under a conjunction that is the
+    // end of it; under a question, `parking` is plenty.
+    const result = await askWith('What did we agree about the parking allocation?');
+    expect(result.status).toBe('answered');
+  });
+});
+
+describe('but a question is not an excuse to retrieve everything', () => {
+  it('retrieves ONLY the record holding a rare single term', async () => {
+    const result = await askWith('QUIBBLETRON');
+    expect(result.status).toBe('answered');
+    expect(citedIds(result)).toEqual(['doc_rent']);
+  });
+
+  it('keeps a rare term rare even when it is asked as a sentence', async () => {
+    const result = await askWith('what is the QUIBBLETRON migration waiting on?');
+    expect(citedIds(result)).toContain('doc_rent');
+    // `migration` and `waiting` are real words in this corpus, so a couple of
+    // other records may legitimately come along — but not the whole shelf.
+    expect(result.citations.length).toBeLessThan(CORPUS.length);
+  });
+
+  it('does not put the entire corpus in front of the model for a narrow question', async () => {
+    const seen: number[] = [];
+    await askCorpus(
+      { question: 'what did we agree about the lease?', mode: 'ask', scope: SCOPE },
+      {
+        corpus: corpusFor().api,
+        llm: {
+          describe: () => ({ provider: 'spy', model: 'spy', live: false }),
+          async answer(input) {
+            seen.push(input.documents.length);
+            return { answer: 'ok', citations: [], unanswerable: false };
+          },
+        },
+      },
+    );
+    expect(seen[0]).toBeGreaterThan(0);
+    expect(seen[0]).toBeLessThan(CORPUS.length);
+  });
+
+  it('still refuses when the corpus genuinely has nothing, without calling the model', async () => {
+    const calls: unknown[] = [];
+    const result = await askCorpus(
+      { question: 'what did the arbitration panel rule on the trademark?', mode: 'ask', scope: SCOPE },
+      {
+        corpus: corpusFor().api,
+        llm: {
+          describe: () => ({ provider: 'spy', model: 'spy', live: false }),
+          async answer(input) {
+            calls.push(input);
+            return { answer: 'I could improvise.', citations: [], unanswerable: false };
+          },
+        },
+      },
+    );
+    expect(result.status).toBe('no_evidence');
+    expect(calls).toHaveLength(0);
+  });
+});
+
+describe('the search term the tenant is actually sent', () => {
+  it('is a disjunction of the question’s content words, not the question', async () => {
+    const { api, requests } = corpusFor();
+    await askCorpus(
+      { question: 'What did we agree about the parking allocation?', mode: 'ask', scope: SCOPE },
+      { corpus: api, llm: createFixtureLlm() },
+    );
+    const term = String(
+      requests.find((request) => request.params.type === 'source_document')?.params.search ?? '',
+    );
+    expect(term).not.toContain('?');
+    expect(term.toLowerCase()).toContain(' or ');
+    expect(term.toLowerCase()).toContain('parking');
+    // Interrogatives and function words carry no signal and, ANDed, delete the
+    // question outright.
+    expect(term.toLowerCase().split(/\s+or\s+/)).not.toContain('what');
+  });
+
+  it('leaves a single rare term exactly as it was typed', () => {
+    // The precision case has to be untouched: one word in, one word out, no
+    // disjunction to widen it.
+    expect(searchTermFor('QUIBBLETRON')).toBe('quibbletron');
+  });
+
+  it('sends NO search term at all when the question is only function words', () => {
+    // `websearch_to_tsquery` compiles a stopword-only query to an EMPTY tsquery,
+    // which matches no row. Sending it would be asking the server for nothing.
+    expect(searchTermFor('what is it?')).toBe('');
+  });
+
+  it('keeps a quoted phrase quoted, and an excluded word excluded', () => {
+    expect(searchTermFor('"funding round"')).toBe('"funding round"');
+    expect(searchTermFor('parking -zillow')).toContain('-zillow');
+  });
+
+  it('asks the server to order by relevance, so page one is the relevant page', async () => {
+    const { api, requests } = corpusFor();
+    await askCorpus(
+      { question: 'what did we agree about the lease?', mode: 'ask', scope: SCOPE },
+      { corpus: api, llm: createFixtureLlm() },
+    );
+    const request = requests.find((entry) => entry.params.type === 'source_document');
+    expect(request?.params.order).toBe('relevance');
+  });
+});
+
+describe('a question with no content words falls back to the recent window', () => {
+  it('answers "what happened lately?" from the newest records', async () => {
+    const result = await askWith('what is going on?');
+    expect(result.status).toBe('answered');
+    expect(citedIds(result)).toContain('doc_office'); // the newest record
+  });
+});
+
+describe('the copy tells the truth about whose fault it is', () => {
+  it('does not blame the corpus when the corpus is full and the question missed', async () => {
+    const result = await askWith('what did the arbitration panel rule on the trademark?');
+    expect(result.status).toBe('no_evidence');
+    // The shipped sentence — "Either it has not been pulled in yet, or it
+    // belongs to a different workspace" — sent someone to check the connector
+    // for a query bug. Six records were sitting right there.
+    expect(result.answer).not.toMatch(/has not been pulled in/i);
+    expect(result.answer).toMatch(/6 record/i);
+  });
+
+  it('DOES say the workspace is empty when the workspace is empty', async () => {
+    const result = await askWith('what did we agree about the lease?', []);
+    expect(result.status).toBe('no_evidence');
+    expect(result.answer).toMatch(/nothing has been pulled in|no records/i);
+  });
+});

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

@@ -80,10 +80,19 @@ describe('enforceScope — nothing is dropped silently', () => {
 });
 
 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.
+  it('ranks the foreign document at the very top when the guard is removed', () => {
+    // Establishes that the guard is doing real work: without it, the leak is not
+    // some tail result the model would ignore — it is the most attractive answer
+    // in the set and it reaches the prompt.
+    //
+    // ASSERTED AS "in the top two", not "first", since bd startsim-768w.38.36:
+    // the ranker now agrees with the tenant's stemmer, so the caller's OWN Acme
+    // note matches `agree` against its "agreed" and covers all six terms of the
+    // question rather than five. It edges ahead by 3%. The bait is no less
+    // attractive and the guard is no less necessary; pinning an exact ordinal
+    // pinned an artifact of the tokenizer instead of the property.
     const unguarded = rankDocuments(FIXTURE_DOCUMENTS, BAIT, { limit: 5 });
-    expect(unguarded[0]?.document.id).toBe('nw_contract_44');
+    expect(unguarded.slice(0, 2).map((item) => item.document.id)).toContain('nw_contract_44');
   });
 
   it('never returns it once the guard runs', () => {