@claritylabs/cl-sdk 0.17.0 → 0.17.1

package/dist/index.mjs

@@ -169,7 +169,14 @@ function createPipelineContext(opts) {
   let latest = opts.resumeFrom;
   const completedPhases = /* @__PURE__ */ new Set();
   if (opts.resumeFrom) {
-    completedPhases.add(opts.resumeFrom.phase);
+    const phaseIndex = opts.phaseOrder?.indexOf(opts.resumeFrom.phase) ?? -1;
+    if (phaseIndex >= 0 && opts.phaseOrder) {
+      for (const phase of opts.phaseOrder.slice(0, phaseIndex + 1)) {
+        completedPhases.add(phase);
+      }
+    } else {
+      completedPhases.add(opts.resumeFrom.phase);
+    }
   }
   return {
     id: opts.id,
@@ -1708,6 +1715,53 @@ async function runExtractor(params) {
   };
 }
 
+// src/extraction/memory.ts
+function isMemoryRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readMemoryRecord(memory, key) {
+  const value = memory.get(key);
+  return isMemoryRecord(value) ? value : void 0;
+}
+function readRecordValue(record, key) {
+  return record?.[key];
+}
+function readRecordArray(record, key) {
+  const value = readRecordValue(record, key);
+  return Array.isArray(value) ? value : void 0;
+}
+function getCarrierInfo(memory) {
+  return readMemoryRecord(memory, "carrier_info");
+}
+function getNamedInsured(memory) {
+  return readMemoryRecord(memory, "named_insured");
+}
+function getCoverageLimits(memory) {
+  return readMemoryRecord(memory, "coverage_limits");
+}
+function getCoverageLimitCoverages(memory) {
+  return readRecordArray(getCoverageLimits(memory), "coverages") ?? [];
+}
+function getSectionsPayload(memory) {
+  return readMemoryRecord(memory, "sections");
+}
+function getSections(memory) {
+  return readRecordArray(getSectionsPayload(memory), "sections");
+}
+function getDefinitionsPayload(memory) {
+  return readMemoryRecord(memory, "definitions");
+}
+function getDefinitions(memory) {
+  return readRecordArray(getDefinitionsPayload(memory), "definitions");
+}
+function getCoveredReasonsPayload(memory) {
+  return readMemoryRecord(memory, "covered_reasons");
+}
+function getCoveredReasons(memory) {
+  const payload = getCoveredReasonsPayload(memory);
+  return readRecordArray(payload, "coveredReasons") ?? readRecordArray(payload, "covered_reasons");
+}
+
 // src/extraction/promote.ts
 function getDeclarationFields(doc) {
   const decl = doc.declarations;
@@ -1734,20 +1788,29 @@ function findRawString(raw, keys) {
   }
   return void 0;
 }
+function promoteRawFields(raw, mappings) {
+  for (const { from, to } of mappings) {
+    if (!raw[to] && raw[from]) {
+      raw[to] = raw[from];
+    }
+    delete raw[from];
+  }
+}
+function findRawOrDeclarationValue(raw, fields, lookup) {
+  return (lookup.rawKey ? raw[lookup.rawKey] : void 0) || findFieldValue(fields, lookup.patterns, lookup.reject);
+}
+function promoteRawOrDeclarationString(raw, fields, targetKey, rawKeys, lookup) {
+  if (raw[targetKey]) return;
+  const value = findRawString(raw, rawKeys) ?? findFieldValue(fields, lookup.patterns, lookup.reject);
+  if (value) raw[targetKey] = value;
+}
 function promoteCarrierFields(doc) {
   const raw = doc;
-  if (!raw.carrierNaicNumber && raw.naicNumber) {
-    raw.carrierNaicNumber = raw.naicNumber;
-  }
-  if (!raw.carrierAmBestRating && raw.amBestRating) {
-    raw.carrierAmBestRating = raw.amBestRating;
-  }
-  if (!raw.carrierAdmittedStatus && raw.admittedStatus) {
-    raw.carrierAdmittedStatus = raw.admittedStatus;
-  }
-  delete raw.naicNumber;
-  delete raw.amBestRating;
-  delete raw.admittedStatus;
+  promoteRawFields(raw, [
+    { from: "naicNumber", to: "carrierNaicNumber" },
+    { from: "amBestRating", to: "carrierAmBestRating" },
+    { from: "admittedStatus", to: "carrierAdmittedStatus" }
+  ]);
   if (!raw.insurer && raw.carrierLegalName) {
     raw.insurer = {
       legalName: raw.carrierLegalName,
@@ -1788,12 +1851,21 @@ var BROKER_ADDRESS_PATTERNS = ["brokerAddress", "agentAddress", "producerAddress
 function promoteBroker(doc) {
   const raw = doc;
   const fields = getDeclarationFields(doc);
-  const brokerAgency = raw.brokerAgency || findFieldValue(fields, BROKER_NAME_PATTERNS);
-  const brokerContact = raw.brokerContactName || findFieldValue(fields, BROKER_CONTACT_PATTERNS);
-  const brokerLicense = raw.brokerLicenseNumber || findFieldValue(fields, BROKER_LICENSE_PATTERNS);
-  const brokerPhone = findFieldValue(fields, BROKER_PHONE_PATTERNS);
-  const brokerEmail = findFieldValue(fields, BROKER_EMAIL_PATTERNS);
-  const brokerAddress = findFieldValue(fields, BROKER_ADDRESS_PATTERNS);
+  const brokerAgency = findRawOrDeclarationValue(raw, fields, {
+    rawKey: "brokerAgency",
+    patterns: BROKER_NAME_PATTERNS
+  });
+  const brokerContact = findRawOrDeclarationValue(raw, fields, {
+    rawKey: "brokerContactName",
+    patterns: BROKER_CONTACT_PATTERNS
+  });
+  const brokerLicense = findRawOrDeclarationValue(raw, fields, {
+    rawKey: "brokerLicenseNumber",
+    patterns: BROKER_LICENSE_PATTERNS
+  });
+  const brokerPhone = findRawOrDeclarationValue(raw, fields, { patterns: BROKER_PHONE_PATTERNS });
+  const brokerEmail = findRawOrDeclarationValue(raw, fields, { patterns: BROKER_EMAIL_PATTERNS });
+  const brokerAddress = findRawOrDeclarationValue(raw, fields, { patterns: BROKER_ADDRESS_PATTERNS });
   if (brokerAgency) raw.brokerAgency = brokerAgency;
   if (brokerContact) raw.brokerContactName = brokerContact;
   if (brokerLicense) raw.brokerLicenseNumber = brokerLicense;
@@ -2169,20 +2241,27 @@ function taxFeeKey(item) {
     item.type ?? ""
   ].join("|");
 }
+function taxFeeItemFromField(field) {
+  const type = taxFeeType(field.field);
+  return {
+    name: titleizeFieldName(field.field),
+    amount: absorbNegative(field.value),
+    ...type ? { type } : {}
+  };
+}
 function absorbNegative(value) {
   return value.replace(/^-\s*/, "").replace(/^\(\s*(.*?)\s*\)$/, "$1");
 }
 function promotePremium(doc) {
   const raw = doc;
   const fields = getDeclarationFields(doc);
-  if (!raw.premium) {
-    const premium = findRawString(raw, PREMIUM_RAW_KEYS) ?? findFieldValue(fields, PREMIUM_PATTERNS, (field) => isTaxOrFeeField(field.field));
-    if (premium) raw.premium = premium;
-  }
-  if (!raw.totalCost) {
-    const totalCost = findRawString(raw, TOTAL_COST_RAW_KEYS) ?? findFieldValue(fields, TOTAL_COST_PATTERNS);
-    if (totalCost) raw.totalCost = totalCost;
-  }
+  promoteRawOrDeclarationString(raw, fields, "premium", PREMIUM_RAW_KEYS, {
+    patterns: PREMIUM_PATTERNS,
+    reject: (field) => isTaxOrFeeField(field.field)
+  });
+  promoteRawOrDeclarationString(raw, fields, "totalCost", TOTAL_COST_RAW_KEYS, {
+    patterns: TOTAL_COST_PATTERNS
+  });
   if (typeof raw.premium === "string") raw.premium = absorbNegative(raw.premium);
   if (typeof raw.totalCost === "string") raw.totalCost = absorbNegative(raw.totalCost);
 }
@@ -2200,11 +2279,7 @@ function synthesizeTaxesAndFees(doc) {
     if (!field.value?.trim()) continue;
     if (!isTaxOrFeeField(field.field)) continue;
     if (isTotalCostField(field.field)) continue;
-    const item = {
-      name: titleizeFieldName(field.field),
-      amount: absorbNegative(field.value),
-      ...taxFeeType(field.field) ? { type: taxFeeType(field.field) } : {}
-    };
+    const item = taxFeeItemFromField(field);
     byKey.set(taxFeeKey(item), item);
   }
   if (byKey.size > 0) {
@@ -2224,43 +2299,47 @@ function promoteExtractedFields(doc) {
 
 // src/extraction/assembler.ts
 function assembleDocument(documentId, documentType, memory) {
-  const carrier = memory.get("carrier_info");
-  const insured = memory.get("named_insured");
-  const coverages = memory.get("coverage_limits");
-  const endorsements = memory.get("endorsements");
-  const exclusions = memory.get("exclusions");
-  const conditions = memory.get("conditions");
-  const premium = memory.get("premium_breakdown");
-  const declarations = memory.get("declarations");
-  const lossHistory = memory.get("loss_history");
-  const sections = memory.get("sections");
-  const supplementary = memory.get("supplementary");
-  const formInventory = memory.get("form_inventory");
-  const definitions = memory.get("definitions");
-  const coveredReasons = memory.get("covered_reasons");
-  const classify = memory.get("classify");
+  const carrier = getCarrierInfo(memory);
+  const insured = getNamedInsured(memory);
+  const coverages = getCoverageLimits(memory);
+  const endorsements = readMemoryRecord(memory, "endorsements");
+  const exclusions = readMemoryRecord(memory, "exclusions");
+  const conditions = readMemoryRecord(memory, "conditions");
+  const premium = readMemoryRecord(memory, "premium_breakdown");
+  const declarations = readMemoryRecord(memory, "declarations");
+  const lossHistory = readMemoryRecord(memory, "loss_history");
+  const supplementary = readMemoryRecord(memory, "supplementary");
+  const formInventory = readMemoryRecord(memory, "form_inventory");
+  const classify = readMemoryRecord(memory, "classify");
+  const lossPayees = readRecordArray(insured, "lossPayees");
+  const mortgageHolders = readRecordArray(insured, "mortgageHolders");
   const base = {
     id: documentId,
-    carrier: carrier?.carrierName ?? "Unknown",
-    insuredName: insured?.insuredName ?? "Unknown",
-    coverages: coverages?.coverages ?? [],
-    policyTypes: classify?.policyTypes,
+    carrier: readRecordValue(carrier, "carrierName") ?? "Unknown",
+    insuredName: readRecordValue(insured, "insuredName") ?? "Unknown",
+    coverages: getCoverageLimitCoverages(memory),
+    policyTypes: readRecordValue(classify, "policyTypes"),
     ...sanitizeNulls(carrier ?? {}),
     ...sanitizeNulls(insured ?? {}),
     // Map named_insured extractor's loss payees/mortgage holders to EndorsementParty shape
-    ...Array.isArray(insured?.lossPayees) && insured.lossPayees.length > 0 ? { lossPayees: insured.lossPayees.map((lp) => ({ ...lp, role: "loss_payee" })) } : {},
-    ...Array.isArray(insured?.mortgageHolders) && insured.mortgageHolders.length > 0 ? { mortgageHolders: insured.mortgageHolders.map((mh) => ({ ...mh, role: "mortgage_holder" })) } : {},
+    ...lossPayees && lossPayees.length > 0 ? { lossPayees: lossPayees.map((lp) => ({ ...lp, role: "loss_payee" })) } : {},
+    ...mortgageHolders && mortgageHolders.length > 0 ? {
+      mortgageHolders: mortgageHolders.map((mh) => ({
+        ...mh,
+        role: "mortgage_holder"
+      }))
+    } : {},
     ...sanitizeNulls(coverages ?? {}),
     ...sanitizeNulls(premium ?? {}),
     ...sanitizeNulls(supplementary ?? {}),
-    supplementaryFacts: supplementary?.auxiliaryFacts,
-    endorsements: endorsements?.endorsements,
-    exclusions: exclusions?.exclusions,
-    conditions: conditions?.conditions,
-    sections: sections?.sections,
-    formInventory: formInventory?.forms,
-    definitions: definitions?.definitions,
-    coveredReasons: coveredReasons?.coveredReasons ?? coveredReasons?.covered_reasons,
+    supplementaryFacts: readRecordValue(supplementary, "auxiliaryFacts"),
+    endorsements: readRecordValue(endorsements, "endorsements"),
+    exclusions: readRecordValue(exclusions, "exclusions"),
+    conditions: readRecordValue(conditions, "conditions"),
+    sections: getSections(memory),
+    formInventory: readRecordValue(formInventory, "forms"),
+    definitions: getDefinitions(memory),
+    coveredReasons: getCoveredReasons(memory),
     declarations: declarations ? sanitizeNulls(declarations) : void 0,
     ...sanitizeNulls(lossHistory ?? {})
   };
@@ -2269,21 +2348,21 @@ function assembleDocument(documentId, documentType, memory) {
     doc = {
       ...base,
       type: "policy",
-      policyNumber: carrier?.policyNumber ?? insured?.policyNumber ?? "Unknown",
-      effectiveDate: carrier?.effectiveDate ?? insured?.effectiveDate ?? "Unknown",
-      expirationDate: carrier?.expirationDate,
-      policyTermType: carrier?.policyTermType
+      policyNumber: readRecordValue(carrier, "policyNumber") ?? readRecordValue(insured, "policyNumber") ?? "Unknown",
+      effectiveDate: readRecordValue(carrier, "effectiveDate") ?? readRecordValue(insured, "effectiveDate") ?? "Unknown",
+      expirationDate: readRecordValue(carrier, "expirationDate"),
+      policyTermType: readRecordValue(carrier, "policyTermType")
     };
   } else {
     doc = {
       ...base,
       type: "quote",
-      quoteNumber: carrier?.quoteNumber ?? "Unknown",
-      proposedEffectiveDate: carrier?.proposedEffectiveDate,
-      proposedExpirationDate: carrier?.proposedExpirationDate,
-      subjectivities: coverages?.subjectivities,
-      underwritingConditions: coverages?.underwritingConditions,
-      premiumBreakdown: premium?.premiumBreakdown
+      quoteNumber: readRecordValue(carrier, "quoteNumber") ?? "Unknown",
+      proposedEffectiveDate: readRecordValue(carrier, "proposedEffectiveDate"),
+      proposedExpirationDate: readRecordValue(carrier, "proposedExpirationDate"),
+      subjectivities: readRecordValue(coverages, "subjectivities"),
+      underwritingConditions: readRecordValue(coverages, "underwritingConditions"),
+      premiumBreakdown: readRecordValue(premium, "premiumBreakdown")
     };
   }
   promoteExtractedFields(doc);
@@ -2385,6 +2464,23 @@ ${block}`;
 }
 
 // src/extraction/formatter.ts
+var LONG_CONTENT_THRESHOLD = 1200;
+function shouldFormatContent(text) {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return false;
+  if (trimmed.length >= LONG_CONTENT_THRESHOLD) return true;
+  if (/```|~~~|<br\s*\/?>/i.test(trimmed)) return true;
+  if (/(^|\s)(\*\*|__|`)/.test(trimmed)) return true;
+  if (/!?\[[^\]]+\]\([^)]+\)/.test(trimmed)) return true;
+  if (/^\s{0,3}#{1,6}\s*\S/m.test(trimmed)) return true;
+  if (/^\s{0,6}(?:[-*+]|\d+[.)])\s+\S/m.test(trimmed)) return true;
+  if (/\t|[^\S\r\n]{3,}|\n{3,}|[ \t]+$/m.test(text)) return true;
+  const lines = trimmed.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (lines.some((line) => (line.match(/\|/g)?.length ?? 0) >= 2)) return true;
+  const spaceAlignedRows = lines.filter((line) => /\S\s{2,}\S\s{2,}\S/.test(line));
+  if (spaceAlignedRows.length >= 2) return true;
+  return false;
+}
 function collectContentFields(doc) {
   const entries = [];
   let id = 0;
@@ -2488,7 +2584,7 @@ function applyFormattedContent(doc, entries, formatted) {
 }
 var MAX_ENTRIES_PER_BATCH = 20;
 async function formatDocumentContent(doc, generateText, options) {
-  const entries = collectContentFields(doc);
+  const entries = collectContentFields(doc).filter((entry) => shouldFormatContent(entry.text));
   const totalUsage = { inputTokens: 0, outputTokens: 0 };
   if (entries.length === 0) {
     return { document: doc, usage: totalUsage };
@@ -2565,11 +2661,22 @@ function chunkDocument(doc) {
     if (policyTypesStr) base.policyTypes = policyTypesStr;
     return base;
   }
-  chunks.push({
-    id: `${docId}:carrier_info:0`,
-    documentId: docId,
-    type: "carrier_info",
-    text: [
+  function lines(values) {
+    return values.filter(Boolean).join("\n");
+  }
+  function pushChunk(idSuffix, type, text, metadata) {
+    chunks.push({
+      id: `${docId}:${idSuffix}`,
+      documentId: docId,
+      type,
+      text,
+      metadata: stringMetadata(metadata)
+    });
+  }
+  pushChunk(
+    "carrier_info:0",
+    "carrier_info",
+    lines([
       `Carrier: ${doc.carrier}`,
       doc.carrierLegalName ? `Legal Name: ${doc.carrierLegalName}` : null,
       doc.carrierNaicNumber ? `NAIC: ${doc.carrierNaicNumber}` : null,
@@ -2586,94 +2693,83 @@ function chunkDocument(doc) {
       doc.isPackage != null ? `Package: ${doc.isPackage ? "Yes" : "No"}` : null,
       doc.security ? `Security: ${doc.security}` : null,
       doc.policyTypes?.length ? `Policy Types: ${doc.policyTypes.join(", ")}` : null
-    ].filter(Boolean).join("\n"),
-    metadata: stringMetadata({ carrier: doc.carrier, documentType: doc.type })
-  });
+    ]),
+    { carrier: doc.carrier, documentType: doc.type }
+  );
   if (doc.summary) {
-    chunks.push({
-      id: `${docId}:declaration:summary`,
-      documentId: docId,
-      type: "declaration",
-      text: `Policy Summary: ${doc.summary}`,
-      metadata: stringMetadata({ documentType: doc.type })
-    });
+    pushChunk("declaration:summary", "declaration", `Policy Summary: ${doc.summary}`, { documentType: doc.type });
   }
   if (doc.type === "policy") {
     const pol = doc;
-    chunks.push({
-      id: `${docId}:declaration:policy_details`,
-      documentId: docId,
-      type: "declaration",
-      text: [
+    pushChunk(
+      "declaration:policy_details",
+      "declaration",
+      lines([
         `Policy Number: ${pol.policyNumber}`,
         `Effective Date: ${pol.effectiveDate}`,
         pol.expirationDate ? `Expiration Date: ${pol.expirationDate}` : null,
         pol.policyTermType ? `Term Type: ${pol.policyTermType}` : null,
         pol.effectiveTime ? `Effective Time: ${pol.effectiveTime}` : null,
         pol.nextReviewDate ? `Next Review Date: ${pol.nextReviewDate}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({
+      ]),
+      {
         policyNumber: pol.policyNumber,
         effectiveDate: pol.effectiveDate,
         expirationDate: pol.expirationDate,
         documentType: doc.type
-      })
-    });
+      }
+    );
   } else {
     const quote = doc;
-    chunks.push({
-      id: `${docId}:declaration:quote_details`,
-      documentId: docId,
-      type: "declaration",
-      text: [
+    pushChunk(
+      "declaration:quote_details",
+      "declaration",
+      lines([
         `Quote Number: ${quote.quoteNumber}`,
         quote.proposedEffectiveDate ? `Proposed Effective Date: ${quote.proposedEffectiveDate}` : null,
         quote.proposedExpirationDate ? `Proposed Expiration Date: ${quote.proposedExpirationDate}` : null,
         quote.quoteExpirationDate ? `Quote Expiration Date: ${quote.quoteExpirationDate}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({
+      ]),
+      {
         quoteNumber: quote.quoteNumber,
         documentType: doc.type
-      })
-    });
+      }
+    );
   }
   if (doc.insurer) {
-    chunks.push({
-      id: `${docId}:party:insurer`,
-      documentId: docId,
-      type: "party",
-      text: [
+    pushChunk(
+      "party:insurer",
+      "party",
+      lines([
         `Insurer: ${doc.insurer.legalName}`,
         doc.insurer.naicNumber ? `NAIC: ${doc.insurer.naicNumber}` : null,
         doc.insurer.amBestRating ? `AM Best Rating: ${doc.insurer.amBestRating}` : null,
         doc.insurer.amBestNumber ? `AM Best Number: ${doc.insurer.amBestNumber}` : null,
         doc.insurer.admittedStatus ? `Admitted Status: ${doc.insurer.admittedStatus}` : null,
         doc.insurer.stateOfDomicile ? `State of Domicile: ${doc.insurer.stateOfDomicile}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({ partyRole: "insurer", partyName: doc.insurer.legalName, documentType: doc.type })
-    });
+      ]),
+      { partyRole: "insurer", partyName: doc.insurer.legalName, documentType: doc.type }
+    );
   }
   if (doc.producer) {
-    chunks.push({
-      id: `${docId}:party:producer`,
-      documentId: docId,
-      type: "party",
-      text: [
+    pushChunk(
+      "party:producer",
+      "party",
+      lines([
         `Producer/Broker: ${doc.producer.agencyName}`,
         doc.producer.contactName ? `Contact: ${doc.producer.contactName}` : null,
         doc.producer.licenseNumber ? `License: ${doc.producer.licenseNumber}` : null,
         doc.producer.phone ? `Phone: ${doc.producer.phone}` : null,
         doc.producer.email ? `Email: ${doc.producer.email}` : null,
         doc.producer.address ? `Address: ${formatAddress(doc.producer.address)}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({ partyRole: "producer", partyName: doc.producer.agencyName, documentType: doc.type })
-    });
+      ]),
+      { partyRole: "producer", partyName: doc.producer.agencyName, documentType: doc.type }
+    );
   }
-  chunks.push({
-    id: `${docId}:named_insured:0`,
-    documentId: docId,
-    type: "named_insured",
-    text: [
+  pushChunk(
+    "named_insured:0",
+    "named_insured",
+    lines([
       `Insured: ${doc.insuredName}`,
       doc.insuredDba ? `DBA: ${doc.insuredDba}` : null,
       doc.insuredEntityType ? `Entity Type: ${doc.insuredEntityType}` : null,
@@ -2681,36 +2777,34 @@ function chunkDocument(doc) {
       doc.insuredSicCode ? `SIC: ${doc.insuredSicCode}` : null,
       doc.insuredNaicsCode ? `NAICS: ${doc.insuredNaicsCode}` : null,
       doc.insuredAddress ? `Address: ${formatAddress(doc.insuredAddress)}` : null
-    ].filter(Boolean).join("\n"),
-    metadata: stringMetadata({ insuredName: doc.insuredName, documentType: doc.type })
-  });
+    ]),
+    { insuredName: doc.insuredName, documentType: doc.type }
+  );
   doc.additionalNamedInsureds?.forEach((insured, i) => {
-    chunks.push({
-      id: `${docId}:named_insured:${i + 1}`,
-      documentId: docId,
-      type: "named_insured",
-      text: [
+    pushChunk(
+      `named_insured:${i + 1}`,
+      "named_insured",
+      lines([
         `Additional Named Insured: ${insured.name}`,
         insured.address ? `Address: ${formatAddress(insured.address)}` : null,
         insured.relationship ? `Relationship: ${insured.relationship}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({ insuredName: insured.name, role: "additional_named_insured", documentType: doc.type })
-    });
+      ]),
+      { insuredName: insured.name, role: "additional_named_insured", documentType: doc.type }
+    );
   });
   doc.coverages.forEach((cov, i) => {
-    chunks.push({
-      id: `${docId}:coverage:${i}`,
-      documentId: docId,
-      type: "coverage",
-      text: [
+    pushChunk(
+      `coverage:${i}`,
+      "coverage",
+      lines([
         `Coverage: ${cov.name}`,
         `Limit: ${cov.limit}`,
         cov.limitValueType ? `Limit Type: ${cov.limitValueType}` : null,
         cov.deductible ? `Deductible: ${cov.deductible}` : null,
         cov.deductibleValueType ? `Deductible Type: ${cov.deductibleValueType}` : null,
         cov.originalContent ? `Source: ${cov.originalContent}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({
+      ]),
+      {
         coverageName: cov.name,
         limit: cov.limit,
         limitValueType: cov.limitValueType,
@@ -2720,15 +2814,14 @@ function chunkDocument(doc) {
         pageNumber: cov.pageNumber,
         sectionRef: cov.sectionRef,
         documentType: doc.type
-      })
-    });
+      }
+    );
   });
   doc.enrichedCoverages?.forEach((cov, i) => {
-    chunks.push({
-      id: `${docId}:coverage:enriched:${i}`,
-      documentId: docId,
-      type: "coverage",
-      text: [
+    pushChunk(
+      `coverage:enriched:${i}`,
+      "coverage",
+      lines([
         `Coverage: ${cov.name}`,
         cov.coverageCode ? `Code: ${cov.coverageCode}` : null,
         `Limit: ${cov.limit}`,
@@ -2745,8 +2838,8 @@ function chunkDocument(doc) {
         `Included: ${cov.included ? "Yes" : "No"}`,
         cov.premium ? `Premium: ${cov.premium}` : null,
         cov.originalContent ? `Source: ${cov.originalContent}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({
+      ]),
+      {
         coverageName: cov.name,
         coverageCode: cov.coverageCode,
         limit: cov.limit,
@@ -2755,8 +2848,8 @@ function chunkDocument(doc) {
         pageNumber: cov.pageNumber,
         included: cov.included,
         documentType: doc.type
-      })
-    });
+      }
+    );
   });
   if (doc.limits) {
     const limitLines = ["Limit Schedule"];
@@ -2780,39 +2873,31 @@ function chunkDocument(doc) {
       limitLines.push(`Employers Liability \u2014 Each Accident: ${lim.employersLiability.eachAccident}, Disease Policy Limit: ${lim.employersLiability.diseasePolicyLimit}, Disease Each Employee: ${lim.employersLiability.diseaseEachEmployee}`);
     }
     if (lim.defenseCostTreatment) limitLines.push(`Defense Cost Treatment: ${lim.defenseCostTreatment}`);
-    chunks.push({
-      id: `${docId}:coverage:limit_schedule`,
-      documentId: docId,
-      type: "coverage",
-      text: limitLines.join("\n"),
-      metadata: stringMetadata({ coverageName: "limit_schedule", documentType: doc.type })
-    });
+    pushChunk("coverage:limit_schedule", "coverage", limitLines.join("\n"), { coverageName: "limit_schedule", documentType: doc.type });
     lim.sublimits?.forEach((sub, i) => {
-      chunks.push({
-        id: `${docId}:coverage:sublimit:${i}`,
-        documentId: docId,
-        type: "coverage",
-        text: [
+      pushChunk(
+        `coverage:sublimit:${i}`,
+        "coverage",
+        lines([
           `Sublimit: ${sub.name}`,
           `Limit: ${sub.limit}`,
           sub.appliesTo ? `Applies To: ${sub.appliesTo}` : null,
           sub.deductible ? `Deductible: ${sub.deductible}` : null
-        ].filter(Boolean).join("\n"),
-        metadata: stringMetadata({ coverageName: sub.name, limit: sub.limit, documentType: doc.type })
-      });
+        ]),
+        { coverageName: sub.name, limit: sub.limit, documentType: doc.type }
+      );
     });
     lim.sharedLimits?.forEach((sl, i) => {
-      chunks.push({
-        id: `${docId}:coverage:shared_limit:${i}`,
-        documentId: docId,
-        type: "coverage",
-        text: [
+      pushChunk(
+        `coverage:shared_limit:${i}`,
+        "coverage",
+        [
           `Shared Limit: ${sl.description}`,
           `Limit: ${sl.limit}`,
           `Coverage Parts: ${sl.coverageParts.join(", ")}`
         ].join("\n"),
-        metadata: stringMetadata({ coverageName: sl.description, limit: sl.limit, documentType: doc.type })
-      });
+        { coverageName: sl.description, limit: sl.limit, documentType: doc.type }
+      );
     });
   }
   if (doc.deductibles) {
@@ -2826,12 +2911,9 @@ function chunkDocument(doc) {
     if (ded.waitingPeriod) dedLines.push(`Waiting Period: ${ded.waitingPeriod}`);
     if (ded.appliesTo) dedLines.push(`Applies To: ${ded.appliesTo}`);
     if (dedLines.length > 1) {
-      chunks.push({
-        id: `${docId}:coverage:deductible_schedule`,
-        documentId: docId,
-        type: "coverage",
-        text: dedLines.join("\n"),
-        metadata: stringMetadata({ coverageName: "deductible_schedule", documentType: doc.type })
+      pushChunk("coverage:deductible_schedule", "coverage", dedLines.join("\n"), {
+        coverageName: "deductible_schedule",
+        documentType: doc.type
       });
     }
   }
@@ -2843,99 +2925,90 @@ function chunkDocument(doc) {
     doc.extendedReportingPeriod?.supplementalPremium ? `Extended Reporting Period Premium: ${doc.extendedReportingPeriod.supplementalPremium}` : null
   ].filter(Boolean);
   if (claimsMadeLines.length > 0) {
-    chunks.push({
-      id: `${docId}:coverage:claims_made_details`,
-      documentId: docId,
-      type: "coverage",
-      text: claimsMadeLines.join("\n"),
-      metadata: stringMetadata({ coverageName: "claims_made_details", documentType: doc.type })
+    pushChunk("coverage:claims_made_details", "coverage", claimsMadeLines.join("\n"), {
+      coverageName: "claims_made_details",
+      documentType: doc.type
     });
   }
   doc.formInventory?.forEach((form, i) => {
-    chunks.push({
-      id: `${docId}:declaration:form:${i}`,
-      documentId: docId,
-      type: "declaration",
-      text: [
+    pushChunk(
+      `declaration:form:${i}`,
+      "declaration",
+      lines([
         `Form: ${form.formNumber}`,
         form.title ? `Title: ${form.title}` : null,
         `Type: ${form.formType}`,
         form.editionDate ? `Edition: ${form.editionDate}` : null,
         form.pageStart ? `Pages: ${form.pageStart}${form.pageEnd ? `-${form.pageEnd}` : ""}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({
+      ]),
+      {
         formNumber: form.formNumber,
         formType: form.formType,
         documentType: doc.type
-      })
-    });
+      }
+    );
   });
   doc.endorsements?.forEach((end, i) => {
-    chunks.push({
-      id: `${docId}:endorsement:${i}`,
-      documentId: docId,
-      type: "endorsement",
-      text: `Endorsement: ${end.title}
+    pushChunk(
+      `endorsement:${i}`,
+      "endorsement",
+      `Endorsement: ${end.title}
 ${end.content}`.trim(),
-      metadata: stringMetadata({
+      {
         endorsementType: end.endorsementType,
         formNumber: end.formNumber,
         pageStart: end.pageStart,
         pageEnd: end.pageEnd,
         documentType: doc.type
-      })
-    });
+      }
+    );
   });
   doc.exclusions?.forEach((exc, i) => {
-    chunks.push({
-      id: `${docId}:exclusion:${i}`,
-      documentId: docId,
-      type: "exclusion",
-      text: `Exclusion: ${exc.name}
-${exc.content}`.trim(),
-      metadata: stringMetadata({ formNumber: exc.formNumber, pageNumber: exc.pageNumber, documentType: doc.type })
+    pushChunk(`exclusion:${i}`, "exclusion", `Exclusion: ${exc.name}
+${exc.content}`.trim(), {
+      formNumber: exc.formNumber,
+      pageNumber: exc.pageNumber,
+      documentType: doc.type
     });
   });
   doc.conditions?.forEach((cond, i) => {
-    chunks.push({
-      id: `${docId}:condition:${i}`,
-      documentId: docId,
-      type: "condition",
-      text: [
+    pushChunk(
+      `condition:${i}`,
+      "condition",
+      [
         `Condition: ${cond.name}`,
         `Type: ${cond.conditionType}`,
         cond.content,
         ...cond.keyValues?.map((kv) => `${kv.key}: ${kv.value}`) ?? []
       ].join("\n"),
-      metadata: stringMetadata({
+      {
         conditionName: cond.name,
         conditionType: cond.conditionType,
         pageNumber: cond.pageNumber,
         documentType: doc.type
-      })
-    });
+      }
+    );
   });
   asRecordArray(extendedDoc.definitions).forEach((definition, i) => {
     const term = firstString(definition, ["term", "name", "title"]) ?? `Definition ${i + 1}`;
     const body = firstString(definition, ["definition", "content", "text", "meaning"]);
-    chunks.push({
-      id: `${docId}:definition:${i}`,
-      documentId: docId,
-      type: "definition",
-      text: [
+    pushChunk(
+      `definition:${i}`,
+      "definition",
+      lines([
         `Definition: ${term}`,
         body,
         firstString(definition, ["originalContent", "source"]) ? `Source: ${firstString(definition, ["originalContent", "source"])}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({
+      ]),
+      {
         term,
         formNumber: firstString(definition, ["formNumber"]),
         formTitle: firstString(definition, ["formTitle"]),
         pageNumber: typeof definition.pageNumber === "number" ? definition.pageNumber : void 0,
         sectionRef: firstString(definition, ["sectionRef", "sectionTitle"]),
         documentType: doc.type
-      })
-    });
+      }
+    );
   });
   const coveredReasons = asRecordArray(extendedDoc.coveredReasons ?? extendedDoc.covered_reasons);
   coveredReasons.forEach((coveredReason, i) => {
@@ -2943,18 +3016,17 @@ ${exc.content}`.trim(),
     const coverageName = firstString(coveredReason, ["coverageName", "coverage", "coveragePart"]);
     const reasonNumber = firstString(coveredReason, ["reasonNumber", "number"]);
     const body = firstString(coveredReason, ["content", "description", "text", "coverageGrant"]);
-    chunks.push({
-      id: `${docId}:covered_reason:${i}`,
-      documentId: docId,
-      type: "covered_reason",
-      text: [
+    pushChunk(
+      `covered_reason:${i}`,
+      "covered_reason",
+      lines([
         coverageName ? `Coverage: ${coverageName}` : null,
         reasonNumber ? `Reason Number: ${reasonNumber}` : null,
         `Covered Reason: ${title}`,
         body,
         firstString(coveredReason, ["originalContent", "source"]) ? `Source: ${firstString(coveredReason, ["originalContent", "source"])}` : null
-      ].filter(Boolean).join("\n"),
-      metadata: stringMetadata({
+      ]),
+      {
         coverageName,
         reasonNumber,
         title,
@@ -2963,21 +3035,20 @@ ${exc.content}`.trim(),
         pageNumber: typeof coveredReason.pageNumber === "number" ? coveredReason.pageNumber : void 0,
         sectionRef: firstString(coveredReason, ["sectionRef", "sectionTitle"]),
         documentType: doc.type
-      })
-    });
+      }
+    );
     const conditions = Array.isArray(coveredReason.conditions) ? coveredReason.conditions.filter((condition) => typeof condition === "string" && condition.trim().length > 0) : [];
     conditions.forEach((condition, conditionIndex) => {
-      chunks.push({
-        id: `${docId}:covered_reason:${i}:condition:${conditionIndex}`,
-        documentId: docId,
-        type: "covered_reason",
-        text: [
+      pushChunk(
+        `covered_reason:${i}:condition:${conditionIndex}`,
+        "covered_reason",
+        lines([
           coverageName ? `Coverage: ${coverageName}` : null,
           reasonNumber ? `Reason Number: ${reasonNumber}` : null,
           `Covered Reason Condition: ${title}`,
           condition
-        ].filter(Boolean).join("\n"),
-        metadata: stringMetadata({
+        ]),
+        {
           coverageName,
           reasonNumber,
           title,
@@ -2987,8 +3058,8 @@ ${exc.content}`.trim(),
           pageNumber: typeof coveredReason.pageNumber === "number" ? coveredReason.pageNumber : void 0,
           sectionRef: firstString(coveredReason, ["sectionRef", "sectionTitle"]),
           documentType: doc.type
-        })
-      });
+        }
+      );
     });
   });
   if (doc.declarations) {
@@ -3003,50 +3074,42 @@ ${exc.content}`.trim(),
       const declMeta = { documentType: doc.type };
       if (typeof decl.formType === "string") declMeta.formType = decl.formType;
       if (typeof decl.line === "string") declMeta.declarationLine = decl.line;
-      chunks.push({
-        id: `${docId}:declaration:0`,
-        documentId: docId,
-        type: "declaration",
-        text: `Declarations
-${declLines.join("\n")}`,
-        metadata: stringMetadata(declMeta)
-      });
+      pushChunk("declaration:0", "declaration", `Declarations
+${declLines.join("\n")}`, declMeta);
     }
   }
   doc.sections?.forEach((sec, i) => {
     const hasSubsections = sec.subsections && sec.subsections.length > 0;
     const contentLength = sec.content.length;
     if (hasSubsections) {
-      chunks.push({
-        id: `${docId}:section:${i}`,
-        documentId: docId,
-        type: "section",
-        text: `Section: ${sec.title}
+      pushChunk(
+        `section:${i}`,
+        "section",
+        `Section: ${sec.title}
 ${sec.content}`,
-        metadata: stringMetadata({
+        {
           sectionType: sec.type,
           sectionNumber: sec.sectionNumber,
           pageStart: sec.pageStart,
           pageEnd: sec.pageEnd,
           documentType: doc.type,
           hasSubsections: "true"
-        })
-      });
+        }
+      );
       sec.subsections.forEach((sub, j) => {
-        chunks.push({
-          id: `${docId}:section:${i}:sub:${j}`,
-          documentId: docId,
-          type: "section",
-          text: `${sec.title} > ${sub.title}
+        pushChunk(
+          `section:${i}:sub:${j}`,
+          "section",
+          `${sec.title} > ${sub.title}
 ${sub.content}`,
-          metadata: stringMetadata({
+          {
             sectionType: sec.type,
             parentSection: sec.title,
             sectionNumber: sub.sectionNumber,
             pageNumber: sub.pageNumber,
             documentType: doc.type
-          })
-        });
+          }
+        );
       });
     } else if (contentLength > 2e3) {
       const paragraphs = sec.content.split(/\n\n+/);
@@ -3054,58 +3117,55 @@ ${sub.content}`,
       let chunkIndex = 0;
       for (const para of paragraphs) {
         if (currentChunk.length + para.length > 1e3 && currentChunk.length > 0) {
-          chunks.push({
-            id: `${docId}:section:${i}:part:${chunkIndex}`,
-            documentId: docId,
-            type: "section",
-            text: `Section: ${sec.title} (part ${chunkIndex + 1})
+          pushChunk(
+            `section:${i}:part:${chunkIndex}`,
+            "section",
+            `Section: ${sec.title} (part ${chunkIndex + 1})
 ${currentChunk.trim()}`,
-            metadata: stringMetadata({
+            {
               sectionType: sec.type,
               sectionNumber: sec.sectionNumber,
               pageStart: sec.pageStart,
               pageEnd: sec.pageEnd,
               documentType: doc.type,
               partIndex: chunkIndex
-            })
-          });
+            }
+          );
           currentChunk = "";
           chunkIndex++;
         }
         currentChunk += (currentChunk ? "\n\n" : "") + para;
       }
       if (currentChunk.trim()) {
-        chunks.push({
-          id: `${docId}:section:${i}:part:${chunkIndex}`,
-          documentId: docId,
-          type: "section",
-          text: `Section: ${sec.title} (part ${chunkIndex + 1})
+        pushChunk(
+          `section:${i}:part:${chunkIndex}`,
+          "section",
+          `Section: ${sec.title} (part ${chunkIndex + 1})
 ${currentChunk.trim()}`,
-          metadata: stringMetadata({
+          {
             sectionType: sec.type,
             sectionNumber: sec.sectionNumber,
             pageStart: sec.pageStart,
             pageEnd: sec.pageEnd,
             documentType: doc.type,
             partIndex: chunkIndex
-          })
-        });
+          }
+        );
       }
     } else {
-      chunks.push({
-        id: `${docId}:section:${i}`,
-        documentId: docId,
-        type: "section",
-        text: `Section: ${sec.title}
+      pushChunk(
+        `section:${i}`,
+        "section",
+        `Section: ${sec.title}
 ${sec.content}`,
-        metadata: stringMetadata({
+        {
           sectionType: sec.type,
           sectionNumber: sec.sectionNumber,
           pageStart: sec.pageStart,
           pageEnd: sec.pageEnd,
           documentType: doc.type
-        })
-      });
+        }
+      );
     }
   });
   doc.locations?.forEach((loc, i) => {
@@ -4683,12 +4743,15 @@ var ReviewResultSchema = z21.object({
     description: z21.string()
   }))
 });
-function buildReviewPrompt(templateExpected, extractedKeys, extractionSummary, pageMapSummary) {
-  return `You are reviewing an extraction for completeness and quality. Compare what was expected vs what was found.
+function buildReviewPrompt(templateExpected, extractedKeys, extractionSummary, pageMapSummary, extractorCatalog) {
+  return `You are the extraction coordinator for an insurance-document agent system. Review the current extraction state, decide whether the result is complete enough, and choose any follow-up extractor tasks needed to improve it.
 
 EXPECTED FIELDS (from document type template):
 ${templateExpected.map((f) => `- ${f}`).join("\n")}
 
+AVAILABLE FOLLOW-UP EXTRACTORS:
+${extractorCatalog}
+
 FIELDS ALREADY EXTRACTED:
 ${extractedKeys.map((f) => `- ${f}`).join("\n")}
 
@@ -4702,7 +4765,7 @@ Determine:
 1. Is the extraction complete enough?
 2. What fields are missing?
 3. What quality issues are present?
-4. Should any additional extraction tasks be dispatched?
+4. Which follow-up extraction tasks, if any, should be dispatched?
 
 Mark the extraction as NOT complete if any of these are true:
 - required fields are missing
@@ -4713,7 +4776,9 @@ Mark the extraction as NOT complete if any of these are true:
 - page assignments suggest declaration, schedule, endorsement, exclusion, or condition pages were not actually extracted with the matching focused extractor
 - a focused extractor exists but returned too little substance for the relevant pages
 
-When reviewing CURRENT EXTRACTION SUMMARY, compare the page-map counts to extracted counts. For definitions and covered_reasons, missing extraction should produce a quality issue and a narrow follow-up task over the mapped page range.
+When reviewing CURRENT EXTRACTION SUMMARY, compare the page-map counts to extracted counts. If an assigned extractor produced no useful records, produce a quality issue and a narrow follow-up task over the mapped page range.
+
+Choose follow-up tasks from AVAILABLE FOLLOW-UP EXTRACTORS. You may dispatch any listed extractor when the page map, current extraction summary, or quality evidence shows that the focused extraction is missing, generic, referential, or too thin. Do not invent extractor names.
 
 Return JSON:
 {
@@ -4725,7 +4790,7 @@ Return JSON:
   ]
 }
 
-Use the page map to target follow-up extraction pages precisely. Prefer narrow, declaration/schedule-focused follow-up tasks over broad page ranges.
+Use the page map to target follow-up extraction pages precisely. Prefer narrow, declaration/schedule-focused follow-up tasks over broad page ranges. If no additional model work is likely to improve the extraction, return an empty additionalTasks array.
 
 Respond with JSON only.`;
 }
@@ -5260,6 +5325,7 @@ var SectionsSchema = z32.object({
         "policy_form",
         "endorsement",
         "application",
+        "covered_reason",
         "exclusion",
         "condition",
         "definition",
@@ -5283,6 +5349,7 @@ For each section, classify its type:
 - "policy_form" \u2014 named ISO or proprietary forms (e.g. CG 00 01, IL 00 17). All sections within a named form should be typed as "policy_form"
 - "endorsement" \u2014 standalone endorsements modifying the base policy
 - "application" \u2014 the insurance application or supplemental application
+- "covered_reason" \u2014 affirmative grants of coverage, covered causes of loss, covered perils, or named covered events
 - "insuring_agreement" \u2014 the insuring agreement clause (only if standalone, not inside a policy_form)
 - "exclusion", "condition", "definition" \u2014 for standalone sections only
 - "schedule" \u2014 coverage or rating schedules
@@ -5460,6 +5527,53 @@ Return JSON only.`;
 }
 
 // src/prompts/extractors/index.ts
+function asRecord(data) {
+  return data && typeof data === "object" ? data : void 0;
+}
+function getSections2(data) {
+  const sections = asRecord(data)?.sections;
+  return Array.isArray(sections) ? sections : [];
+}
+function isCoveredReasonsEmpty(data) {
+  const record = asRecord(data);
+  if (!record) return true;
+  const coveredReasons = Array.isArray(record.coveredReasons) ? record.coveredReasons : Array.isArray(record.covered_reasons) ? record.covered_reasons : [];
+  return coveredReasons.length === 0;
+}
+function isDefinitionsEmpty(data) {
+  const definitions = asRecord(data)?.definitions;
+  return !Array.isArray(definitions) || definitions.length === 0;
+}
+function sectionLooksLikeCoveredReason(section) {
+  const type = String(section.type ?? "").toLowerCase();
+  const title = String(section.title ?? "").toLowerCase();
+  return type === "covered_reason" || title.includes("covered cause") || title.includes("covered reason") || title.includes("covered peril") || title.includes("named peril") || title.includes("insuring agreement");
+}
+function deriveCoveredReasonsFromSections(data) {
+  const coveredReasons = getSections2(data).filter(sectionLooksLikeCoveredReason).map((section) => ({
+    coverageName: String(section.coverageName ?? section.formTitle ?? section.title ?? "Covered Reasons"),
+    title: typeof section.title === "string" ? section.title : void 0,
+    content: String(section.content ?? ""),
+    pageNumber: typeof section.pageStart === "number" ? section.pageStart : void 0,
+    formNumber: typeof section.formNumber === "string" ? section.formNumber : void 0,
+    formTitle: typeof section.formTitle === "string" ? section.formTitle : void 0,
+    sectionRef: typeof section.sectionNumber === "string" ? section.sectionNumber : void 0,
+    originalContent: typeof section.content === "string" ? section.content.slice(0, 500) : void 0
+  })).filter((coveredReason) => coveredReason.content.trim().length > 0);
+  return coveredReasons.length > 0 ? { coveredReasons } : void 0;
+}
+function deriveDefinitionsFromSections(data) {
+  const definitions = getSections2(data).filter((section) => String(section.type ?? "").toLowerCase() === "definition").map((section) => ({
+    term: String(section.title ?? "Definitions"),
+    definition: String(section.content ?? ""),
+    pageNumber: typeof section.pageStart === "number" ? section.pageStart : void 0,
+    formNumber: typeof section.formNumber === "string" ? section.formNumber : void 0,
+    formTitle: typeof section.formTitle === "string" ? section.formTitle : void 0,
+    sectionRef: typeof section.sectionNumber === "string" ? section.sectionNumber : void 0,
+    originalContent: typeof section.content === "string" ? section.content.slice(0, 500) : void 0
+  })).filter((definition) => definition.definition.trim().length > 0);
+  return definitions.length > 0 ? { definitions } : void 0;
+}
 var EXTRACTORS = {
   carrier_info: { buildPrompt: buildCarrierInfoPrompt, schema: CarrierInfoSchema, maxTokens: 2048 },
   named_insured: { buildPrompt: buildNamedInsuredPrompt, schema: NamedInsuredSchema2, maxTokens: 2048 },
@@ -5472,12 +5586,36 @@ var EXTRACTORS = {
   loss_history: { buildPrompt: buildLossHistoryPrompt, schema: LossHistorySchema, maxTokens: 4096 },
   sections: { buildPrompt: buildSectionsPrompt, schema: SectionsSchema, maxTokens: 8192 },
   supplementary: { buildPrompt: buildSupplementaryPrompt, schema: SupplementarySchema, maxTokens: 2048 },
-  definitions: { buildPrompt: buildDefinitionsPrompt, schema: DefinitionsSchema, maxTokens: 8192 },
-  covered_reasons: { buildPrompt: buildCoveredReasonsPrompt, schema: CoveredReasonsSchema, maxTokens: 8192 }
+  definitions: {
+    buildPrompt: buildDefinitionsPrompt,
+    schema: DefinitionsSchema,
+    maxTokens: 8192,
+    fallback: {
+      extractorName: "sections",
+      isEmpty: isDefinitionsEmpty,
+      deriveFocusedResult: deriveDefinitionsFromSections
+    }
+  },
+  covered_reasons: {
+    buildPrompt: buildCoveredReasonsPrompt,
+    schema: CoveredReasonsSchema,
+    maxTokens: 8192,
+    fallback: {
+      extractorName: "sections",
+      isEmpty: isCoveredReasonsEmpty,
+      deriveFocusedResult: deriveCoveredReasonsFromSections
+    }
+  }
 };
 function getExtractor(name) {
   return EXTRACTORS[name];
 }
+function formatExtractorCatalogForPrompt() {
+  return Object.entries(EXTRACTORS).map(([name, extractor]) => {
+    const fallback = extractor.fallback ? `; fallback: ${extractor.fallback.extractorName}` : "";
+    return `- ${name} (maxTokens: ${extractor.maxTokens ?? 4096}${fallback})`;
+  }).join("\n");
+}
 
 // src/extraction/resolve-referential.ts
 import { z as z37 } from "zod";
@@ -5529,18 +5667,124 @@ Your task:
 Return JSON only.`;
 }
 
-// src/extraction/resolve-referential.ts
+// src/extraction/heuristics.ts
 function looksReferential(value) {
   if (typeof value !== "string") return false;
   const normalized = value.toLowerCase();
   return normalized.includes("shown in the declarations") || normalized.includes("shown in declarations") || normalized.includes("shown in the schedule") || normalized.includes("as stated") || normalized.includes("if applicable");
 }
+function looksCoveredReasonSection(section) {
+  const title = String(section.title ?? "").toLowerCase();
+  const type = String(section.type ?? "").toLowerCase();
+  return type === "covered_reason" || title.includes("covered cause") || title.includes("covered reason") || title.includes("covered peril");
+}
+
+// src/extraction/referential-workflow.ts
+function normalizeText(value) {
+  return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+function containsTarget(value, target) {
+  const normalizedValue = normalizeText(value);
+  return Boolean(normalizedValue && target && normalizedValue.includes(target));
+}
+function pageRangeFrom(startPage, endPage) {
+  if (typeof startPage !== "number" || !Number.isFinite(startPage) || startPage <= 0) {
+    return void 0;
+  }
+  const normalizedEnd = typeof endPage === "number" && Number.isFinite(endPage) && endPage >= startPage ? endPage : startPage;
+  return { startPage, endPage: normalizedEnd };
+}
+function parseReferentialTarget(rawTarget) {
+  const raw = rawTarget?.trim() || "unknown";
+  const normalized = raw.toLowerCase();
+  if (normalized === "unknown") return { raw, normalized, kind: "unknown" };
+  if (/declarations?|dec\b|decs\b/.test(normalized)) return { raw, normalized, kind: "declarations" };
+  if (/schedule|scheduled/.test(normalized)) return { raw, normalized, kind: "schedule" };
+  if (/\bitem\b/.test(normalized)) return { raw, normalized, kind: "item" };
+  if (/premises?|location|building/.test(normalized)) return { raw, normalized, kind: "premises" };
+  if (/\bsection\b/.test(normalized)) return { raw, normalized, kind: "section" };
+  if (/policy|coverage\s+part|coverage\s+form/.test(normalized)) return { raw, normalized, kind: "policy" };
+  return { raw, normalized, kind: "unknown" };
+}
+function findLocalReferentialPages(params) {
+  const targetLower = params.referenceTarget.toLowerCase();
+  for (const section of params.sections) {
+    if (containsTarget(section.title, targetLower)) {
+      const range = pageRangeFrom(section.pageStart, section.pageEnd);
+      if (range) return range;
+    }
+  }
+  for (const form of params.formInventory) {
+    const titleMatch = containsTarget(form.title, targetLower);
+    const typeMatch = containsTarget(form.formType, targetLower);
+    const numberMatch = containsTarget(form.formNumber, targetLower);
+    if (titleMatch || typeMatch || numberMatch) {
+      const range = pageRangeFrom(form.pageStart, form.pageEnd);
+      if (range) return range;
+    }
+  }
+  return void 0;
+}
+function findDeclarationsSchedulePages(parsedTarget, formInventory) {
+  for (const form of formInventory) {
+    const formType = normalizeText(form.formType);
+    const title = normalizeText(form.title);
+    const matchesDeclarations = formType === "declarations" || /declarations?|dec\b|decs\b/.test(title);
+    const matchesSchedule = /schedule|scheduled|coverage/.test(title) || formType === "coverage";
+    const shouldUse = parsedTarget.kind === "declarations" ? matchesDeclarations : parsedTarget.kind === "schedule" || parsedTarget.kind === "item" || parsedTarget.kind === "premises" ? matchesSchedule || matchesDeclarations : parsedTarget.kind === "policy" ? matchesDeclarations || matchesSchedule : false;
+    if (shouldUse) {
+      const range = pageRangeFrom(form.pageStart, form.pageEnd);
+      if (range) return range;
+    }
+  }
+  return void 0;
+}
+function findSectionPages(parsedTarget, sections) {
+  for (const section of sections) {
+    const title = normalizeText(section.title);
+    const type = normalizeText(section.type);
+    const matchesKind = parsedTarget.kind === "declarations" && (type === "declarations" || /declarations?/.test(title)) || parsedTarget.kind === "schedule" && (type === "schedule" || /schedule|scheduled/.test(title)) || parsedTarget.kind === "premises" && /premises?|location|building/.test(title) || parsedTarget.kind === "item" && /\bitem\b|schedule|scheduled/.test(title) || parsedTarget.kind === "section" && containsTarget(title, parsedTarget.normalized);
+    if (matchesKind) {
+      const range = pageRangeFrom(section.pageStart, section.pageEnd);
+      if (range) return range;
+    }
+  }
+  return void 0;
+}
+function decideReferentialResolutionAction(params) {
+  if (params.localPageRange) {
+    return { kind: "lookup_pages", source: "local", pageRange: params.localPageRange };
+  }
+  const parsedTarget = parseReferentialTarget(params.referenceTarget);
+  const declarationsScheduleRange = findDeclarationsSchedulePages(parsedTarget, params.formInventory);
+  if (declarationsScheduleRange) {
+    return {
+      kind: "lookup_pages",
+      source: "declarations_schedule",
+      pageRange: declarationsScheduleRange
+    };
+  }
+  const sectionRange = findSectionPages(parsedTarget, params.sections);
+  if (sectionRange) {
+    return { kind: "lookup_pages", source: "sections", pageRange: sectionRange };
+  }
+  if (parsedTarget.kind === "unknown") {
+    return { kind: "skip", reason: "no concrete reference target" };
+  }
+  return { kind: "page_location" };
+}
+
+// src/extraction/resolve-referential.ts
 function parseReferenceTarget(text) {
   if (typeof text !== "string") return void 0;
   const normalized = text.trim();
   if (!normalized) return void 0;
   const sectionMatch = normalized.match(/\b(Section\s+\d+[A-Za-z]?)/i);
   if (sectionMatch) return sectionMatch[1];
+  const itemMatch = normalized.match(/\b(Item\s+\d+[A-Za-z]?)/i);
+  if (itemMatch) return itemMatch[1];
+  const premisesMatch = normalized.match(/\b(Premises?(?:\s+No\.?\s*\d+[A-Za-z]?|\s+\d+[A-Za-z]?)?)/i);
+  if (premisesMatch) return premisesMatch[1].trim();
   if (/declarations/i.test(normalized)) return "Declarations";
   const scheduleMatch = normalized.match(/\b(Schedule(?:\s+of\s+[A-Za-z ]+)?)/i);
   if (scheduleMatch) return scheduleMatch[1].trim();
@@ -5566,26 +5810,31 @@ async function findReferencedPages(params) {
     pageCount,
     generateObject,
     providerOptions,
+    trackUsage,
     log
   } = params;
-  const targetLower = referenceTarget.toLowerCase();
-  for (const section of sections) {
-    if (section.title && section.pageStart != null && section.title.toLowerCase().includes(targetLower)) {
-      return {
-        startPage: section.pageStart,
-        endPage: section.pageEnd ?? section.pageStart
-      };
-    }
+  const localPageRange = findLocalReferentialPages({
+    referenceTarget,
+    sections,
+    formInventory
+  });
+  const action = decideReferentialResolutionAction({
+    referenceTarget,
+    sections,
+    formInventory,
+    localPageRange
+  });
+  if (action.kind === "lookup_pages") {
+    await log?.(
+      `Referential target "${referenceTarget}" resolved to pages ${action.pageRange.startPage}-${action.pageRange.endPage} via ${action.source}.`
+    );
+    return action.pageRange;
   }
-  for (const form of formInventory) {
-    const titleMatch = form.title && form.title.toLowerCase().includes(targetLower);
-    const typeMatch = form.formType && form.formType.toLowerCase().includes(targetLower);
-    if ((titleMatch || typeMatch) && form.pageStart != null) {
-      return {
-        startPage: form.pageStart,
-        endPage: form.pageEnd ?? form.pageStart
-      };
-    }
+  if (action.kind === "skip") {
+    await log?.(
+      `Skipping referential target "${referenceTarget}": ${action.reason}.`
+    );
+    return void 0;
   }
   try {
     const result = await safeGenerateObject(
@@ -5613,6 +5862,7 @@ Return JSON only.`,
         )
       }
     );
+    trackUsage?.(result.usage);
     if (result.object.startPage > 0 && result.object.endPage > 0) {
       return {
         startPage: result.object.startPage,
@@ -5670,7 +5920,9 @@ async function resolveReferentialCoverages(params) {
   for (let i = 0; i < referentialCoverages.length; i++) {
     const cov = referentialCoverages[i];
     const refString = (looksReferential(cov.limit) ? cov.limit : void 0) ?? (looksReferential(cov.deductible) ? cov.deductible : void 0) ?? cov.limit ?? "";
-    const target = parseReferenceTarget(refString) ?? "unknown";
+    const sectionRef = typeof cov.sectionRef === "string" ? cov.sectionRef : "";
+    const parsedTarget = parseReferenceTarget(refString) ?? parseReferenceTarget(sectionRef) ?? sectionRef;
+    const target = parsedTarget || "unknown";
     const group = targetGroups.get(target) ?? [];
     group.push({ coverage: cov, index: i });
     targetGroups.set(target, group);
@@ -5694,6 +5946,7 @@ async function resolveReferentialCoverages(params) {
           pageCount,
           generateObject,
           providerOptions,
+          trackUsage,
           log
         });
         if (!pageRange) {
@@ -5811,6 +6064,78 @@ async function resolveReferentialCoverages(params) {
   };
 }
 
+// src/extraction/focused-dispatch.ts
+async function runFocusedExtractorWithFallback(params) {
+  const {
+    task,
+    pdfInput,
+    generateObject,
+    convertPdfToImages,
+    providerOptions,
+    trackUsage,
+    log
+  } = params;
+  const ext = getExtractor(task.extractorName);
+  if (!ext) {
+    await log?.(`Unknown extractor: ${task.extractorName}, skipping`);
+    return null;
+  }
+  try {
+    const result = await runExtractor({
+      name: task.extractorName,
+      prompt: ext.buildPrompt(),
+      schema: ext.schema,
+      pdfInput,
+      startPage: task.startPage,
+      endPage: task.endPage,
+      generateObject,
+      convertPdfToImages,
+      maxTokens: ext.maxTokens ?? 4096,
+      providerOptions
+    });
+    trackUsage(result.usage);
+    if (!ext.fallback?.isEmpty(result.data)) {
+      return result;
+    }
+    if (!ext.fallback) {
+      return result;
+    }
+  } catch (error) {
+    await log?.(`Extractor ${task.extractorName} failed: ${error}`);
+    if (!ext.fallback) {
+      return null;
+    }
+  }
+  const fallbackExt = getExtractor(ext.fallback.extractorName);
+  if (!fallbackExt) return null;
+  await log?.(
+    `Extractor ${task.extractorName} produced no usable records; trying ${ext.fallback.extractorName} fallback for pages ${task.startPage}-${task.endPage}`
+  );
+  try {
+    const fallbackResult = await runExtractor({
+      name: ext.fallback.extractorName,
+      prompt: fallbackExt.buildPrompt(),
+      schema: fallbackExt.schema,
+      pdfInput,
+      startPage: task.startPage,
+      endPage: task.endPage,
+      generateObject,
+      convertPdfToImages,
+      maxTokens: fallbackExt.maxTokens ?? 4096,
+      providerOptions
+    });
+    trackUsage(fallbackResult.usage);
+    const focusedData = ext.fallback.deriveFocusedResult(fallbackResult.data);
+    return focusedData ? [
+      fallbackResult,
+      { name: task.extractorName, data: focusedData, usage: void 0 }
+    ] : fallbackResult;
+  } catch (fallbackError) {
+    await log?.(`${ext.fallback.extractorName} fallback for ${task.extractorName} failed: ${fallbackError}`);
+    return null;
+  }
+}
+
 // src/core/quality.ts
 function evaluateQualityGate(params) {
   const { issues, hasRoundWarnings = false } = params;
@@ -5847,11 +6172,6 @@ function addFormEntry(inventory, formNumber, source, extra) {
     sources: [source]
   });
 }
-function looksReferential2(value) {
-  if (typeof value !== "string") return false;
-  const normalized = value.toLowerCase();
-  return normalized.includes("shown in the declarations") || normalized.includes("shown in declarations") || normalized.includes("shown in the schedule") || normalized.includes("as stated") || normalized.includes("if applicable");
-}
 function looksTocArtifact(value) {
   if (typeof value !== "string") return false;
   return /\.{4,}\d{1,3}$/.test(value.trim()) || /^\d+\.\s+[A-Z][\s\S]*\.{3,}\d{1,3}$/.test(value.trim());
@@ -5878,11 +6198,7 @@ function buildExtractionReviewReport(params) {
   const definitionsResult = memory.get("definitions");
   const coveredReasonsResult = memory.get("covered_reasons");
   const definitions = Array.isArray(definitionsResult?.definitions) ? definitionsResult.definitions : sections.filter((section) => section.type === "definition");
-  const coveredReasons = Array.isArray(coveredReasonsResult?.coveredReasons) ? coveredReasonsResult.coveredReasons : Array.isArray(coveredReasonsResult?.covered_reasons) ? coveredReasonsResult.covered_reasons : sections.filter((section) => {
-    const title = String(section.title ?? "").toLowerCase();
-    const type = String(section.type ?? "").toLowerCase();
-    return type === "covered_reason" || title.includes("covered cause") || title.includes("covered reason") || title.includes("covered peril");
-  });
+  const coveredReasons = Array.isArray(coveredReasonsResult?.coveredReasons) ? coveredReasonsResult.coveredReasons : Array.isArray(coveredReasonsResult?.covered_reasons) ? coveredReasonsResult.covered_reasons : sections.filter(looksCoveredReasonSection);
   const mappedDefinitions = params.pageAssignments.some((assignment) => assignment.extractorNames.includes("definitions"));
   const mappedCoveredReasons = params.pageAssignments.some((assignment) => assignment.extractorNames.includes("covered_reasons"));
   if (mappedDefinitions && definitions.length === 0) {
@@ -5997,7 +6313,7 @@ function buildExtractionReviewReport(params) {
         itemName: typeof coverage.name === "string" ? coverage.name : void 0
       });
     }
-    if (looksReferential2(coverage.limit) || looksReferential2(coverage.deductible)) {
+    if (looksReferential(coverage.limit) || looksReferential(coverage.deductible)) {
       deterministicIssues.push({
         code: "coverage_referential_value",
         severity: "warning",
@@ -6147,7 +6463,7 @@ function buildExtractionReviewReport(params) {
         itemName
       });
     }
-    if (looksReferential2(content) || looksReferential2(coveredReason.reason)) {
+    if (looksReferential(content) || looksReferential(coveredReason.reason)) {
       deterministicIssues.push({
         code: "covered_reason_referential_value",
         severity: "warning",
@@ -6208,6 +6524,134 @@ function toReviewRoundRecord(round, review) {
   };
 }
 
+// src/extraction/planning.ts
+function normalizePageAssignments(pageAssignments, formInventory) {
+  const pageFormTypes = /* @__PURE__ */ new Map();
+  if (formInventory) {
+    for (const form of formInventory.forms) {
+      if (form.pageStart != null) {
+        const end = form.pageEnd ?? form.pageStart;
+        for (let p = form.pageStart; p <= end; p += 1) {
+          const types = pageFormTypes.get(p) ?? /* @__PURE__ */ new Set();
+          types.add(form.formType);
+          pageFormTypes.set(p, types);
+        }
+      }
+    }
+  }
+  return pageAssignments.map((assignment) => {
+    let extractorNames = [...new Set(
+      (assignment.extractorNames.length > 0 ? assignment.extractorNames : ["sections"]).filter(Boolean)
+    )];
+    const hasDeclarations = extractorNames.includes("declarations");
+    const hasConditions = extractorNames.includes("conditions");
+    const hasExclusions = extractorNames.includes("exclusions");
+    const hasEndorsements = extractorNames.includes("endorsements");
+    const looksLikeScheduleValues = assignment.hasScheduleValues === true;
+    const roleBlocksCoverageLimits = assignment.pageRole === "policy_form" || assignment.pageRole === "condition_exclusion_form" || assignment.pageRole === "endorsement_form";
+    const inventoryTypes = pageFormTypes.get(assignment.localPageNumber);
+    const inventoryBlocksCoverageLimits = inventoryTypes != null && !looksLikeScheduleValues && !hasDeclarations && (inventoryTypes.has("endorsement") || inventoryTypes.has("notice") || inventoryTypes.has("application"));
+    if (extractorNames.includes("coverage_limits")) {
+      const shouldDropCoverageLimits = inventoryBlocksCoverageLimits || !looksLikeScheduleValues && roleBlocksCoverageLimits || !hasDeclarations && !looksLikeScheduleValues && (hasConditions || hasExclusions) || !hasDeclarations && !looksLikeScheduleValues && hasEndorsements;
+      if (shouldDropCoverageLimits) {
+        extractorNames = extractorNames.filter((name) => name !== "coverage_limits");
+      }
+    }
+    if (inventoryTypes?.has("endorsement") && !extractorNames.includes("endorsements")) {
+      extractorNames = [...extractorNames, "endorsements"];
+    }
+    if (extractorNames.length === 0) {
+      extractorNames = ["sections"];
+    }
+    return {
+      ...assignment,
+      extractorNames
+    };
+  });
+}
+function buildTemplateHints(primaryType, documentType, pageCount, template) {
+  return [
+    `Document type: ${primaryType} ${documentType}`,
+    `Expected sections: ${template.expectedSections.join(", ")}`,
+    `Page hints: ${Object.entries(template.pageHints).map(([k, v]) => `${k}: ${v}`).join("; ")}`,
+    `Total pages: ${pageCount}`
+  ].join("\n");
+}
+function groupContiguousPages(pages) {
+  if (pages.length === 0) return [];
+  const sorted = [...new Set(pages)].sort((a, b) => a - b);
+  const ranges = [];
+  let start = sorted[0];
+  let previous = sorted[0];
+  for (let i = 1; i < sorted.length; i += 1) {
+    const current = sorted[i];
+    if (current === previous + 1) {
+      previous = current;
+      continue;
+    }
+    ranges.push({ startPage: start, endPage: previous });
+    start = current;
+    previous = current;
+  }
+  ranges.push({ startPage: start, endPage: previous });
+  return ranges;
+}
+function buildPlanFromPageAssignments(pageAssignments, pageCount, formInventory) {
+  const extractorPages = /* @__PURE__ */ new Map();
+  for (const assignment of pageAssignments) {
+    const extractors = assignment.extractorNames.length > 0 ? assignment.extractorNames : ["sections"];
+    for (const extractorName of extractors) {
+      extractorPages.set(extractorName, [...extractorPages.get(extractorName) ?? [], assignment.localPageNumber]);
+    }
+  }
+  const coveredPages = /* @__PURE__ */ new Set();
+  for (const pages of extractorPages.values()) {
+    for (const page of pages) coveredPages.add(page);
+  }
+  for (let page = 1; page <= pageCount; page += 1) {
+    if (!coveredPages.has(page)) {
+      extractorPages.set("sections", [...extractorPages.get("sections") ?? [], page]);
+    }
+  }
+  const contextualExtractors = /* @__PURE__ */ new Set(["conditions", "covered_reasons", "definitions", "exclusions", "endorsements"]);
+  const contextualForms = (formInventory?.forms ?? []).filter(
+    (form) => form.pageStart != null && (form.pageEnd ?? form.pageStart) != null
+  );
+  const expandPagesToFormRanges = (extractorName, pages) => {
+    if (!contextualExtractors.has(extractorName)) return pages;
+    const expanded = new Set(pages);
+    for (const page of pages) {
+      for (const form of contextualForms) {
+        const pageStart = form.pageStart;
+        const pageEnd = form.pageEnd ?? form.pageStart;
+        const formType = form.formType;
+        const supportsContextualExpansion = extractorName === "endorsements" ? formType === "endorsement" : formType === "coverage" || formType === "endorsement";
+        if (!supportsContextualExpansion) continue;
+        if (page < pageStart || page > pageEnd) continue;
+        for (let current = pageStart; current <= pageEnd; current += 1) {
+          expanded.add(current);
+        }
+      }
+    }
+    return [...expanded].sort((a, b) => a - b);
+  };
+  const tasks = [...extractorPages.entries()].flatMap(
+    ([extractorName, pages]) => groupContiguousPages(expandPagesToFormRanges(extractorName, pages)).map(({ startPage, endPage }) => ({
+      extractorName,
+      startPage,
+      endPage,
+      description: `Page-mapped ${extractorName} extraction for pages ${startPage}-${endPage}`
+    }))
+  ).sort((a, b) => a.startPage - b.startPage || a.extractorName.localeCompare(b.extractorName));
+  return {
+    tasks,
+    pageMap: [...extractorPages.entries()].map(([section, pages]) => ({
+      section,
+      pages: `pages ${[...new Set(pages)].sort((a, b) => a - b).join(", ")}`
+    }))
+  };
+}
+
 // src/extraction/coordinator.ts
 function createExtractor(config) {
   const {
@@ -6224,6 +6668,7 @@ function createExtractor(config) {
     onCheckpointSave
   } = config;
   const limit = pLimit(concurrency);
+  const extractorCatalog = formatExtractorCatalogForPrompt();
   let totalUsage = { inputTokens: 0, outputTokens: 0 };
   let modelCalls = 0;
   let callsWithUsage = 0;
@@ -6244,43 +6689,56 @@ function createExtractor(config) {
     memory.set(name, mergeExtractorResult(name, existing, data));
   }
   function summarizeExtraction(memory) {
-    const coverageResult = memory.get("coverage_limits");
-    const declarationResult = memory.get("declarations");
-    const endorsementResult = memory.get("endorsements");
-    const exclusionResult = memory.get("exclusions");
-    const conditionResult = memory.get("conditions");
-    const sectionResult = memory.get("sections");
-    const definitionsResult = memory.get("definitions");
-    const coveredReasonsResult = memory.get("covered_reasons");
-    const sections = Array.isArray(sectionResult?.sections) ? sectionResult.sections : [];
-    const definitionCount = Array.isArray(definitionsResult?.definitions) ? definitionsResult.definitions.length : sections.filter((section) => section.type === "definition").length;
-    const coveredReasonCount = Array.isArray(coveredReasonsResult?.coveredReasons) ? coveredReasonsResult.coveredReasons.length : Array.isArray(coveredReasonsResult?.covered_reasons) ? coveredReasonsResult.covered_reasons.length : sections.filter((section) => {
-      const title = String(section.title ?? "").toLowerCase();
-      const type = String(section.type ?? "").toLowerCase();
-      return type === "covered_reason" || title.includes("covered cause") || title.includes("covered reason") || title.includes("covered peril");
-    }).length;
-    const coverageSummary = Array.isArray(coverageResult?.coverages) ? coverageResult.coverages.slice(0, 12).map((coverage) => ({
+    const declarationResult = readMemoryRecord(memory, "declarations");
+    const endorsements = readRecordArray(readMemoryRecord(memory, "endorsements"), "endorsements") ?? [];
+    const exclusions = readRecordArray(readMemoryRecord(memory, "exclusions"), "exclusions") ?? [];
+    const conditions = readRecordArray(readMemoryRecord(memory, "conditions"), "conditions") ?? [];
+    const sections = getSections(memory) ?? [];
+    const definitions = getDefinitions(memory) ?? sections.filter((section) => section.type === "definition");
+    const coveredReasons = getCoveredReasons(memory) ?? sections.filter(looksCoveredReasonSection);
+    const coverages = getCoverageLimitCoverages(memory);
+    const coverageSummary = coverages.slice(0, 12).map((coverage) => ({
       name: coverage.name,
       limit: coverage.limit,
       deductible: coverage.deductible,
       formNumber: coverage.formNumber
-    })) : [];
+    }));
     return JSON.stringify({
       extractedKeys: [...memory.keys()].filter((key) => key !== "classify"),
       declarationFieldCount: Array.isArray(declarationResult?.fields) ? declarationResult.fields.length : 0,
-      coverageCount: Array.isArray(coverageResult?.coverages) ? coverageResult.coverages.length : 0,
+      coverageCount: coverages.length,
       coverageSamples: coverageSummary,
-      endorsementCount: Array.isArray(endorsementResult?.endorsements) ? endorsementResult.endorsements.length : 0,
-      exclusionCount: Array.isArray(exclusionResult?.exclusions) ? exclusionResult.exclusions.length : 0,
-      conditionCount: Array.isArray(conditionResult?.conditions) ? conditionResult.conditions.length : 0,
-      definitionCount,
-      coveredReasonCount,
+      endorsementCount: endorsements.length,
+      exclusionCount: exclusions.length,
+      conditionCount: conditions.length,
+      definitionCount: definitions.length,
+      coveredReasonCount: coveredReasons.length,
       sectionCount: sections.length
     }, null, 2);
   }
+  function textIncludesSupplementarySignal(value) {
+    if (typeof value !== "string") return false;
+    return /\b(supplementary|regulatory|department of insurance|ombudsman|complaint|claim|claims|contact|phone|email|cancellation|cancelled|nonrenewal|non-renewal|non renew|notice|governing law|jurisdiction|third[- ]party administrator|tpa)\b/i.test(value);
+  }
+  function hasSupplementaryExtractionSignal(pageAssignments, formInventory, memory) {
+    const hasPageSignal = pageAssignments.some(
+      (assignment) => assignment.pageRole === "supplementary" || assignment.extractorNames.includes("supplementary") || textIncludesSupplementarySignal(assignment.notes)
+    );
+    if (hasPageSignal) return true;
+    const hasFormSignal = (formInventory?.forms ?? []).some(
+      (form) => form.formType === "notice" || textIncludesSupplementarySignal(form.title) || textIncludesSupplementarySignal(form.formNumber)
+    );
+    if (hasFormSignal) return true;
+    const likelySupplementaryKeys = ["sections", "conditions", "endorsements", "exclusions"];
+    return likelySupplementaryKeys.some((key) => {
+      const value = memory.get(key);
+      if (!value) return false;
+      return textIncludesSupplementarySignal(JSON.stringify(value));
+    });
+  }
   function buildAlreadyExtractedSummary(memory) {
     const lines = [];
-    const declarationResult = memory.get("declarations");
+    const declarationResult = readMemoryRecord(memory, "declarations");
     if (Array.isArray(declarationResult?.fields)) {
       for (const field of declarationResult.fields) {
         if (field.key && field.value) {
@@ -6289,20 +6747,17 @@ function createExtractor(config) {
         }
       }
     }
-    const coverageResult = memory.get("coverage_limits");
-    if (Array.isArray(coverageResult?.coverages)) {
-      for (const cov of coverageResult.coverages) {
-        const parts = [cov.name, cov.limit && `limit=${cov.limit}`, cov.deductible && `deductible=${cov.deductible}`].filter(Boolean);
-        if (parts.length > 0) lines.push(`- coverage: ${parts.join(", ")}`);
-      }
+    for (const cov of getCoverageLimitCoverages(memory)) {
+      const parts = [cov.name, cov.limit && `limit=${cov.limit}`, cov.deductible && `deductible=${cov.deductible}`].filter(Boolean);
+      if (parts.length > 0) lines.push(`- coverage: ${parts.join(", ")}`);
     }
-    const namedInsured = memory.get("named_insured");
+    const namedInsured = getNamedInsured(memory);
     if (namedInsured) {
       for (const [key, value] of Object.entries(namedInsured)) {
         if (value && typeof value === "string") lines.push(`- ${key}: ${value}`);
       }
     }
-    const carrierInfo = memory.get("carrier_info");
+    const carrierInfo = getCarrierInfo(memory);
     if (carrierInfo) {
       for (const [key, value] of Object.entries(carrierInfo)) {
         if (value && typeof value === "string") lines.push(`- ${key}: ${value}`);
@@ -6310,6 +6765,34 @@ function createExtractor(config) {
     }
     return lines.length > 0 ? lines.join("\n") : "";
   }
+  async function runFocusedExtractorTask(task, pdfInput, memory) {
+    if (task.extractorName === "supplementary") {
+      const alreadyExtractedSummary = buildAlreadyExtractedSummary(memory);
+      const result = await runExtractor({
+        name: "supplementary",
+        prompt: buildSupplementaryPrompt(alreadyExtractedSummary),
+        schema: SupplementarySchema,
+        pdfInput,
+        startPage: task.startPage,
+        endPage: task.endPage,
+        generateObject,
+        convertPdfToImages,
+        maxTokens: 4096,
+        providerOptions
+      });
+      trackUsage(result.usage);
+      return result;
+    }
+    return runFocusedExtractorWithFallback({
+      task,
+      pdfInput,
+      generateObject,
+      convertPdfToImages,
+      providerOptions,
+      trackUsage,
+      log
+    });
+  }
   function formatPageMapSummary(pageAssignments) {
     const extractorPages = /* @__PURE__ */ new Map();
     for (const assignment of pageAssignments) {
@@ -6320,132 +6803,6 @@ function createExtractor(config) {
     if (extractorPages.size === 0) return "No page assignments available.";
     return [...extractorPages.entries()].map(([extractorName, pages]) => `${extractorName}: ${pages.length} page(s), pages ${pages.join(", ")}`).join("\n");
   }
-  function normalizePageAssignments(pageAssignments, formInventory) {
-    const pageFormTypes = /* @__PURE__ */ new Map();
-    if (formInventory) {
-      for (const form of formInventory.forms) {
-        if (form.pageStart != null) {
-          const end = form.pageEnd ?? form.pageStart;
-          for (let p = form.pageStart; p <= end; p++) {
-            const types = pageFormTypes.get(p) ?? /* @__PURE__ */ new Set();
-            types.add(form.formType);
-            pageFormTypes.set(p, types);
-          }
-        }
-      }
-    }
-    return pageAssignments.map((assignment) => {
-      let extractorNames = [...new Set(
-        (assignment.extractorNames.length > 0 ? assignment.extractorNames : ["sections"]).filter(Boolean)
-      )];
-      const hasDeclarations = extractorNames.includes("declarations");
-      const hasConditions = extractorNames.includes("conditions");
-      const hasExclusions = extractorNames.includes("exclusions");
-      const hasEndorsements = extractorNames.includes("endorsements");
-      const looksLikeScheduleValues = assignment.hasScheduleValues === true;
-      const roleBlocksCoverageLimits = assignment.pageRole === "policy_form" || assignment.pageRole === "condition_exclusion_form" || assignment.pageRole === "endorsement_form";
-      const inventoryTypes = pageFormTypes.get(assignment.localPageNumber);
-      const inventoryBlocksCoverageLimits = inventoryTypes != null && !looksLikeScheduleValues && !hasDeclarations && (inventoryTypes.has("endorsement") || inventoryTypes.has("notice") || inventoryTypes.has("application"));
-      if (extractorNames.includes("coverage_limits")) {
-        const shouldDropCoverageLimits = inventoryBlocksCoverageLimits || !looksLikeScheduleValues && roleBlocksCoverageLimits || !hasDeclarations && !looksLikeScheduleValues && (hasConditions || hasExclusions) || !hasDeclarations && !looksLikeScheduleValues && hasEndorsements;
-        if (shouldDropCoverageLimits) {
-          extractorNames = extractorNames.filter((name) => name !== "coverage_limits");
-        }
-      }
-      if (inventoryTypes?.has("endorsement") && !extractorNames.includes("endorsements")) {
-        extractorNames = [...extractorNames, "endorsements"];
-      }
-      if (extractorNames.length === 0) {
-        extractorNames = ["sections"];
-      }
-      return {
-        ...assignment,
-        extractorNames
-      };
-    });
-  }
-  function buildTemplateHints(primaryType, documentType, pageCount, template) {
-    return [
-      `Document type: ${primaryType} ${documentType}`,
-      `Expected sections: ${template.expectedSections.join(", ")}`,
-      `Page hints: ${Object.entries(template.pageHints).map(([k, v]) => `${k}: ${v}`).join("; ")}`,
-      `Total pages: ${pageCount}`
-    ].join("\n");
-  }
-  function groupContiguousPages(pages) {
-    if (pages.length === 0) return [];
-    const sorted = [...new Set(pages)].sort((a, b) => a - b);
-    const ranges = [];
-    let start = sorted[0];
-    let previous = sorted[0];
-    for (let i = 1; i < sorted.length; i += 1) {
-      const current = sorted[i];
-      if (current === previous + 1) {
-        previous = current;
-        continue;
-      }
-      ranges.push({ startPage: start, endPage: previous });
-      start = current;
-      previous = current;
-    }
-    ranges.push({ startPage: start, endPage: previous });
-    return ranges;
-  }
-  function buildPlanFromPageAssignments(pageAssignments, pageCount, formInventory) {
-    const extractorPages = /* @__PURE__ */ new Map();
-    for (const assignment of pageAssignments) {
-      const extractors = assignment.extractorNames.length > 0 ? assignment.extractorNames : ["sections"];
-      for (const extractorName of extractors) {
-        extractorPages.set(extractorName, [...extractorPages.get(extractorName) ?? [], assignment.localPageNumber]);
-      }
-    }
-    const coveredPages = /* @__PURE__ */ new Set();
-    for (const pages of extractorPages.values()) {
-      for (const page of pages) coveredPages.add(page);
-    }
-    for (let page = 1; page <= pageCount; page += 1) {
-      if (!coveredPages.has(page)) {
-        extractorPages.set("sections", [...extractorPages.get("sections") ?? [], page]);
-      }
-    }
-    const contextualExtractors = /* @__PURE__ */ new Set(["conditions", "covered_reasons", "definitions", "exclusions", "endorsements"]);
-    const contextualForms = (formInventory?.forms ?? []).filter(
-      (form) => form.pageStart != null && (form.pageEnd ?? form.pageStart) != null
-    );
-    const expandPagesToFormRanges = (extractorName, pages) => {
-      if (!contextualExtractors.has(extractorName)) return pages;
-      const expanded = new Set(pages);
-      for (const page of pages) {
-        for (const form of contextualForms) {
-          const pageStart = form.pageStart;
-          const pageEnd = form.pageEnd ?? form.pageStart;
-          const formType = form.formType;
-          const supportsContextualExpansion = extractorName === "endorsements" ? formType === "endorsement" : formType === "coverage" || formType === "endorsement";
-          if (!supportsContextualExpansion) continue;
-          if (page < pageStart || page > pageEnd) continue;
-          for (let current = pageStart; current <= pageEnd; current += 1) {
-            expanded.add(current);
-          }
-        }
-      }
-      return [...expanded].sort((a, b) => a - b);
-    };
-    const tasks = [...extractorPages.entries()].flatMap(
-      ([extractorName, pages]) => groupContiguousPages(expandPagesToFormRanges(extractorName, pages)).map(({ startPage, endPage }) => ({
-        extractorName,
-        startPage,
-        endPage,
-        description: `Page-mapped ${extractorName} extraction for pages ${startPage}-${endPage}`
-      }))
-    ).sort((a, b) => a.startPage - b.startPage || a.extractorName.localeCompare(b.extractorName));
-    return {
-      tasks,
-      pageMap: [...extractorPages.entries()].map(([section, pages]) => ({
-        section,
-        pages: `pages ${[...new Set(pages)].sort((a, b) => a - b).join(", ")}`
-      }))
-    };
-  }
   async function extract(pdfInput, documentId, options) {
     const id = documentId ?? `doc-${Date.now()}`;
     const memory = /* @__PURE__ */ new Map();
@@ -6456,7 +6813,8 @@ function createExtractor(config) {
     const pipelineCtx = createPipelineContext({
       id,
       onSave: onCheckpointSave,
-      resumeFrom: options?.resumeFrom
+      resumeFrom: options?.resumeFrom,
+      phaseOrder: ["classify", "form_inventory", "page_map", "plan", "extract", "resolve_referential", "review", "assemble"]
     });
     const resumed = pipelineCtx.getCheckpoint()?.state;
     if (resumed?.memory) {
@@ -6624,40 +6982,18 @@ function createExtractor(config) {
       const extractorResults = await Promise.all(
         tasks.map(
           (task) => limit(async () => {
-            const ext = getExtractor(task.extractorName) ?? (task.extractorName === "definitions" || task.extractorName === "covered_reasons" ? getExtractor("sections") : void 0);
-            if (!ext) {
-              await log?.(`Unknown extractor: ${task.extractorName}, skipping`);
-              return null;
-            }
             onProgress?.(`Extracting ${task.extractorName} (pages ${task.startPage}-${task.endPage})...`);
-            try {
-              const result = await runExtractor({
-                name: task.extractorName,
-                prompt: ext.buildPrompt(),
-                schema: ext.schema,
-                pdfInput,
-                startPage: task.startPage,
-                endPage: task.endPage,
-                generateObject,
-                convertPdfToImages,
-                maxTokens: ext.maxTokens ?? 4096,
-                providerOptions
-              });
-              trackUsage(result.usage);
-              return result;
-            } catch (error) {
-              await log?.(`Extractor ${task.extractorName} failed: ${error}`);
-              return null;
-            }
+            return runFocusedExtractorTask(task, pdfInput, memory);
           })
         )
       );
-      for (const result of extractorResults) {
+      for (const result of extractorResults.flatMap((item) => Array.isArray(item) ? item : item ? [item] : [])) {
         if (result) {
           mergeMemoryResult(result.name, result.data, memory);
         }
       }
-      {
+      const planIncludesSupplementary = tasks.some((task) => task.extractorName === "supplementary");
+      if (!planIncludesSupplementary && hasSupplementaryExtractionSignal(pageAssignments, formInventory, memory)) {
         onProgress?.("Extracting supplementary retrieval facts...");
         try {
           const alreadyExtractedSummary = buildAlreadyExtractedSummary(memory);
@@ -6731,7 +7067,7 @@ function createExtractor(config) {
         const reviewResponse = await safeGenerateObject(
           generateObject,
           {
-            prompt: buildReviewPrompt(template.required, extractedKeys, extractionSummary, pageMapSummary),
+            prompt: buildReviewPrompt(template.required, extractedKeys, extractionSummary, pageMapSummary, extractorCatalog),
             schema: ReviewResultSchema,
             maxTokens: 1536,
             providerOptions: await buildPdfProviderOptions(pdfInput, providerOptions)
@@ -6755,31 +7091,11 @@ function createExtractor(config) {
         const followUpResults = await Promise.all(
           reviewResponse.object.additionalTasks.map(
             (task) => limit(async () => {
-              const ext = getExtractor(task.extractorName) ?? (task.extractorName === "definitions" || task.extractorName === "covered_reasons" ? getExtractor("sections") : void 0);
-              if (!ext) return null;
-              try {
-                const result = await runExtractor({
-                  name: task.extractorName,
-                  prompt: ext.buildPrompt(),
-                  schema: ext.schema,
-                  pdfInput,
-                  startPage: task.startPage,
-                  endPage: task.endPage,
-                  generateObject,
-                  convertPdfToImages,
-                  maxTokens: ext.maxTokens ?? 4096,
-                  providerOptions
-                });
-                trackUsage(result.usage);
-                return result;
-              } catch (error) {
-                await log?.(`Follow-up extractor ${task.extractorName} failed: ${error}`);
-                return null;
-              }
+              return runFocusedExtractorTask(task, pdfInput, memory);
             })
           )
         );
-        for (const result of followUpResults) {
+        for (const result of followUpResults.flatMap((item) => Array.isArray(item) ? item : item ? [item] : [])) {
           if (result) {
             mergeMemoryResult(result.name, result.data, memory);
           }
@@ -7818,6 +8134,70 @@ function reviewBatchEmail(text, batchFields) {
   };
 }
 
+// src/application/workflow.ts
+var MAX_DOCUMENT_SEARCH_FIELDS = 5;
+var LOW_VALUE_FIELD_RATIO_LIMIT = 0.6;
+function planApplicationWorkflow(input) {
+  const unfilledFields = input.fields.filter(isUnfilled);
+  const documentSearchFields = planDocumentSearchFields(
+    unfilledFields,
+    input.hasDocumentStore && input.hasMemoryStore
+  );
+  return {
+    runBackfill: input.hasBackfillProvider && unfilledFields.length > 0,
+    runContextAutoFill: input.orgContextCount > 0 && unfilledFields.length > 0,
+    documentSearchFields,
+    runBatching: unfilledFields.length > 0,
+    unfilledFields
+  };
+}
+function planReplyActions(input) {
+  const hasCurrentFields = input.currentBatchFields.length > 0;
+  const nextBatchNeedsAnswers = (input.nextBatchFields ?? []).some(isUnfilled);
+  const hasLookupRequests = (input.intent.lookupRequests?.length ?? 0) > 0;
+  return {
+    parseAnswers: input.intent.hasAnswers && hasCurrentFields,
+    runLookup: hasLookupRequests && input.hasDocumentStore,
+    answerQuestion: Boolean(input.intent.questionText) && (input.intent.primaryIntent === "question" || input.intent.primaryIntent === "mixed"),
+    advanceBatch: hasCurrentFields && input.currentBatchFields.every((field) => !isUnfilled(field)),
+    generateNextEmail: nextBatchNeedsAnswers
+  };
+}
+function planDocumentSearchFields(unfilledFields, hasStores) {
+  if (!hasStores || unfilledFields.length === 0) return [];
+  const searchableFields = unfilledFields.filter(isHighValueLookupField);
+  if (searchableFields.length === 0) return [];
+  const lowValueRatio = 1 - searchableFields.length / unfilledFields.length;
+  if (unfilledFields.length > MAX_DOCUMENT_SEARCH_FIELDS && lowValueRatio > LOW_VALUE_FIELD_RATIO_LIMIT) {
+    return [];
+  }
+  return searchableFields.slice(0, MAX_DOCUMENT_SEARCH_FIELDS);
+}
+function isUnfilled(field) {
+  return field.value === void 0 || field.value.trim() === "";
+}
+function isHighValueLookupField(field) {
+  const text = `${field.section} ${field.label}`.toLowerCase();
+  if (field.required) return true;
+  return [
+    "carrier",
+    "policy",
+    "premium",
+    "limit",
+    "deductible",
+    "insured",
+    "address",
+    "revenue",
+    "payroll",
+    "effective",
+    "expiration",
+    "coverage",
+    "class code",
+    "fein",
+    "entity"
+  ].some((term) => text.includes(term));
+}
+
 // src/application/coordinator.ts
 function createApplicationPipeline(config) {
   const {
@@ -7916,27 +8296,37 @@ function createApplicationPipeline(config) {
     state.updatedAt = Date.now();
     await applicationStore?.save(state);
     onProgress?.(`Auto-filling ${fields.length} fields...`);
-    const fillTasks = [];
-    if (backfillProvider) {
-      fillTasks.push(
-        (async () => {
-          try {
-            const priorAnswers = await backfillFromPriorAnswers(fields, backfillProvider);
-            for (const pa of priorAnswers) {
-              const field = state.fields.find((f) => f.id === pa.fieldId);
-              if (field && !field.value && pa.relevance > 0.8) {
-                field.value = pa.value;
-                field.source = `backfill: ${pa.source}`;
-                field.confidence = "high";
-              }
-            }
-          } catch (e) {
-            await log?.(`Backfill failed: ${e}`);
+    let workflowPlan = planApplicationWorkflow({
+      fields: state.fields,
+      hasBackfillProvider: Boolean(backfillProvider),
+      orgContextCount: orgContext.length,
+      hasDocumentStore: Boolean(documentStore),
+      hasMemoryStore: Boolean(memoryStore)
+    });
+    if (workflowPlan.runBackfill && backfillProvider) {
+      try {
+        const priorAnswers = await backfillFromPriorAnswers(state.fields, backfillProvider);
+        for (const pa of priorAnswers) {
+          const field = state.fields.find((f) => f.id === pa.fieldId);
+          if (field && !field.value && pa.relevance > 0.8) {
+            field.value = pa.value;
+            field.source = `backfill: ${pa.source}`;
+            field.confidence = "high";
           }
-        })()
-      );
+        }
+      } catch (e) {
+        await log?.(`Backfill failed: ${e}`);
+      }
     }
-    if (orgContext.length > 0) {
+    workflowPlan = planApplicationWorkflow({
+      fields: state.fields,
+      hasBackfillProvider: false,
+      orgContextCount: orgContext.length,
+      hasDocumentStore: Boolean(documentStore),
+      hasMemoryStore: Boolean(memoryStore)
+    });
+    const fillTasks = [];
+    if (workflowPlan.runContextAutoFill) {
       fillTasks.push(
         limit(async () => {
           const unfilledFields2 = state.fields.filter((f) => !f.value);
@@ -7963,18 +8353,13 @@ function createApplicationPipeline(config) {
         })
       );
     }
-    if (documentStore && memoryStore) {
+    if (workflowPlan.documentSearchFields.length > 0 && memoryStore) {
       fillTasks.push(
         (async () => {
           try {
-            const unfilledFields2 = state.fields.filter((f) => !f.value);
-            const searchPromises = unfilledFields2.slice(0, 10).map(
+            const searchPromises = workflowPlan.documentSearchFields.map(
               (f) => limit(async () => {
-                const chunks = await memoryStore.search(f.label, { limit: 3 });
-                for (const chunk of chunks) {
-                  if (!state.fields.find((sf) => sf.id === f.id)?.value) {
-                  }
-                }
+                await memoryStore.search(f.label, { limit: 3 });
               })
             );
             await Promise.all(searchPromises);
@@ -7987,8 +8372,15 @@ function createApplicationPipeline(config) {
     await Promise.all(fillTasks);
     state.updatedAt = Date.now();
     await applicationStore?.save(state);
-    const unfilledFields = state.fields.filter((f) => !f.value);
-    if (unfilledFields.length > 0) {
+    workflowPlan = planApplicationWorkflow({
+      fields: state.fields,
+      hasBackfillProvider: false,
+      orgContextCount: 0,
+      hasDocumentStore: false,
+      hasMemoryStore: false
+    });
+    const unfilledFields = workflowPlan.unfilledFields;
+    if (workflowPlan.runBatching) {
       onProgress?.(`Batching ${unfilledFields.length} remaining questions...`);
       state.status = "batching";
       try {
@@ -8055,7 +8447,12 @@ function createApplicationPipeline(config) {
     }
     let fieldsFilled = 0;
     let responseText;
-    if (intent.hasAnswers) {
+    let replyPlan = planReplyActions({
+      intent,
+      currentBatchFields,
+      hasDocumentStore: Boolean(documentStore)
+    });
+    if (replyPlan.parseAnswers) {
       onProgress?.("Parsing answers...");
       try {
         const { result: parseResult, usage: parseUsage } = await parseAnswers(
@@ -8078,7 +8475,7 @@ function createApplicationPipeline(config) {
         await log?.(`Answer parsing failed: ${error instanceof Error ? error.message : String(error)}`);
       }
     }
-    if (intent.lookupRequests?.length) {
+    if (replyPlan.runLookup && intent.lookupRequests?.length) {
       onProgress?.("Processing lookup requests...");
       let availableData = "";
       if (documentStore) {
@@ -8119,64 +8516,78 @@ function createApplicationPipeline(config) {
         }
       }
     }
-    if (intent.primaryIntent === "question" || intent.primaryIntent === "mixed") {
-      if (intent.questionText) {
-        try {
-          const { text, usage } = await generateText({
-            prompt: `The user is filling out an insurance application and asked: "${intent.questionText}"
+    if (replyPlan.answerQuestion && intent.questionText) {
+      try {
+        const { text, usage } = await generateText({
+          prompt: `The user is filling out an insurance application and asked: "${intent.questionText}"
 
 Provide a brief, helpful explanation (2-3 sentences). End with "Just reply with the answer when you're ready and I'll fill it in."`,
-            maxTokens: 512,
-            providerOptions
-          });
-          trackUsage(usage);
-          responseText = text;
-        } catch (error) {
-          await log?.(`Question response generation failed: ${error instanceof Error ? error.message : String(error)}`);
-          responseText = `I wasn't able to generate an explanation for your question. Could you rephrase it, or just provide the answer directly?`;
-        }
+          maxTokens: 512,
+          providerOptions
+        });
+        trackUsage(usage);
+        responseText = text;
+      } catch (error) {
+        await log?.(`Question response generation failed: ${error instanceof Error ? error.message : String(error)}`);
+        responseText = `I wasn't able to generate an explanation for your question. Could you rephrase it, or just provide the answer directly?`;
       }
     }
     const currentBatchComplete = currentBatchFieldIds.every(
       (fid) => state.fields.find((f) => f.id === fid)?.value
     );
-    if (currentBatchComplete && state.batches) {
-      if (state.currentBatchIndex < state.batches.length - 1) {
-        state.currentBatchIndex++;
-        const nextBatchFieldIds = state.batches[state.currentBatchIndex];
-        const nextBatchFields = state.fields.filter(
-          (f) => nextBatchFieldIds.includes(f.id)
-        );
+    let nextBatchIndex;
+    let nextBatchFields;
+    if (state.batches) {
+      for (let index = state.currentBatchIndex + 1; index < state.batches.length; index++) {
+        const candidateFields = state.fields.filter((f) => state.batches[index].includes(f.id));
+        if (candidateFields.some((f) => !f.value)) {
+          nextBatchIndex = index;
+          nextBatchFields = candidateFields;
+          break;
+        }
+      }
+    }
+    replyPlan = planReplyActions({
+      intent,
+      currentBatchFields,
+      nextBatchFields,
+      hasDocumentStore: Boolean(documentStore)
+    });
+    if (currentBatchComplete && replyPlan.advanceBatch && state.batches) {
+      if (nextBatchIndex !== void 0 && nextBatchFields) {
+        state.currentBatchIndex = nextBatchIndex;
         const filledCount = state.fields.filter((f) => f.value).length;
-        try {
-          const { text: emailText, usage: emailUsage } = await generateBatchEmail(
-            nextBatchFields,
-            state.currentBatchIndex,
-            state.batches.length,
-            {
-              appTitle: state.title,
-              totalFieldCount: state.fields.length,
-              filledFieldCount: filledCount,
-              companyName: context?.companyName
-            },
-            generateText,
-            providerOptions
-          );
-          trackUsage(emailUsage);
-          const emailReview = reviewBatchEmail(emailText, nextBatchFields);
-          state.qualityReport = {
-            ...buildApplicationQualityReport(state),
-            emailReview
-          };
-          if (!responseText) {
-            responseText = emailText;
-          } else {
-            responseText += `
+        if (replyPlan.generateNextEmail) {
+          try {
+            const { text: emailText, usage: emailUsage } = await generateBatchEmail(
+              nextBatchFields,
+              state.currentBatchIndex,
+              state.batches.length,
+              {
+                appTitle: state.title,
+                totalFieldCount: state.fields.length,
+                filledFieldCount: filledCount,
+                companyName: context?.companyName
+              },
+              generateText,
+              providerOptions
+            );
+            trackUsage(emailUsage);
+            const emailReview = reviewBatchEmail(emailText, nextBatchFields);
+            state.qualityReport = {
+              ...buildApplicationQualityReport(state),
+              emailReview
+            };
+            if (!responseText) {
+              responseText = emailText;
+            } else {
+              responseText += `
 
 ${emailText}`;
+            }
+          } catch (error) {
+            await log?.(`Batch email generation failed: ${error instanceof Error ? error.message : String(error)}`);
           }
-        } catch (error) {
-          await log?.(`Batch email generation failed: ${error instanceof Error ? error.message : String(error)}`);
         }
       } else {
         state.status = "confirming";
@@ -8990,6 +9401,42 @@ ${item.text}`).join("\n\n");
   return { evidence, contextSummary };
 }
 
+// src/query/workflow.ts
+function shouldRetrieveForClassification(classification) {
+  return classification.requiresDocumentLookup || classification.requiresChunkSearch;
+}
+function buildInitialQueryWorkflowPlan(params) {
+  const { classification, attachmentEvidence } = params;
+  const actions = [];
+  const shouldRetrieve = shouldRetrieveForClassification(classification);
+  if (shouldRetrieve) {
+    actions.push({
+      type: "retrieve",
+      subQuestions: classification.subQuestions,
+      reason: "classification requested document or chunk lookup"
+    });
+  }
+  actions.push({
+    type: "reason",
+    subQuestions: classification.subQuestions,
+    reason: shouldRetrieve ? "answer with retrieved evidence and any attachment evidence" : attachmentEvidence.length > 0 ? "answer with attachment evidence only" : "answer without document retrieval"
+  });
+  actions.push(
+    {
+      type: "verify",
+      reason: "check grounding and request targeted retries when needed"
+    },
+    {
+      type: "respond",
+      reason: "compose final response"
+    }
+  );
+  return { actions, shouldRetrieve };
+}
+function getWorkflowAction(plan, type) {
+  return plan.actions.find((action) => action.type === type);
+}
+
 // src/query/coordinator.ts
 function createQueryAgent(config) {
   const {
@@ -9034,29 +9481,37 @@ function createQueryAgent(config) {
     onProgress?.("Classifying query...");
     const classification = await classify(question, conversationId, attachmentContext);
     await pipelineCtx.save("classify", { classification, attachmentEvidence });
-    onProgress?.(`Retrieving evidence for ${classification.subQuestions.length} sub-question(s)...`);
     const retrieverConfig = {
       documentStore,
       memoryStore,
       retrievalLimit,
       log
     };
-    const retrievalResults = await Promise.all(
-      classification.subQuestions.map(
-        (sq) => limit(() => retrieve(sq, conversationId, retrieverConfig))
-      )
-    );
+    const workflowPlan = buildInitialQueryWorkflowPlan({ classification, attachmentEvidence });
+    const retrieveAction = getWorkflowAction(workflowPlan, "retrieve");
+    const reasonAction = getWorkflowAction(workflowPlan, "reason");
+    await pipelineCtx.save("workflow", { classification, attachmentEvidence, workflowPlan });
+    const retrievalResults = retrieveAction ? await (async () => {
+      onProgress?.(`Retrieving evidence for ${retrieveAction.subQuestions.length} sub-question(s)...`);
+      return Promise.all(
+        retrieveAction.subQuestions.map(
+          (sq) => limit(() => retrieve(sq, conversationId, retrieverConfig))
+        )
+      );
+    })() : [];
     const allEvidence = [...attachmentEvidence, ...retrievalResults.flatMap((r) => r.evidence)];
     await pipelineCtx.save("retrieve", { classification, attachmentEvidence, evidence: allEvidence });
     onProgress?.("Reasoning over evidence...");
     const reasonerConfig = { generateObject, providerOptions };
+    const subQuestionsToReason = reasonAction?.subQuestions ?? classification.subQuestions;
     const reasonResults = await Promise.allSettled(
-      classification.subQuestions.map(
-        (sq, i) => limit(async () => {
+      subQuestionsToReason.map(
+        (sq) => limit(async () => {
+          const retrievedEvidence = retrievalResults.find((r) => r.subQuestion === sq.question)?.evidence ?? [];
           const { subAnswer, usage } = await reason(
             sq.question,
             sq.intent,
-            [...attachmentEvidence, ...retrievalResults[i].evidence],
+            [...attachmentEvidence, ...retrievedEvidence],
             reasonerConfig
           );
           trackUsage(usage);
@@ -9070,9 +9525,9 @@ function createQueryAgent(config) {
       if (result.status === "fulfilled") {
         subAnswers.push(result.value);
       } else {
-        await log?.(`Reasoner failed for sub-question "${classification.subQuestions[i].question}": ${result.reason}`);
+        await log?.(`Reasoner failed for sub-question "${subQuestionsToReason[i].question}": ${result.reason}`);
         subAnswers.push({
-          subQuestion: classification.subQuestions[i].question,
+          subQuestion: subQuestionsToReason[i].question,
           answer: "Unable to answer this part of the question due to a processing error.",
           citations: [],
           confidence: 0,