@startsimpli/integrations 0.2.14 → 0.2.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.14",
+  "version": "0.2.17",
   "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",
@@ -48,7 +48,7 @@
     "react-dom": "^19.0.0",
     "typescript": "^6.0.0",
     "vitest": "^3.0.0",
-    "@startsimpli/llm": "0.4.15"
+    "@startsimpli/llm": "0.4.16"
   },
   "scripts": {
     "type-check": "tsc --noEmit",

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

@@ -0,0 +1,246 @@
+/**
+ * THE FIELD READ GATE, from the client's side (bd startsim-768w.38.33).
+ *
+ * `corpus-scope.test.ts` next door asks "can the pipeline be made to read
+ * another WORKSPACE's records". This asks the narrower and, on the tandem
+ * tenant, more likely question: can it be made to read a part of its OWN
+ * workspace's record that the server withheld from this reader.
+ *
+ * SAME ADVERSARIAL POSTURE, DELIBERATELY. Every case runs against a tenant that
+ * is LEAKING — it names `body` in `redacted_fields` and then sends `body`
+ * anyway, which is what a half-rolled deploy, a response cached from an admin's
+ * session, or a serializer edited without its gate looks like from out here. If
+ * the pipeline is only safe because the server is, these fail. That is the
+ * point; a test against a correctly-behaving server proves the server, not the
+ * client.
+ *
+ * THE BAIT is `doc_checkin`: a document whose SUMMARY is anodyne and whose
+ * withheld `body` contains the verbatim sentence that answers the question best.
+ * A mapper that reads `data.body` without checking `redacted_fields` puts that
+ * sentence into the prompt, the model quotes it, and the leak arrives in the
+ * most convincing possible format — cited, fluent, and attributed to the user's
+ * own corpus.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { askCorpus } from '../corpus/ask';
+import { createCorpusApi } from '../corpus/client';
+import { toSourceDocument, withheldFieldsOf } from '../corpus/entities';
+import type { TenantEntity } from '../corpus/entities';
+import { createFixtureCorpusHttp, createFixtureLlm, FIXTURE_ORG } from '../corpus/fixtures';
+import type { CorpusHttp, CorpusLlm, CorpusScope } from '../corpus/types';
+
+const SCOPE: CorpusScope = { orgId: FIXTURE_ORG };
+
+/** The sentence nobody consented to re-host in a third system. */
+const VERBATIM = 'Dana: I relapsed in March and I have been in therapy weekly since.';
+const ANODYNE = 'Personal check-in. Agreed to revisit the lease in Q3.';
+
+/**
+ * A tenant row as the LEAKING server sends it: the gate ran (it named what it
+ * withheld) and the payload came anyway.
+ */
+function leakingEntity(overrides: Partial<TenantEntity> = {}): TenantEntity {
+  return {
+    id: 'doc_checkin',
+    entity_type: 'source_document',
+    external_id: 'granola:not_checkin',
+    name: 'Personal check-in — therapy, substance use, and relationship progress',
+    org_id: FIXTURE_ORG,
+    created_at: '2026-08-01T10:00:00Z',
+    data: {
+      source: 'granola',
+      subtype: 'meeting',
+      title: 'Personal check-in',
+      summary: ANODYNE,
+      body: VERBATIM,
+      occurred_at: '2026-08-01T09:00:00Z',
+    },
+    redacted_fields: ['body'],
+    ...overrides,
+  };
+}
+
+/** The same row as a CORRECT server sends it: stripped, and saying so. */
+function gatedEntity(): TenantEntity {
+  const row = leakingEntity();
+  const { body: _dropped, ...rest } = row.data as Record<string, unknown>;
+  return { ...row, data: rest };
+}
+
+function httpFor(entities: TenantEntity[]): CorpusHttp {
+  return createFixtureCorpusHttp({ entities, relationships: [] }).http as CorpusHttp;
+}
+
+function apiFor(entities: TenantEntity[]) {
+  return createCorpusApi({ http: httpFor(entities), scope: SCOPE, supportedFilters: [] });
+}
+
+describe('the mapper honours the server’s own declaration', () => {
+  it('drops a withheld key even when the server sent it anyway', () => {
+    const document = toSourceDocument(leakingEntity(), SCOPE);
+    expect(document.body).not.toContain('relapsed');
+    expect(JSON.stringify(document)).not.toContain('relapsed');
+  });
+
+  it('falls back to the summary rather than rendering an empty record', () => {
+    // A blank document would be the other failure: safe, and useless. The
+    // meeting is still a meeting, and its summary was never restricted.
+    const document = toSourceDocument(leakingEntity(), SCOPE);
+    expect(document.body).toBe(ANODYNE);
+    expect(document.summary).toBe(ANODYNE);
+  });
+
+  it('says WHICH field was withheld, so absence is not mistaken for emptiness', () => {
+    // The distinction the whole gate turns on: "this meeting has no transcript"
+    // and "you were not shown this meeting's transcript" are different facts,
+    // and only one of them is an answer.
+    expect(toSourceDocument(leakingEntity(), SCOPE).withheldFields).toEqual(['body']);
+    expect(withheldFieldsOf(leakingEntity())).toEqual(['body']);
+  });
+
+  it('accepts the camelCase spelling the api client produces', () => {
+    const row = leakingEntity();
+    const camel: TenantEntity = { ...row, redacted_fields: undefined, redactedFields: ['body'] };
+    expect(toSourceDocument(camel, SCOPE).body).not.toContain('relapsed');
+  });
+
+  it('leaves a record with nothing withheld exactly as it was', () => {
+    // The migration property, from this side: a corpus with no policy anywhere
+    // must map identically to how it mapped before this existed.
+    const open = leakingEntity({ redacted_fields: undefined });
+    const document = toSourceDocument(open, SCOPE);
+    expect(document.body).toBe(VERBATIM);
+    expect(document.withheldFields).toBeUndefined();
+  });
+
+  it('withholds a section as readily as a top-level field', () => {
+    const row = leakingEntity({
+      data: {
+        source: 'granola',
+        summary: ANODYNE,
+        transcript: VERBATIM,
+      },
+      redacted_fields: ['transcript'],
+    });
+    const document = toSourceDocument(row, SCOPE);
+    expect(JSON.stringify(document.sections)).not.toContain('relapsed');
+  });
+});
+
+describe('the corpus client never surfaces a withheld field', () => {
+  it('keeps it out of a listed document', async () => {
+    const page = await apiFor([leakingEntity()]).listDocuments({ page: 1, pageSize: 50 });
+    expect(page.results).toHaveLength(1);
+    expect(JSON.stringify(page.results)).not.toContain('relapsed');
+    expect(page.results[0]?.withheldFields).toEqual(['body']);
+  });
+
+  it('keeps it out of a fetched document', async () => {
+    const document = await apiFor([leakingEntity()]).getDocument('doc_checkin');
+    expect(JSON.stringify(document)).not.toContain('relapsed');
+  });
+});
+
+describe('askCorpus — the withheld text 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(JSON.stringify(input.documents));
+          return inner.answer(input);
+        },
+      },
+    };
+  }
+
+  /**
+   * A question answerable from the SUMMARY, so the document really is retrieved
+   * and really does reach the prompt. Asking something only the withheld text
+   * could answer would prove nothing: an empty prompt keeps every secret.
+   */
+  const question = 'What did we agree about the lease?';
+
+  it('puts the document in the prompt WITHOUT the withheld text', async () => {
+    const { llm, seen } = spyLlm();
+    await askCorpus({ question, mode: 'ask', scope: SCOPE }, { corpus: apiFor([leakingEntity()]), llm });
+
+    expect(seen).toHaveLength(1); // ONE call, not one per document
+    expect(seen[0]).toContain('lease'); // the record DID reach the model...
+    expect(seen[0]).not.toContain('relapsed'); // ...without the part it may not read
+  });
+
+  it('never quotes it back in the answer or a citation', async () => {
+    const result = await askCorpus(
+      { question, mode: 'ask', scope: SCOPE },
+      { corpus: apiFor([leakingEntity()]), llm: createFixtureLlm() },
+    );
+
+    expect(result.status).toBe('answered');
+    expect(result.answer).not.toContain('relapsed');
+    expect(JSON.stringify(result.citations)).not.toContain('relapsed');
+  });
+
+  it('reports that something was withheld rather than absorbing it', async () => {
+    // Same contract as `droppedOutOfScope`: an answer built from a partial
+    // record has to say so. Otherwise "your corpus has nothing about that" and
+    // "you were not shown the part that does" are the same sentence.
+    const result = await askCorpus(
+      { question, mode: 'ask', scope: SCOPE },
+      { corpus: apiFor([leakingEntity()]), llm: createFixtureLlm() },
+    );
+    expect(result.withheldFields).toEqual(['body']);
+  });
+
+  it('tells the MODEL the record is partly withheld, so it cannot answer a confident no', async () => {
+    const { llm, seen } = spyLlm();
+    await askCorpus({ question, mode: 'ask', scope: SCOPE }, { corpus: apiFor([leakingEntity()]), llm });
+    expect(seen[0]).toContain('withheldFields');
+  });
+
+  it('does not retrieve on a term that exists ONLY in the withheld text', async () => {
+    // The client-side half of the search oracle the tenant API closes. If the
+    // withheld words were still rankable here, a reader could confirm what a
+    // transcript contains by watching which records come back — an answer about
+    // somebody's private speech, delivered without ever printing it.
+    const result = await askCorpus(
+      { question: 'relapsed', mode: 'ask', scope: SCOPE },
+      { corpus: apiFor([leakingEntity()]), llm: createFixtureLlm() },
+    );
+    expect(result.status).toBe('no_evidence');
+    expect(result.citations).toHaveLength(0);
+    expect(result.answer).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
+    // not, and the two answers must not differ.
+    const ask = (entity: TenantEntity) =>
+      askCorpus(
+        { question, mode: 'ask', scope: SCOPE },
+        { corpus: apiFor([entity]), llm: createFixtureLlm() },
+      );
+    const [leaked, gated] = await Promise.all([ask(leakingEntity()), ask(gatedEntity())]);
+    expect(leaked.answer).toBe(gated.answer);
+    expect(leaked.withheldFields).toEqual(gated.withheldFields);
+  });
+
+  it('still answers from the parts the reader IS allowed to see', async () => {
+    // Over-blocking would be the other way to fail: the summary was never
+    // restricted, and a corpus that goes silent because one field is gated has
+    // taken the product away in order to protect it.
+    const result = await askCorpus(
+      { question, mode: 'ask', scope: SCOPE },
+      { corpus: apiFor([leakingEntity()]), llm: createFixtureLlm() },
+    );
+    expect(result.status).toBe('answered');
+    expect(result.citations.length).toBeGreaterThan(0);
+    expect(result.answer).toContain('lease');
+  });
+});

