@startsimpli/integrations 0.2.13 → 0.2.14

package/src/corpus/extract.ts

@@ -31,7 +31,7 @@
  */
 import { EXTRACTOR_VERSION, applyResolutions, mergeDrafts, reconcile } from './commitments';
 import { enforceScope } from './retrieval';
-import { outcomeSections } from './text';
+import { documentText, outcomeSections, documentParts, words } from './text';
 import type {
   Commitment,
   CommitmentApi,
@@ -44,8 +44,11 @@ import type {
   ExtractionResult,
   ResolutionClaim,
   SourceDocument,
+  VerificationRequest,
 } from './types';
 
+export { documentText };
+
 export interface ExtractCommitmentsOptions {
   /** How many documents to read before extracting. */
   documentLimit?: number;
@@ -53,12 +56,39 @@ export interface ExtractCommitmentsOptions {
   maxPages?: number;
   /** Characters of each document's text sent to the model. */
   maxCharsPerDocument?: number;
+  /**
+   * Characters of document text ONE call may carry, across every document in it.
+   *
+   * THE RIGHT AXIS, and `limit` is the wrong one. A summary is about 3,400
+   * characters and a forty-minute transcript is ten times that, so "four
+   * documents per call" means two completely different requests depending on
+   * whether `ingest_transcripts` happens to be on — and the tenant gateway closes
+   * a request at 60 seconds either way (bd startsim-768w.38.28). Budgeting the
+   * TEXT keeps one call one size whatever the corpus is made of, and the caller
+   * walks `nextOffset` for the rest.
+   */
+  maxCharsPerRun?: number;
 }
 
 const DEFAULTS: Required<ExtractCommitmentsOptions> = {
   documentLimit: 200,
   maxPages: 10,
   maxCharsPerDocument: 12_000,
+  // MEASURED, not chosen. Against claude-sonnet-5 over the real tandem corpus:
+  // one document (3,101 prompt characters) takes 19.6 seconds; TWO documents
+  // (7,909 characters) do not finish inside the provider client's 60-second
+  // timeout. Not the gateway's 60 seconds — the LLM client's own, a second wall
+  // nobody had measured. And because `extract` is deliberately wrapped so a
+  // provider outage costs the extras and not the list, blowing through it is
+  // SILENT: the run returns every rules-derived commitment and `fromModel: 0`,
+  // which reads exactly like "the model found nothing to add".
+  //
+  // So the budget is one document's worth of text. A sixteen-document sweep is
+  // therefore sixteen calls of about twenty seconds, which does not fit in a
+  // request at all and is why bd startsim-768w.38.28 (extraction belongs on a
+  // queue) is a PREREQUISITE rather than an adjacent nicety. Transcripts make
+  // each of those calls larger again.
+  maxCharsPerRun: 6_000,
 };
 
 // ---------------------------------------------------------------------------
@@ -104,9 +134,11 @@ const ACRONYM = /^[A-Z][A-Z0-9.\s,&-]*$/;
  * idempotent rather than merely usually idempotent.
  */
 export function rulesExtract(document: SourceDocument): CommitmentDraft[] {
-  const text = [document.body, ...document.sections.map((section) => section.text)]
-    .filter(Boolean)
-    .join('\n\n');
+  // EVERY piece of the document, summary included and de-duplicated. The
+  // outcome block lives in the summary — and only in the summary, because a
+  // transcript is speech and nobody speaks a markdown heading — so a version of
+  // this that read `body` alone produced ZERO on the day transcripts landed.
+  const text = documentParts(document).join('\n\n');
 
   const drafts: CommitmentDraft[] = [];
   for (const section of outcomeSections(text)) {
@@ -189,8 +221,11 @@ export function extractSystemPrompt(): string {
   return [
     'You read meeting records for one company and turn them into trackable items.',
     'You are given documents that ALREADY have some items extracted from them, listed under ALREADY_FOUND. Do NOT repeat those. Find what they missed.',
+    'A document may contain a curated summary AND the verbatim transcript of the same meeting. ALREADY_FOUND was taken from the summary, so the items worth reporting are the ones that were said out loud and never made it into the summary.',
     'An item is something a person now owes, has decided, needs, is at risk from, or has asked. It must be stated in the document — never inferred, never invented.',
-    'For every item, copy a short verbatim "quote" from the document it came from, and echo that document\'s exact id.',
+    'People in conversation say things they are not committing to. "We should probably look at that", "maybe next quarter", thinking aloud, reading an agenda, or describing what somebody else already did are NOT items.',
+    'BUT A VAGUE OPENING FOLLOWED BY A DECISION IS AN ITEM. "Somebody has to cancel that seat" — "put it on Megan" is one commitment with an owner, not two hedges. So is "we need to ask the city about the sidewalk" when nobody argues and the group moves on. Read the exchange, not the sentence: what matters is whether the thing ends up settled, and who ends up holding it.',
+    'For every item, copy a short verbatim "quote" from the document it came from, and echo that document\'s exact id. The quote must appear in the document CHARACTER FOR CHARACTER — it is checked, and an item whose quote is not found is discarded.',
     'Set "subject" to what the item is ABOUT — a matter or case number, a property, a client, a system, a person. Copy an identifier verbatim when the text has one.',
     'Set "owner" only to a name the document actually names. Leave it out otherwise.',
     'Set "dueAt" only when the document states a date. Never estimate one.',
@@ -227,6 +262,80 @@ export function renderExtractPrompt(input: {
   return [`DOCUMENTS (${input.documents.length}):`, blocks.join('\n\n')].join('\n');
 }
 
+// ---------------------------------------------------------------------------
+//  the verification prompt
+// ---------------------------------------------------------------------------
+
+/**
+ * THE PRICE OF READING MORE TEXT.
+ *
+ * Measured on the summaries alone, adding the model pass took recall 56.1% →
+ * 65.9% and precision 95.8% → 67.5%. A transcript is roughly ten times the text
+ * and it is text of a different KIND — verbatim speech is full of sentences that
+ * have the grammar of a commitment and none of the substance. "I'll take a look
+ * at that", said and forgotten, is indistinguishable from a commitment to any
+ * extractor working sentence by sentence. So more text does not make the model
+ * pass more precise; it makes it less precise, and the recall it buys is only
+ * worth having if something else pays the precision back.
+ *
+ * This is that something else. A SECOND, CHEAPER, ADVERSARIAL pass whose only
+ * job is to say no: given the record and a candidate, is this a thing a named
+ * person actually took on, and where exactly does it say so. Anything it will
+ * not stand behind with a span from the record is dropped.
+ *
+ * It is deliberately asked as a REFUSAL task rather than a scoring one. "Rate
+ * your confidence 0-1" produces a number nobody can act on and a threshold
+ * nobody can defend; "quote the sentence where this was agreed, or say it was
+ * not" produces evidence, and evidence can be checked in code.
+ */
+export function verifySystemPrompt(): string {
+  return [
+    'You are checking a list of proposed commitments against the meeting records they were taken from. You are the last check before these appear on somebody\'s to-do list.',
+    'For each candidate, decide ONE thing: did a specific person, in this document, actually take on this specific thing?',
+    'Confirm it ONLY if you can copy the span of the document that says so. The span must appear in the document character for character.',
+    // MEASURED, and the obvious loosening is the wrong call. This line used to
+    // read "an unowned item can still be real — judge whether the document
+    // states it as settled or required, not whether it names a person", which is
+    // a perfectly good argument: the `need` subtype exists precisely for a
+    // stated requirement with nobody on it. Run it and the verifier keeps 56% of
+    // candidates instead of 37%, and the whole run scores 66.1% recall at 65.5%
+    // precision instead of 65.3% at 75.5%. One point of recall for ten points of
+    // precision. Requiring somebody to be on the hook is what makes this pass
+    // worth its own model call; without it the verifier agrees with the
+    // extractor, which is not a check.
+    'Refuse it if: nobody owns it; it is a suggestion, a hypothetical, a hedge ("we should", "maybe", "at some point"); it describes something already finished; it is somebody reading an agenda or restating a topic; it is a scheduling note like when the next call is; or you cannot find where the document says it.',
+    'Refusing a real commitment costs one missing row. Confirming an invented one puts work on a person who never agreed to it and makes the whole list untrustworthy. When you are unsure, refuse.',
+    'Echo every candidate id back exactly once.',
+    'Respond with JSON only: {"verdicts":[{"id":string,"confirmed":boolean,"quote":string,"reason":string}]}',
+  ].join('\n');
+}
+
+/** ONE payload carrying every candidate and the records they claim to come from. */
+export function renderVerifyPrompt(input: VerificationRequest): string {
+  const documents = input.documents.map((document) =>
+    [`<document id="${document.id}">`, `title: ${document.title}`, '', document.text, '</document>'].join('\n'),
+  );
+  const candidates = input.candidates.map((candidate) =>
+    [
+      `<candidate id="${candidate.id}" document="${candidate.documentId}">`,
+      `kind: ${candidate.subtype}`,
+      `statement: ${candidate.title}`,
+      candidate.owner ? `claimed owner: ${candidate.owner}` : '',
+      `claimed evidence: ${candidate.quote}`,
+      '</candidate>',
+    ]
+      .filter(Boolean)
+      .join('\n'),
+  );
+  return [
+    `DOCUMENTS (${input.documents.length}):`,
+    documents.join('\n\n'),
+    '',
+    `CANDIDATES (${input.candidates.length}):`,
+    candidates.join('\n'),
+  ].join('\n');
+}
+
 // ---------------------------------------------------------------------------
 //  the pipeline
 // ---------------------------------------------------------------------------
@@ -258,7 +367,7 @@ export async function extractCommitments(
   deps: ExtractDeps,
   options: ExtractCommitmentsOptions = {},
 ): Promise<ExtractionResult> {
-  const { documentLimit, maxPages, maxCharsPerDocument } = { ...DEFAULTS, ...options };
+  const { documentLimit, maxPages, maxCharsPerDocument, maxCharsPerRun } = { ...DEFAULTS, ...options };
   const { corpus, extractor } = deps;
 
   // An empty scope grants nothing (`isInScope`). Refusing here rather than
@@ -277,7 +386,14 @@ export async function extractCommitments(
   // (org_id, entity_type, -created_at) index), so an offset means the same thing
   // between calls of one sweep.
   const offset = Math.max(0, request.offset ?? 0);
-  const documents = request.limit ? inScope.slice(offset, offset + request.limit) : inScope.slice(offset);
+  const asked = request.limit ? inScope.slice(offset, offset + request.limit) : inScope.slice(offset);
+  // AND THEN CUT AGAIN, BY SIZE. Whatever the caller asked for, one call carries
+  // a bounded amount of text — otherwise a corpus that grew a transcript
+  // overnight turns yesterday's working slice into today's gateway timeout, and
+  // the only symptom is a 504 with no clue in it. Always at least one document,
+  // because a single record larger than the whole budget still has to be
+  // processed rather than skipped forever.
+  const documents = takeWithinBudget(asked, maxCharsPerDocument, maxCharsPerRun);
   const consumed = offset + documents.length;
   const nextOffset = consumed < inScope.length ? consumed : null;
 
@@ -289,6 +405,10 @@ export async function extractCommitments(
     };
   }
 
+  const promptText = new Map(
+    documents.map((document) => [document.id, documentText(document, maxCharsPerDocument)]),
+  );
+
   const allowedIds = new Set(documents.map((document) => document.id));
 
   // 3. rules first, so the model can be told what not to repeat.
@@ -330,7 +450,7 @@ export async function extractCommitments(
         source: document.sourceLabel || document.source,
         occurredAt: document.occurredAt,
         participants: document.participants.map((party) => party.name),
-        text: documentText(document, maxCharsPerDocument),
+        text: promptText.get(document.id) ?? '',
         alreadyFound: foundByDocument.get(document.id) ?? [],
       })),
     });
@@ -339,9 +459,17 @@ export async function extractCommitments(
     draft = { items: [], resolutions: [] };
   }
 
-  const modelDrafts = normaliseItems(draft.items ?? [], allowedIds);
+  const proposed = normaliseItems(draft.items ?? [], allowedIds);
   const claims = normaliseResolutions(draft.resolutions ?? [], allowedIds);
 
+  // 4b. VERIFY the model's half. Not the rules half — see `verifyDrafts`.
+  const checked = await verifyDrafts(proposed, {
+    documents,
+    promptText,
+    extractor,
+  });
+  const modelDrafts = checked.kept;
+
   // 5. identity, dedupe within the run, then against what is stored.
   const groups = mergeDrafts([...ruleDrafts, ...modelDrafts]);
   const reconciled = reconcile(existing, groups, { scope: request.scope, documents });
@@ -367,6 +495,9 @@ export async function extractCommitments(
     nextOffset,
     fromRules: ruleDrafts.length,
     fromModel: modelDrafts.length,
+    ungrounded: checked.ungrounded,
+    unconfirmed: checked.unconfirmed,
+    verified: checked.verified,
     created: reconciled.created,
     merged: reconciled.merged,
     resolved: resolutions.resolved,
@@ -377,6 +508,203 @@ export async function extractCommitments(
   void matched;
 }
 
+// ---------------------------------------------------------------------------
+//  the verification stage
+// ---------------------------------------------------------------------------
+
+/**
+ * How much of a quote has to be found in the record for it to count as grounded.
+ *
+ * NOT an exact substring match, and that is a considered choice. Models
+ * normalise as they copy — a curly apostrophe becomes straight, a line break
+ * becomes a space, a speaker label gets dropped — and failing an otherwise
+ * correct item over a character of whitespace would delete real commitments to
+ * enforce a rule about punctuation. So the comparison is over WORDS, and the bar
+ * is that essentially all of the quoted words appear, in the record, in order.
+ */
+const GROUNDING_THRESHOLD = 0.9;
+
+/** The shortest quote worth checking. Below this, a match means nothing. */
+const MIN_QUOTE_WORDS = 4;
+
+/**
+ * And at least this many of them have to carry meaning. A four-word quote of
+ * "and then we were" matches every document ever written.
+ */
+const MIN_CONTENT_WORDS = 2;
+
+/**
+ * Is this span really in this document?
+ *
+ * FREE, DETERMINISTIC, AND IT RUNS FIRST. An item whose quote does not appear in
+ * the record is the signature of an invented commitment, and catching it costs
+ * no tokens and no time. Doing it before the model call also makes the model
+ * call cheaper, because it never sees the candidates that are already disproved.
+ */
+export function isGrounded(quote: string, text: string): boolean {
+  // The LENGTH gate counts words as written; the MATCH is over content words.
+  // Counting only content words for both rejected "the number they gave us is
+  // high" — a perfectly real seven-word quote — because five of its words are
+  // stopwords. A quote is short or not short in the language it was said in.
+  const written = quote.trim().split(/\s+/).filter(Boolean);
+  if (written.length < MIN_QUOTE_WORDS) return false;
+  const needle = words(quote);
+  if (needle.length < MIN_CONTENT_WORDS) return false;
+  const haystack = words(text);
+  if (haystack.length === 0) return false;
+
+  // Walk the record once, in order, consuming quote words as they appear. Order
+  // matters: the same words in a different order are a different sentence.
+  let cursor = 0;
+  let found = 0;
+  for (const word of needle) {
+    const at = haystack.indexOf(word, cursor);
+    if (at === -1) continue;
+    cursor = at + 1;
+    found += 1;
+  }
+  return found / needle.length >= GROUNDING_THRESHOLD;
+}
+
+interface VerifyContext {
+  documents: SourceDocument[];
+  promptText: Map<string, string>;
+  extractor: CorpusExtractorLlm;
+}
+
+interface VerifyOutcome {
+  kept: CommitmentDraft[];
+  /** Quoted something that is not in the record. */
+  ungrounded: number;
+  /** Grounded, but the verifier would not stand behind it. */
+  unconfirmed: number;
+  verified: boolean;
+}
+
+/**
+ * Two gates over the MODEL's candidates, and none over the rules pass.
+ *
+ * THE RULES PASS IS NOT VERIFIED, deliberately. Its quote is the vendor's own
+ * bullet, copied by a regular expression — there is nothing for a model to
+ * confirm that the code did not already guarantee, and asking anyway would spend
+ * tokens for a chance to lose a correct item. Its measured precision is 95.8%
+ * with 100% owner accuracy; the way to keep those numbers is to leave it alone.
+ *
+ * FAIL-CLOSED. When verification is offered and the call fails, every model
+ * candidate is dropped and the run says `verified: false`. That is the same rule
+ * the extract call already follows one level down — the deterministic half does
+ * not depend on the probabilistic half — applied to the check rather than to the
+ * proposal. An unverified model item is exactly the row this whole stage exists
+ * to keep off somebody's list.
+ */
+async function verifyDrafts(
+  proposed: CommitmentDraft[],
+  context: VerifyContext,
+): Promise<VerifyOutcome> {
+  if (proposed.length === 0) {
+    return { kept: [], ungrounded: 0, unconfirmed: 0, verified: Boolean(context.extractor.verify) };
+  }
+
+  // Gate 1 — grounding. No model, no cost.
+  const grounded: CommitmentDraft[] = [];
+  let ungrounded = 0;
+  for (const draft of proposed) {
+    if (isGrounded(draft.quote, context.promptText.get(draft.documentId) ?? '')) grounded.push(draft);
+    else ungrounded += 1;
+  }
+
+  const verify = context.extractor.verify;
+  if (!verify) {
+    // Nothing confirmed these. They are grounded, which is not nothing, and the
+    // result says `verified: false` so the number is never read as more.
+    return { kept: grounded, ungrounded, unconfirmed: 0, verified: false };
+  }
+  if (grounded.length === 0) {
+    return { kept: [], ungrounded, unconfirmed: 0, verified: true };
+  }
+
+  // Gate 2 — ONE call over every survivor, ids echoed.
+  const ids = new Map<string, CommitmentDraft>();
+  const candidates = grounded.map((draft, index) => {
+    const id = `c${index + 1}`;
+    ids.set(id, draft);
+    return {
+      id,
+      documentId: draft.documentId,
+      subtype: draft.subtype,
+      title: draft.title,
+      ...(draft.ownerName ? { owner: draft.ownerName } : {}),
+      quote: draft.quote,
+    };
+  });
+
+  const referenced = new Set(grounded.map((draft) => draft.documentId));
+  let verdicts: Array<{ id: string; confirmed: boolean; quote?: string }> = [];
+  try {
+    const response = await verify({
+      documents: context.documents
+        .filter((document) => referenced.has(document.id))
+        .map((document) => ({
+          id: document.id,
+          title: document.title,
+          text: context.promptText.get(document.id) ?? '',
+        })),
+      candidates,
+    });
+    verdicts = response?.verdicts ?? [];
+  } catch {
+    return { kept: [], ungrounded, unconfirmed: grounded.length, verified: false };
+  }
+
+  const confirmed = new Map<string, string>();
+  for (const verdict of verdicts) {
+    const id = String(verdict?.id ?? '');
+    if (!ids.has(id) || verdict?.confirmed !== true) continue;
+    confirmed.set(id, String(verdict.quote ?? '').trim());
+  }
+
+  const kept: CommitmentDraft[] = [];
+  for (const [id, draft] of ids) {
+    if (!confirmed.has(id)) continue;
+    // A verdict may CORRECT the span, and a corrected span is checked against
+    // the record too — a verifier that invents its evidence is not a check.
+    const offered = confirmed.get(id) ?? '';
+    const quote =
+      offered && isGrounded(offered, context.promptText.get(draft.documentId) ?? '')
+        ? offered
+        : draft.quote;
+    kept.push({ ...draft, quote });
+  }
+
+  return {
+    kept,
+    ungrounded,
+    // A candidate with NO verdict is unconfirmed, not confirmed. Silence from
+    // the verifier is not assent.
+    unconfirmed: grounded.length - kept.length,
+    verified: true,
+  };
+}
+
+/**
+ * As many of `documents` as fit in one call's text budget, always at least one.
+ */
+function takeWithinBudget(
+  documents: SourceDocument[],
+  maxCharsPerDocument: number,
+  maxCharsPerRun: number,
+): SourceDocument[] {
+  const taken: SourceDocument[] = [];
+  let spent = 0;
+  for (const document of documents) {
+    const size = Math.min(documentText(document, maxCharsPerDocument).length, maxCharsPerDocument);
+    if (taken.length > 0 && spent + size > maxCharsPerRun) break;
+    taken.push(document);
+    spent += size;
+  }
+  return taken;
+}
+
 /**
  * Read the corpus, PAST THE FIRST PAGE.
  *
@@ -402,12 +730,6 @@ async function readDocuments(
   return { documents: documents.slice(0, limit), matched };
 }
 
-function documentText(document: SourceDocument, maxChars: number): string {
-  const parts = [document.body, ...document.sections.map((section) => `## ${section.label}\n${section.text}`)];
-  const joined = parts.filter(Boolean).join('\n\n');
-  return joined.length > maxChars ? `${joined.slice(0, maxChars)}\n…[truncated]` : joined;
-}
-
 const SUBTYPES = new Set(['action', 'decision', 'need', 'risk', 'question']);
 const STATUSES = new Set<CommitmentStatus>(['open', 'done', 'blocked', 'dropped']);
 
@@ -476,6 +798,9 @@ function empty(extractor: CorpusExtractorLlm, _why: string): ExtractionResult {
     nextOffset: null,
     fromRules: 0,
     fromModel: 0,
+    ungrounded: 0,
+    unconfirmed: 0,
+    verified: Boolean(extractor.verify),
     created: 0,
     merged: 0,
     resolved: 0,

package/src/corpus/fixtures.ts

@@ -210,7 +210,15 @@ export const FIXTURE_TENANT_DOCUMENTS: TenantEntity[] = [
       // 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,
+      // THE ATTRIBUTE THE PIPELINE REALLY WRITES, and it used to be `transcript`
+      // here — which is why nothing caught the mapper collapsing `summary` into
+      // `body`. `granola.declare_canonical()` maps the `meeting_transcript`
+      // record onto the note's own document with `merge_into`, filling the
+      // canonical `body` attribute; the canonical schema declares `summary` and
+      // `body` as two fields for exactly this reason. A fixture that used a key
+      // the connector never emits is a fixture that proves the wrong thing —
+      // the whole lesson of bd startsim-768w.38.22, one field over.
+      body: GRANOLA_TRANSCRIPT,
     },
   }),
   row({

package/src/corpus/llm.ts

@@ -18,7 +18,12 @@
 import { extractJson, LLMService } from '@startsimpli/llm';
 
 import { answerSystemPrompt, renderAnswerPrompt } from './ask';
-import { extractSystemPrompt, renderExtractPrompt } from './extract';
+import {
+  extractSystemPrompt,
+  renderExtractPrompt,
+  renderVerifyPrompt,
+  verifySystemPrompt,
+} from './extract';
 import type {
   AnswerDraft,
   AnswerRequest,
@@ -27,6 +32,8 @@ import type {
   ExtractionDraft,
   ExtractionRequest,
   LlmDescription,
+  VerificationDraft,
+  VerificationRequest,
 } from './types';
 
 export interface CorpusLlmOptions {
@@ -256,6 +263,34 @@ export function parseExtractionDraft(raw: string): ExtractionDraft | null {
   };
 }
 
+/**
+ * Parse + shape-check the verifier's JSON.
+ *
+ * A MISSING VERDICT IS NOT A YES. Anything that is not an explicit `true`
+ * becomes `confirmed: false`, so a truncated response, a dropped id or a
+ * `"confirmed": "yes"` all fail closed. The caller drops what it is not told to
+ * keep, which means the failure modes of this parser all point at losing a real
+ * item rather than shipping an invented one.
+ */
+export function parseVerificationDraft(raw: string): VerificationDraft | null {
+  const extraction = extractJson(raw);
+  if (!extraction.success || !extraction.json || typeof extraction.json !== 'object') return null;
+  const json = extraction.json as Record<string, unknown>;
+  const verdicts = Array.isArray(json.verdicts) ? json.verdicts : null;
+  if (!verdicts) return null;
+  return {
+    verdicts: verdicts
+      .filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === 'object')
+      .map((entry) => ({
+        id: String(entry.id ?? '').trim(),
+        confirmed: entry.confirmed === true,
+        quote: typeof entry.quote === 'string' ? entry.quote : '',
+        reason: typeof entry.reason === 'string' ? entry.reason : '',
+      }))
+      .filter((verdict) => verdict.id !== ''),
+  };
+}
+
 /**
  * A `CorpusExtractorLlm` backed by `@startsimpli/llm`.
  *
@@ -325,5 +360,49 @@ export function createCorpusExtractor(options: CorpusLlmOptions = {}): CorpusExt
       lastModel = repair.model || lastModel;
       return parseExtractionDraft(repair.content) ?? { items: [], resolutions: [] };
     },
+
+    /**
+     * The precision half. ONE call over every candidate, ids echoed, same shape
+     * as `extract` — including the single JSON-repair retry, which is a
+     * correction of one request rather than a loop over items.
+     *
+     * IT THROWS RATHER THAN RETURNING NOTHING when the provider is unreachable.
+     * An empty verdict list and a failed call mean opposite things to the
+     * caller: the first is "the verifier refused everything", the second is "no
+     * check happened". Collapsing them would let a provider outage read as a
+     * corpus with no real commitments in it.
+     */
+    async verify(input: VerificationRequest): Promise<VerificationDraft> {
+      if (!service.isAvailable()) {
+        throw new Error(
+          'No LLM provider is reachable. Configure ANTHROPIC_API_KEY for this tenant.',
+        );
+      }
+
+      const system = verifySystemPrompt();
+      const user = renderVerifyPrompt(input);
+
+      const first = await service.chat(user, system);
+      lastModel = first.model || lastModel;
+      const parsed = parseVerificationDraft(first.content);
+      if (parsed) return parsed;
+
+      const repair = await service.chat(
+        [
+          'Your previous response was not valid JSON in the required shape.',
+          'Return ONLY the JSON object, with the key "verdicts".',
+          '',
+          'Your previous response was:',
+          first.content,
+        ].join('\n'),
+        system,
+      );
+      lastModel = repair.model || lastModel;
+      const repaired = parseVerificationDraft(repair.content);
+      if (repaired) return repaired;
+      // Unparseable twice is not a set of refusals — it is a verifier that did
+      // not answer, and the caller must be able to tell the difference.
+      throw new Error('The verification pass did not return a usable result.');
+    },
   };
 }

package/src/corpus/retrieval.ts

@@ -97,8 +97,16 @@ export function enforceScope<T extends { scope: CorpusScope }>(
 /** Half-life of the recency prior, in days. */
 const RECENCY_HALF_LIFE_DAYS = 120;
 
-/** Fields are weighted because a title hit means more than a transcript hit. */
-const FIELD_WEIGHTS = { title: 3, participants: 2, body: 1, sections: 0.6 } as const;
+/**
+ * Fields are weighted because a title hit means more than a transcript hit.
+ *
+ * `summary` sits between the title and the full text on purpose. It is the one
+ * piece of a record somebody (or something) already decided was the point, so a
+ * term appearing there is better evidence than the same term appearing once in
+ * forty minutes of verbatim speech — and once transcripts are ingested, `body`
+ * is verbatim speech.
+ */
+const FIELD_WEIGHTS = { title: 3, participants: 2, summary: 1.5, body: 1, sections: 0.6 } as const;
 
 function recencyWeight(occurredAt: string | null | undefined, now: number): number {
   if (!occurredAt) return 0.5; // undated: neither fresh nor stale, just less certain
@@ -125,7 +133,13 @@ function countHits(tokens: string[], terms: Set<string>): { hits: number; matche
  * WHY this record came back rather than making them open it to find out.
  */
 export function snippetFor(document: SourceDocument, terms: Set<string>, length = 220): string {
-  const haystacks = [document.body, ...document.sections.map((section) => section.text)];
+  // The summary is searched FIRST, so a citation card quotes the curated
+  // sentence rather than the moment somebody said the word out loud.
+  const haystacks = [
+    document.summary ?? '',
+    document.body,
+    ...document.sections.map((section) => section.text),
+  ];
   for (const text of haystacks) {
     if (!text) continue;
     const lower = text.toLowerCase();
@@ -189,6 +203,12 @@ export function rankDocuments(
       tokenize(document.participants.map((party) => `${party.name} ${party.email ?? ''}`).join(' ')),
       terms,
     );
+    // Scored SEPARATELY from `body`, and only when they are actually different
+    // strings — `body` falls back to the summary on a corpus that has never
+    // delivered a full text, and counting the same words twice there would
+    // silently re-weight every document on the tenant.
+    const summaryText = document.summary && document.summary !== document.body ? document.summary : '';
+    const summary = countHits(tokenize(summaryText), terms);
     const body = countHits(tokenize(document.body), terms);
     const sections = countHits(
       tokenize(document.sections.map((section) => section.text).join(' ')),
@@ -200,13 +220,17 @@ export function rankDocuments(
     const termScore =
       FIELD_WEIGHTS.title * Math.log1p(title.hits) +
       FIELD_WEIGHTS.participants * Math.log1p(participants.hits) +
+      FIELD_WEIGHTS.summary * Math.log1p(summary.hits) +
       FIELD_WEIGHTS.body * Math.log1p(body.hits) +
       FIELD_WEIGHTS.sections * Math.log1p(sections.hits);
 
     if (termScore <= 0) continue;
 
     const matched = [
-      ...new Set([...title.matched, ...participants.matched, ...body.matched, ...sections.matched]),
+      ...new Set([
+        ...title.matched, ...participants.matched, ...summary.matched,
+        ...body.matched, ...sections.matched,
+      ]),
     ];
     // Coverage rewards matching MORE OF the question rather than one term often.
     const coverage = matched.length / terms.size;