@startsimpli/integrations 0.2.16 → 0.2.18

package/src/corpus/extract.ts

@@ -27,7 +27,19 @@
  *
  * A PROVIDER OUTAGE COSTS THE EXTRAS, NOT THE LIST. Step 4 is wrapped: if the
  * model is unreachable the run still produces every commitment the vendor's own
- * structure carried, and says so in `fromModel: 0`.
+ * structure carried.
+ *
+ * AND IT SAYS SO, IN `modelFailure`, WHICH IS THE POINT. This used to be
+ * reported as `fromModel: 0` and nothing else, and `fromModel: 0` reads exactly
+ * like "the model found nothing to add". It did not: on the live tandem tenant
+ * the provider client's own sixty-second deadline was being blown on every slice
+ * of more than one document, so a rules-only pass was presented as a model pass
+ * for a week (bd startsim-768w.38.28). Degrading is fine. Degrading quietly is
+ * not, and every caller of this function now gets the reason.
+ *
+ * ONE CALL OF THIS FUNCTION IS ONE SLICE, NOT A SWEEP. A whole corpus does not
+ * fit in a request — one document is about twenty seconds — so the sweep is a
+ * durable, resumable, leased RUN in `./runs`, and this is the step it is made of.
  */
 import { EXTRACTOR_VERSION, applyResolutions, mergeDrafts, reconcile } from './commitments';
 import { enforceScope } from './retrieval';