package/src/__tests__/corpus-llm-timeout.test.ts

@@ -0,0 +1,91 @@
+/**
+ * THE SECOND SIXTY-SECOND WALL (bd startsim-768w.38.28).
+ *
+ * The one everybody measured was the tenant gateway's. This is the other one:
+ * the provider client in `@startsimpli/llm` defaults to a 60,000ms
+ * AbortController, and against claude-sonnet-5 over the real tandem corpus one
+ * document takes 19.6 seconds while two (7,909 prompt characters) do not finish
+ * at all. Because the extract call is deliberately wrapped so a provider outage
+ * costs the extras and not the list, hitting it was SILENT — the run returned
+ * every rules-derived commitment and `fromModel: 0`, which reads exactly like
+ * "the model found nothing to add".
+ *
+ * Putting extraction on a job is what makes a longer deadline affordable:
+ * nothing is holding a socket open waiting for it. So the deadline has to be
+ * settable per call, and it has to actually reach the provider — an option that
+ * is accepted and dropped is worse than no option, because it looks fixed.
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+import { createCorpusExtractor, createCorpusLlm } from '../corpus/llm';
+
+function fakeService(content: string) {
+  return {
+    chat: vi.fn(async () => ({ content, model: 'claude-sonnet-5' })),
+    isAvailable: () => true,
+    getAvailableProviders: () => ['anthropic'],
+  };
+}
+
+describe('a queued run can buy real time from the provider', () => {
+  it('passes the deadline the caller asked for through to the provider call', async () => {
+    const service = fakeService('{"items":[],"resolutions":[]}');
+    const extractor = createCorpusExtractor({
+      service: service as never,
+      timeoutMs: 240_000,
+      env: {},
+    });
+
+    await extractor.extract({ documents: [] });
+
+    expect(service.chat).toHaveBeenCalledTimes(1);
+    expect(service.chat.mock.calls[0][2]).toEqual({ timeout: 240_000 });
+  });
+
+  it('carries the deadline into the JSON-repair retry too', async () => {
+    // The repair is a correction of the SAME request, so it has the same amount
+    // of work to do. Sending it with the default deadline would make the retry
+    // fail for a reason the first attempt did not.
+    const service = fakeService('not json at all');
+    const extractor = createCorpusExtractor({
+      service: service as never,
+      timeoutMs: 240_000,
+      env: {},
+    });
+
+    await extractor.extract({ documents: [] });
+
+    expect(service.chat).toHaveBeenCalledTimes(2);
+    expect(service.chat.mock.calls[1][2]).toEqual({ timeout: 240_000 });
+  });
+
+  it('falls back to the deployment-wide LLM_TIMEOUT_MS when no call sets one', async () => {
+    const service = fakeService('{"items":[],"resolutions":[]}');
+    const extractor = createCorpusExtractor({
+      service: service as never,
+      env: { LLM_TIMEOUT_MS: '120000' },
+    });
+
+    await extractor.extract({ documents: [] });
+
+    expect(service.chat.mock.calls[0][2]).toEqual({ timeout: 120_000 });
+  });
+
+  it('sends nothing at all when neither is set, so the provider default stands', async () => {
+    const service = fakeService('{"items":[],"resolutions":[]}');
+    const extractor = createCorpusExtractor({ service: service as never, env: {} });
+
+    await extractor.extract({ documents: [] });
+
+    expect(service.chat.mock.calls[0][2]).toBeUndefined();
+  });
+
+  it('applies to the Ask adapter as well, which shares the seam', async () => {
+    const service = fakeService('{"answer":"x","citations":[]}');
+    const llm = createCorpusLlm({ service: service as never, timeoutMs: 90_000, env: {} });
+
+    await llm.answer({ mode: 'ask', question: 'x', documents: [] } as never);
+
+    expect(service.chat.mock.calls[0][2]).toEqual({ timeout: 90_000 });
+  });
+});

package/src/__tests__/corpus-pages.test.tsx

@@ -311,6 +311,53 @@ function askApiOver(api: CorpusApi, extra: Partial<CorpusAskApi> = {}): CorpusAs
   };
 }
 
+describe('a withheld field is SHOWN as withheld, not as empty', () => {
+  // bd startsim-768w.38.33. The tenant strips a restricted attribute and names
+  // it back; if the screen renders the gap silently, the reader concludes the
+  // meeting had no transcript — which is a stronger, and wrong, claim than the
+  // gate ever made.
+
+  it('LibraryPage names what was held back on the open record', async () => {
+    const withheld: SourceDocument = {
+      ...ownDocuments()[0],
+      id: 'doc_withheld',
+      title: 'Personal check-in',
+      withheldFields: ['body'],
+    };
+    const api = createFixtureCorpusApi({
+      scope: SCOPE, documents: [withheld], moneyEvents: [],
+    });
+    render(<LibraryPage api={api} scope={SCOPE} initialDocumentId="doc_withheld" />);
+
+    expect(await screen.findByText(/not shared with you/i)).toBeInTheDocument();
+    expect(screen.getByText(/body/)).toBeInTheDocument();
+  });
+
+  it('AskPage says the answer may be incomplete', async () => {
+    const user = userEvent.setup();
+    const api: CorpusAskApi = {
+      async ask() {
+        return {
+          status: 'answered',
+          answer: 'They agreed to revisit the lease in Q3.',
+          citations: [],
+          considered: [],
+          unresolvedCitations: [],
+          droppedOutOfScope: 0,
+          withheldFields: ['body'],
+          provider: { provider: 'fixture', model: 'fixture-echo', live: false },
+        };
+      },
+    };
+    render(<AskPage api={api} scope={SCOPE} />);
+    await user.type(screen.getByRole('textbox'), 'lease');
+    await user.click(screen.getByRole('button', { name: 'Ask' }));
+
+    const answer = await screen.findByRole('region', { name: 'Answer' });
+    expect(within(answer).getByText(/only partly shared with you/i)).toBeInTheDocument();
+  });
+});
+
 describe('AskPage — an answer is only an answer when it is traceable', () => {
   it('renders the answer with a citation per record, clickable through to it', async () => {
     const user = userEvent.setup();