@startsimpli/integrations 0.2.14 → 0.2.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "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-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();

package/src/components/pages/AskPage.tsx

@@ -260,6 +260,17 @@ function AnswerPanel({
         </p>
       ) : null}
 
+      {/* An answer built from a partly-withheld record has to say so
+          (bd startsim-768w.38.33) — otherwise "your corpus has nothing about
+          that" and "you were not shown the part that does" are the same
+          sentence, and the second one is the dangerous one to believe. */}
+      {result.withheldFields?.length ? (
+        <p className={cn.warning} role="status">
+          Some records were only partly shared with you ({result.withheldFields.join(', ')}),
+          so this answer may be incomplete.
+        </p>
+      ) : null}
+
       {/* A model asked for prose answers in Markdown. Rendering it as literal
           text puts "**$4,800**" on the screen, which reads as the product
           failing rather than as the model emphasising the number. */}

package/src/components/pages/LibraryPage.tsx

@@ -639,6 +639,18 @@ function DocumentDetail({
         </details>
       ) : null}
 
+      {/* WITHHELD IS NOT EMPTY (bd startsim-768w.38.33). The tenant's per-field
+          read gate strips a restricted attribute and names it in
+          `redacted_fields`; without this line the reader sees a meeting with no
+          transcript and concludes there wasn't one. Named rather than counted,
+          because "the transcript" and "the salary" are different absences. */}
+      {document.withheldFields?.length ? (
+        <p className={`mt-3 ${cn.warning}`} role="status">
+          Part of this record is not shared with you:{' '}
+          {document.withheldFields.join(', ')}. Ask an admin if you need it.
+        </p>
+      ) : null}
+
       {/* Long-form under the SOURCE's own name for it — "Transcript" for a
           meeting, "Extracted text" for a PDF. This component does not know
           which is which, and must not. */}

package/src/corpus/ask.ts

@@ -75,6 +75,7 @@ function systemPrompt(mode: AskRequest['mode']): string {
     'You answer questions about a company using only that company\'s own records.',
     ...shared,
     'Be specific and short. Prefer naming the record and the date over hedging.',
+    'A document may list "withheld_from_this_reader". Those parts were deliberately not shown to you: never claim something was not said or did not happen on the basis of a document that lists them — say the record is partly withheld instead.',
   ].join('\n');
 }
 
@@ -94,6 +95,7 @@ export function buildAnswerRequest(
     occurredAt: document.occurredAt,
     participants: document.participants.map((party) => party.name),
     text: documentText(document, maxChars),
+    ...(document.withheldFields?.length ? { withheldFields: document.withheldFields } : {}),
   }));
   return {
     question: request.question,
@@ -126,6 +128,13 @@ export function renderAnswerPrompt(input: AnswerRequest): string {
       `source: ${document.source}`,
       `occurred_at: ${document.occurredAt ?? 'unknown'}`,
       document.participants.length ? `participants: ${document.participants.join(', ')}` : '',
+      // The model is told what it was NOT given. Otherwise a summary-only view of
+      // a meeting whose transcript was withheld is indistinguishable from a
+      // meeting where the thing was never said, and the answer comes back as a
+      // confident negative about text nobody was allowed to show it.
+      document.withheldFields?.length
+        ? `withheld_from_this_reader: ${document.withheldFields.join(', ')}`
+        : '',
       '',
       document.text,
       '</document>',
@@ -279,6 +288,8 @@ export async function askCorpus(
     };
   }
 
+  const withheldFields = collectWithheld(retrieved);
+
   const draft = await llm.answer(
     buildAnswerRequest(request, retrieved, maxCharsPerDocument),
   );
@@ -294,11 +305,21 @@ export async function askCorpus(
     considered: retrieved,
     unresolvedCitations: unresolved,
     droppedOutOfScope,
+    ...(withheldFields.length ? { withheldFields } : {}),
     provider: llm.describe(),
     freshness,
   };
 }
 