@@ -41,6 +53,7 @@ import type {
   CorpusExtractorLlm,
   CorpusScope,
   ExtractionDraft,
+  ExtractionModelFailure,
   ExtractionResult,
   ResolutionClaim,
   SourceDocument,
@@ -442,6 +455,7 @@ export async function extractCommitments(
 
   // 4. ONE call, every document, ids echoed.
   let draft: ExtractionDraft = { items: [], resolutions: [] };
+  let modelFailure: ExtractionModelFailure | null = null;
   try {
     draft = await extractor.extract({
       documents: documents.map((document) => ({
@@ -454,9 +468,12 @@ export async function extractCommitments(
         alreadyFound: foundByDocument.get(document.id) ?? [],
       })),
     });
-  } catch {
-    // The deterministic half does not depend on the probabilistic half.
+  } catch (err) {
+    // The deterministic half does not depend on the probabilistic half — but the
+    // REPORT does depend on saying which half ran. Swallowing this into
+    // `fromModel: 0` is the bug that hid bd startsim-768w.38.28 for a week.
     draft = { items: [], resolutions: [] };
+    modelFailure = describeModelFailure('extract', err);
   }
 
   const proposed = normaliseItems(draft.items ?? [], allowedIds);
@@ -491,6 +508,7 @@ export async function extractCommitments(
 
   return {
     documentsProcessed: documents.length,
+    documentIds: documents.map((document) => document.id),
     totalDocuments: inScope.length,
     nextOffset,
     fromRules: ruleDrafts.length,
@@ -504,10 +522,48 @@ export async function extractCommitments(
     needsReview: resolutions.needsReview,
     droppedOutOfScope: dropped.length,
     provider: extractor.describe(),
+    // The PROPOSING call's failure is the more important one to report, because
+    // it is the one that empties the list; a verifier that did not answer is
+    // reported when the proposer did.
+    modelFailure: modelFailure ?? checked.failure,
   };
   void matched;
 }
 
+/**
+ * Name the failure, and separate a blown deadline from everything else.
+ *
+ * The distinction is operational, not cosmetic: a timeout is fixed by giving the
+ * run more time or less text, and a 401 or a 429 is not. `@startsimpli/llm`
+ * raises `LLMProviderError` with `code: 'TIMEOUT'` when its own AbortController
+ * fires, so the code is read first and the message only as a fallback — a caller
+ * that wrapped the error keeps the sentence even when it loses the class.
+ */
+function describeModelFailure(stage: 'extract' | 'verify', err: unknown): ExtractionModelFailure {
+  const raw = (err as { message?: string })?.message || '';
+  // A provider whose error body is not the shape the client expects arrives as
+  // the literal string "Unknown error", which is not a report — it is the same
+  // silence in a different font. The status code is the only thing that
+  // distinguishes a retired model (404) from a bad key (401) from a rate limit
+  // (429), so when the message says nothing the status says it instead. Found
+  // by this very field: a local base-URL override made every call 404, and the
+  // run said so within a second instead of reporting `fromModel: 0`.
+  const status = (err as { statusCode?: number; status?: number })?.statusCode
+    ?? (err as { status?: number })?.status;
+  const useless = !raw || /^unknown error$/i.test(raw);
+  const message = useless
+    ? `The model did not answer${status ? ` (HTTP ${status})` : ''}.`
+    : status && !raw.includes(String(status))
+      ? `${raw} (HTTP ${status})`
+      : raw;
+  const code = String((err as { code?: unknown })?.code ?? '');
+  const timedOut =
+    code === 'TIMEOUT' ||
+    (err as { name?: string })?.name === 'AbortError' ||
+    /timed?\s*out|timeout|aborted/i.test(message);
+  return { stage, message, timedOut };
+}
+
 // ---------------------------------------------------------------------------
 //  the verification stage
 // ---------------------------------------------------------------------------
@@ -579,6 +635,16 @@ interface VerifyOutcome {
   /** Grounded, but the verifier would not stand behind it. */
   unconfirmed: number;
   verified: boolean;
+  /**
+   * WHY the check did not happen, when it did not.
+   *
+   * `verified: false` already says a check did not happen, and it is the field
+   * the screen reads — but it cannot distinguish "this deployment has no
+   * verifier" from "the verifier timed out and every model candidate was
+   * dropped", and those are opposite instructions to whoever is looking at a
+   * suddenly shorter list.
+   */
+  failure: ExtractionModelFailure | null;
 }
 
 /**
@@ -602,7 +668,10 @@ async function verifyDrafts(
   context: VerifyContext,
 ): Promise<VerifyOutcome> {
   if (proposed.length === 0) {
-    return { kept: [], ungrounded: 0, unconfirmed: 0, verified: Boolean(context.extractor.verify) };
+    return {
+      kept: [], ungrounded: 0, unconfirmed: 0,
+      verified: Boolean(context.extractor.verify), failure: null,
+    };
   }
 
   // Gate 1 — grounding. No model, no cost.
@@ -617,10 +686,10 @@ async function verifyDrafts(
   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 };
+    return { kept: grounded, ungrounded, unconfirmed: 0, verified: false, failure: null };
   }
   if (grounded.length === 0) {
-    return { kept: [], ungrounded, unconfirmed: 0, verified: true };
+    return { kept: [], ungrounded, unconfirmed: 0, verified: true, failure: null };
   }
 
   // Gate 2 — ONE call over every survivor, ids echoed.
@@ -652,8 +721,11 @@ async function verifyDrafts(
       candidates,
     });
     verdicts = response?.verdicts ?? [];
-  } catch {
-    return { kept: [], ungrounded, unconfirmed: grounded.length, verified: false };
+  } catch (err) {
+    return {
+      kept: [], ungrounded, unconfirmed: grounded.length, verified: false,
+      failure: describeModelFailure('verify', err),
+    };
   }
 
   const confirmed = new Map<string, string>();
@@ -683,6 +755,7 @@ async function verifyDrafts(
     // the verifier is not assent.
     unconfirmed: grounded.length - kept.length,
     verified: true,
+    failure: null,
   };
 }
 
@@ -794,6 +867,7 @@ function empty(extractor: CorpusExtractorLlm, _why: string): ExtractionResult {
   void _why;
   return {
     documentsProcessed: 0,
+    documentIds: [],
     totalDocuments: 0,
     nextOffset: null,
     fromRules: 0,
@@ -807,6 +881,9 @@ function empty(extractor: CorpusExtractorLlm, _why: string): ExtractionResult {
     needsReview: [],
     droppedOutOfScope: 0,
     provider: extractor.describe(),
+    // Nothing was asked of the model, so nothing failed. `null` here and
+    // `fromModel: 0` together mean "no work", which is the truth.
+    modelFailure: null,
   };
 }
 

package/src/corpus/fixtures.ts

@@ -908,3 +908,37 @@ export function createFixtureLlm(): import('./types').CorpusLlm {
     },
   };
 }
+
+/**
+ * An `ExtractionRunStore` in memory, with the tenant's own round-trip in the
+ * middle of it (bd startsim-768w.38.28).
+ *
+ * IT SERIALISES. The real store writes the record into `Entity.data` as JSON and
+ * reads it back through the same snake_case↔camelCase transform every other row
+ * goes through, so a fixture that handed the same object back would test nothing
+ * about the one thing that actually breaks: a field that does not survive
+ * storage. This one stringifies on write and parses on read, so a run whose
+ * cursor or totals do not round-trip fails here rather than on a live tenant
+ * halfway through a six-minute sweep.
+ */
+export function createFixtureRunStore(
+  initial?: import('./types').ExtractionRun | null,
+): import('./types').ExtractionRunStore & { writes: number } {
+  let stored = initial ? JSON.stringify(initial) : null;
+  const store = {
+    writes: 0,
+    async readRun() {
+      return stored ? (JSON.parse(stored) as import('./types').ExtractionRun) : null;
+    },
+    async writeRun(run: import('./types').ExtractionRun) {
+      store.writes += 1;
+      // `adopted` is a fact about a request, not about the run, and it must not
+      // survive into the record — a stored `adopted: true` would make every
+      // later reader think a stalled sweep had just been taken over.
+      const { adopted: _adopted, ...durable } = run;
+      stored = JSON.stringify(durable);
+      return JSON.parse(stored) as import('./types').ExtractionRun;
+    },
+  };
+  return store;
+}

package/src/corpus/index.ts

@@ -19,8 +19,14 @@ export type {
   CommitmentTrackerApi,
   CorpusExtractorLlm,
   ExtractionDraft,
+  ExtractionModelFailure,
   ExtractionRequest,
   ExtractionResult,
+  ExtractionRun,
+  ExtractionRunStatus,
+  ExtractionRunStore,
+  ExtractionRunSummary,
+  ExtractionRunTotals,
   ResolutionClaim,
   AskRequest,
   AskResult,
@@ -46,9 +52,12 @@ export type {
 
 export {
   DEFAULT_PARTICIPANT_EDGES,
+  DEFAULT_RUN_KEY,
   DEFAULT_TYPE_KEYS,
   indexParticipants,
   commitmentToEntity,
+  extractionRunToEntity,
+  toExtractionRun,
   mergeParticipants,
   moneyEventAsDocument,
   toCommitment,
@@ -91,6 +100,25 @@ export {
 } from './extract';
 export type { ExtractCommitmentsOptions, ExtractDeps, ExtractRequest } from './extract';
 
+// Extraction as a JOB — durable, leased, resumable (bd startsim-768w.38.28).
+export {
+  EMPTY_TOTALS,
+  advanceExtractionRun,
+  defaultDriverId,
+  driveExtractionRun,
+  isLeaseLive,
+  isStalled,
+  newExtractionRun,
+  runCoverage,
+  runProgress,
+  startExtractionRun,
+} from './runs';
+export type {
+  ExtractionRunDeps,
+  ExtractionRunOptions,
+  StartExtractionRunRequest,
+} from './runs';
+
 export {
   applyResolutions,
   commitmentIdentity,
@@ -117,6 +145,7 @@ export {
   createFixtureCorpusHttp,
   createFixtureExtractor,
   createFixtureLlm,
+  createFixtureRunStore,
   FIXTURE_DOCUMENTS,
   FIXTURE_MONEY_EVENTS,
   FIXTURE_ORG,

package/src/corpus/llm.ts

@@ -43,10 +43,34 @@ export interface CorpusLlmOptions {
   model?: string;
   temperature?: number;
   maxTokens?: number;
+  /**
+   * Per-request deadline, in milliseconds.
+   *
+   * THE SECOND SIXTY-SECOND WALL, and for a week nobody knew it was there. The
+   * provider clients in `@startsimpli/llm` default to 60,000ms, and against
+   * claude-sonnet-5 over the real tandem corpus one document takes 19.6 seconds
+   * while two do not finish at all. Because `extract` is wrapped so a provider
+   * outage costs the extras and not the list, blowing it was SILENT.
+   *
+   * A QUEUED RUN CAN AFFORD MORE TIME THAN A REQUEST CAN. That is most of the
+   * point of putting extraction on a job: nothing downstream is waiting on a
+   * socket, so the deadline can be set by how long the work honestly takes
+   * rather than by what a gateway will tolerate. Passed per call so the same
+   * process can hold a short deadline for an interactive Ask and a long one for
+   * a background sweep; `LLM_TIMEOUT_MS` remains the deployment-wide override.
+   */
+  timeoutMs?: number;
   /** Injectable environment, so the configured-model lookup is testable. */
   env?: Record<string, string | undefined>;
 }
 
+/** The deadline this call should carry, if any. */
+function callOptions(options: CorpusLlmOptions): { timeout?: number } | undefined {
+  const env = options.env ?? (typeof process !== 'undefined' ? process.env : {});
+  const timeout = options.timeoutMs ?? (Number(env.LLM_TIMEOUT_MS) || undefined);
+  return timeout ? { timeout } : undefined;
+}
+
 /**
  * The model this deployment CONFIGURED for a provider, from its own environment.
  *
@@ -176,6 +200,7 @@ export function createCorpusLlm(options: CorpusLlmOptions = {}): CorpusLlm {
 
   let lastModel = options.model ?? '';
   const env = options.env ?? (typeof process !== 'undefined' ? process.env : {});
+  const call = callOptions(options);
 
   const describe = (): LlmDescription => {
     const available = service.getAvailableProviders();
@@ -206,7 +231,7 @@ export function createCorpusLlm(options: CorpusLlmOptions = {}): CorpusLlm {
       const system = answerSystemPrompt(input.mode);
       const user = renderAnswerPrompt(input);
 
-      const first = await service.chat(user, system);
+      const first = await service.chat(user, system, call);
       lastModel = first.model || lastModel;
       const parsed = parseAnswerDraft(first.content);
       if (parsed) return parsed;
@@ -222,6 +247,7 @@ export function createCorpusLlm(options: CorpusLlmOptions = {}): CorpusLlm {
           first.content,
         ].join('\n'),
         system,
+        call,
       );
       lastModel = repair.model || lastModel;
       const repaired = parseAnswerDraft(repair.content);
@@ -317,6 +343,7 @@ export function createCorpusExtractor(options: CorpusLlmOptions = {}): CorpusExt
 
   let lastModel = options.model ?? '';
   const env = options.env ?? (typeof process !== 'undefined' ? process.env : {});
+  const call = callOptions(options);
 
   return {
     describe(): LlmDescription {
@@ -342,7 +369,7 @@ export function createCorpusExtractor(options: CorpusLlmOptions = {}): CorpusExt
       const system = extractSystemPrompt();
       const user = renderExtractPrompt(input);
 
-      const first = await service.chat(user, system);
+      const first = await service.chat(user, system, call);
       lastModel = first.model || lastModel;
       const parsed = parseExtractionDraft(first.content);
       if (parsed) return parsed;
@@ -356,6 +383,7 @@ export function createCorpusExtractor(options: CorpusLlmOptions = {}): CorpusExt
           first.content,
         ].join('\n'),
         system,
+        call,
       );
       lastModel = repair.model || lastModel;
       return parseExtractionDraft(repair.content) ?? { items: [], resolutions: [] };
@@ -382,7 +410,7 @@ export function createCorpusExtractor(options: CorpusLlmOptions = {}): CorpusExt
       const system = verifySystemPrompt();
       const user = renderVerifyPrompt(input);
 
-      const first = await service.chat(user, system);
+      const first = await service.chat(user, system, call);
       lastModel = first.model || lastModel;
       const parsed = parseVerificationDraft(first.content);
       if (parsed) return parsed;
@@ -396,6 +424,7 @@ export function createCorpusExtractor(options: CorpusLlmOptions = {}): CorpusExt
           first.content,
         ].join('\n'),
         system,
+        call,
       );
       lastModel = repair.model || lastModel;
       const repaired = parseVerificationDraft(repair.content);