+/** Every field withheld on any record that reached the prompt, deduped. */
+function collectWithheld(retrieved: RetrievedDocument[]): string[] {
+  const names = new Set<string>();
+  for (const item of retrieved) {
+    for (const name of item.document.withheldFields ?? []) names.add(name);
+  }
+  return [...names].sort();
+}
+
 /**
  * `uncited` is a real outcome, not a failure to report. The model produced text
  * and nothing traceable; the surface renders that as a warning over the text

package/src/corpus/entities.ts

@@ -85,6 +85,14 @@ export interface TenantEntity {
   orgId?: string;
   owner_sub?: string;
   ownerSub?: string;
+  /**
+   * Attribute names the tenant's per-field read gate withheld from this caller
+   * (bd startsim-768w.38.33). The server has ALREADY removed them from `data`;
+   * this names them so the absence is legible rather than mistaken for a record
+   * that never had them.
+   */
+  redacted_fields?: string[];
+  redactedFields?: string[];
 }
 
 /**
@@ -111,9 +119,35 @@ export const DEFAULT_TYPE_KEYS: CorpusTypeKeys = {
 //  tolerant accessors
 // ---------------------------------------------------------------------------
 
+/**
+ * Field names the server says it withheld from this caller
+ * (bd startsim-768w.38.33). Both spellings, for the same reason every other
+ * accessor here takes both: the `@startsimpli/api` client transforms
+ * snake_case↔camelCase and either client can fetch a row.
+ */
+export function withheldFieldsOf(entity: TenantEntity): string[] {
+  const raw = entity.redacted_fields ?? entity.redactedFields;
+  return Array.isArray(raw) ? raw.map((name) => String(name)).filter(Boolean) : [];
+}
+
 function bag(entity: TenantEntity): Record<string, unknown> {
   const data = entity.data;
-  return data && typeof data === 'object' ? (data as Record<string, unknown>) : {};
+  const payload = data && typeof data === 'object' ? (data as Record<string, unknown>) : {};
+  // BELT AND BRACES, ON PURPOSE. The gate is enforced server-side and `data`
+  // arrives already stripped — so in the normal case this loop removes nothing.
+  // It runs anyway because `redacted_fields` is the server telling us what it
+  // meant to withhold, and a build where the two disagree (a half-rolled deploy,
+  // a response cached from an admin's session, a serializer edited without its
+  // gate) is exactly the case where a client that trusts `data` alone quotes a
+  // transcript into an answer. Honouring the server's own declaration costs one
+  // pass over a small object and turns that class of bug into a no-op.
+  const withheld = withheldFieldsOf(entity);
+  if (!withheld.length) return payload;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(payload)) {
+    if (!withheld.includes(key)) out[key] = value;
+  }
+  return out;
 }
 
 /**
@@ -449,6 +483,9 @@ export function toSourceDocument(
     ),
     scope: scopeOf(entity, fallbackScope),
     ingestedAt: asIso(entity.created_at ?? entity.createdAt),
+    ...(withheldFieldsOf(entity).length
+      ? { withheldFields: withheldFieldsOf(entity) }
+      : {}),
   };
 }
 

package/src/corpus/types.ts

@@ -127,6 +127,19 @@ export interface SourceDocument {
   scope: CorpusScope;
   /** When the connector last wrote this row. Drives the freshness claim. */
   ingestedAt?: string | null;
+  /**
+   * Attribute names the SERVER withheld from this reader
+   * (bd startsim-768w.38.33). The tenant's per-field read gate strips them from
+   * `data` and names them back in `redacted_fields`; this carries that fact all
+   * the way to the screen and into the prompt.
+   *
+   * IT HAS TO TRAVEL, and that is the whole reason it is on the document rather
+   * than swallowed at the mapper. A record whose transcript was withheld is NOT
+   * a record with no transcript. Anything that cannot tell the two apart — a
+   * reader, or a model asked "was this discussed?" — answers "no" with total
+   * confidence about text it was simply never shown.
+   */
+  withheldFields?: string[];
 }
 
 /**
@@ -299,6 +312,14 @@ export interface AskResult {
    * returned something it should not have, and is worth seeing.
    */
   droppedOutOfScope: number;
+  /**
+   * Attribute names the server withheld from this reader on at least one record
+   * that was considered (bd startsim-768w.38.33). Reported for exactly the
+   * reason `droppedOutOfScope` is: an answer built from a partial record has to
+   * say so, or "your corpus has nothing about that" and "you were not shown the
+   * part that does" become the same sentence.
+   */
+  withheldFields?: string[];
   /** Which provider/model actually answered, and whether it was a real one. */
   provider: LlmDescription;
   /** Freshness at answer time — an answer over a stale corpus says so. */
@@ -323,6 +344,13 @@ export interface PromptDocument {
   occurredAt: string | null;
   participants: string[];
   text: string;
+  /**
+   * Fields the reader was not allowed to see (bd startsim-768w.38.33). Rendered
+   * into the document block so the model states a limit instead of inventing a
+   * certainty: without it, a summary-only view of a meeting whose transcript was
+   * withheld reads as proof the thing was never discussed.
+   */
+  withheldFields?: string[];
 }
 
 export interface AnswerRequest {