@claritylabs/cl-sdk 3.0.17 → 3.0.19

package/dist/index.mjs

@@ -9168,6 +9168,17 @@ var OperationalProfilePromptSchema = z41.object({
   sourceNodeIds: z41.array(z41.string()).optional(),
   sourceSpanIds: z41.array(z41.string()).optional()
 });
+function formatFormHintsForPrompt(forms) {
+  const usable = forms.filter((form) => typeof form.pageStart === "number" && typeof form.pageEnd === "number").slice(0, 120).map((form) => ({
+    title: form.title,
+    formType: form.formType,
+    formNumber: form.formNumber,
+    editionDate: form.editionDate,
+    pageStart: form.pageStart,
+    pageEnd: form.pageEnd
+  }));
+  return usable.length ? JSON.stringify(usable, null, 2) : "[]";
+}
 function cleanText(value, fallback) {
   const text = value?.replace(/\s+/g, " ").trim();
   return text || fallback;
@@ -9265,6 +9276,197 @@ function semanticGroupNodeId(documentId, kind, title, childNodeIds) {
     childNodeIds.join("_").replace(/[^a-zA-Z0-9_.:-]/g, "_").slice(0, 80)
   ].join(":");
 }
+function spanPageStart(span) {
+  return span.pageStart ?? span.location?.page ?? span.location?.startPage;
+}
+function spanPageEnd2(span) {
+  return span.pageEnd ?? span.location?.endPage ?? spanPageStart(span);
+}
+function spanSourceUnit(span) {
+  return span.sourceUnit ?? span.metadata?.sourceUnit ?? span.metadata?.elementType;
+}
+function formNumberFromText(value) {
+  return cleanText(value, "").match(/\b[A-Z]{2,}(?:-[A-Z0-9]+)+\s+\d{2}\s+\d{2}\b/)?.[0]?.replace(/\s+/g, " ");
+}
+function editionDateFromFormNumber(formNumber) {
+  const match = formNumber?.match(/\b(\d{2})\s+(\d{2})$/);
+  return match ? `${match[1]}/${match[2]}` : void 0;
+}
+function pageTitleFromText(text, fallback) {
+  const normalized = cleanText(text, fallback);
+  const patterns = [
+    /\bIMPORTANT NOTICE\s+[—-]\s+HOW TO REPORT A CLAIM\b/i,
+    /\bPRIVACY NOTICE TO POLICYHOLDERS\b/i,
+    /\bOFAC ADVISORY NOTICE\b/i,
+    /\bTERRORISM RISK INSURANCE ACT\s*\(TRIA\)\s*DISCLOSURE AND REJECTION\b/i,
+    /\bDECLARATIONS PAGE\b/i,
+    /\bTECHNOLOGY ERRORS?\s*&\s*OMISSIONS AND CYBER LIABILITY INSURANCE POLICY\b/i,
+    /\bTRADE OR ECONOMIC SANCTIONS LIMITATION\b/i,
+    /\bFORMS? AND ENDORSEMENTS\b/i
+  ];
+  for (const pattern of patterns) {
+    const match = normalized.match(pattern)?.[0];
+    if (match) return cleanText(match, fallback);
+  }
+  const endorsement = normalized.match(/\bENDORSEMENT\s+(?:NO\.?|NUMBER|#)\s*[A-Z0-9][A-Z0-9.-]*\b/i)?.[0];
+  if (endorsement) return cleanText(endorsement, fallback);
+  const firstSentence = normalized.split(/(?<=\.)\s+/)[0];
+  if (firstSentence && firstSentence.length <= 120) return firstSentence.replace(/[.]$/, "");
+  return fallback;
+}
+function pageFormTypeFromText(text) {
+  if (/\b(declarations?\s+page|declarations?\s+schedule)\b/i.test(text)) return "declarations";
+  if (/\b(endorsement\s+(?:no\.?|number|#)|this endorsement changes the policy|[A-Z]{2,}-END\s+\d{2,})\b/i.test(text)) return "endorsement";
+  if (/\b(technology errors?\s*&?\s*omissions.*liability insurance policy|policy form|coverage form|insuring agreement|definitions?|exclusions?|conditions?)\b/i.test(text)) return "coverage";
+  if (/\b(important notice|privacy notice|ofac advisory|terrorism risk insurance act|tria|trade or economic sanctions)\b/i.test(text)) return "notice";
+  return "other";
+}
+function inferFormHintsFromSourceSpans(sourceSpans) {
+  const pageTexts = /* @__PURE__ */ new Map();
+  const pageSpanTexts = /* @__PURE__ */ new Map();
+  for (const span of sourceSpans) {
+    const start = spanPageStart(span);
+    if (typeof start !== "number") continue;
+    const end = spanPageEnd2(span) ?? start;
+    for (let page = start; page <= end; page += 1) {
+      if (spanSourceUnit(span) === "page") {
+        pageSpanTexts.set(page, cleanText(span.text, ""));
+        continue;
+      }
+      const existing = pageTexts.get(page) ?? "";
+      if (existing.length < 4e3) pageTexts.set(page, cleanText([existing, span.text].filter(Boolean).join(" "), ""));
+    }
+  }
+  if (pageSpanTexts.size === 0) return [];
+  const pageHints = [.../* @__PURE__ */ new Set([...pageTexts.keys(), ...pageSpanTexts.keys()])].sort((left, right) => left - right).map((page) => {
+    const text = pageSpanTexts.get(page) ?? pageTexts.get(page) ?? "";
+    const formNumber = formNumberFromText(text);
+    return {
+      formNumber,
+      editionDate: editionDateFromFormNumber(formNumber),
+      title: pageTitleFromText(text, `Page ${page}`),
+      formType: pageFormTypeFromText(text),
+      pageStart: page,
+      pageEnd: page
+    };
+  });
+  const merged = [];
+  for (const hint of pageHints) {
+    const previous = merged[merged.length - 1];
+    const startsNewEndorsement = hint.formType === "endorsement" && /\bendorsement\s+(?:no\.?|number|#)\s*[A-Z0-9]|this endorsement changes the policy/i.test(hint.title ?? "");
+    const canMerge = previous && previous.formType === hint.formType && previous.pageEnd !== void 0 && hint.pageStart === previous.pageEnd + 1 && (hint.formType === "declarations" || hint.formType === "coverage" || hint.formType === "endorsement" && !startsNewEndorsement);
+    if (!canMerge) {
+      merged.push(hint);
+      continue;
+    }
+    previous.pageEnd = hint.pageEnd;
+    previous.title = previous.title ?? hint.title;
+    previous.formNumber = previous.formNumber ?? hint.formNumber;
+    previous.editionDate = previous.editionDate ?? hint.editionDate;
+  }
+  return merged;
+}
+function normalizeFormHints(forms, sourceSpans) {
+  const provided = (forms ?? []).filter(
+    (form) => typeof form.pageStart === "number" && typeof form.pageEnd === "number" && form.pageStart > 0 && form.pageEnd >= form.pageStart
+  ).map((form) => ({
+    ...form,
+    title: form.title ? cleanText(form.title, "") : void 0
+  })).sort(
+    (left, right) => (left.pageStart ?? Number.MAX_SAFE_INTEGER) - (right.pageStart ?? Number.MAX_SAFE_INTEGER) || (left.pageEnd ?? Number.MAX_SAFE_INTEGER) - (right.pageEnd ?? Number.MAX_SAFE_INTEGER)
+  );
+  return provided.length ? provided : inferFormHintsFromSourceSpans(sourceSpans);
+}
+function formHintForPage(forms, page) {
+  return forms.find(
+    (form) => typeof form.pageStart === "number" && typeof form.pageEnd === "number" && page >= form.pageStart && page <= form.pageEnd
+  );
+}
+function titleFromFormHint(form, fallback) {
+  if (form.formType === "declarations") return "Declarations";
+  if (form.formType === "coverage") return "Policy Form";
+  if (form.formType === "endorsement") return endorsementTitle([form.title, form.formNumber].filter(Boolean).join(" ")) ?? cleanText(form.title, fallback);
+  return cleanText(form.title, fallback);
+}
+function formGroupConfig(form) {
+  if (form.formType === "declarations") {
+    return {
+      kind: "page_group",
+      title: "Declarations",
+      description: "Declarations pages and schedules grouped from form inventory",
+      organizer: "form_inventory_declarations_grouping"
+    };
+  }
+  if (form.formType === "coverage") {
+    return {
+      kind: "form",
+      title: "Policy Form",
+      description: "Policy form pages grouped from form inventory",
+      organizer: "form_inventory_policy_form_grouping"
+    };
+  }
+  if (form.formType === "endorsement") {
+    const title = titleFromFormHint(form, "Endorsement");
+    return {
+      kind: "endorsement",
+      title,
+      description: `${title} grouped from form inventory`,
+      organizer: "form_inventory_endorsement_grouping"
+    };
+  }
+  return void 0;
+}
+function applyFormInventoryHints(sourceTree, forms) {
+  if (forms.length === 0) return sourceTree;
+  const rootId = sourceTreeRootId(sourceTree);
+  if (!rootId) return sourceTree;
+  const byParent = nodesByParent(sourceTree);
+  const children = (byParent.get(rootId) ?? []).filter((node) => node.kind !== "document").sort((left, right) => left.order - right.order);
+  const rootPages = children.filter((node) => node.kind === "page" && typeof node.pageStart === "number");
+  let nextTree = sourceTree.map((node) => {
+    if (node.kind !== "page" || typeof node.pageStart !== "number") return node;
+    const form = formHintForPage(forms, node.pageStart);
+    if (!form) return node;
+    const isStartPage = form.pageStart === node.pageStart;
+    const shouldRetitle = isStartPage && form.formType !== "other";
+    return {
+      ...node,
+      title: shouldRetitle ? titleFromFormHint(form, node.title) : node.title,
+      metadata: {
+        ...node.metadata,
+        formInventoryHint: {
+          formType: form.formType,
+          formNumber: form.formNumber,
+          title: form.title,
+          pageStart: form.pageStart,
+          pageEnd: form.pageEnd
+        }
+      }
+    };
+  });
+  const claimed = /* @__PURE__ */ new Set();
+  for (const form of forms) {
+    const config = formGroupConfig(form);
+    const pageStart2 = form.pageStart;
+    const pageEnd2 = form.pageEnd;
+    if (!config || typeof pageStart2 !== "number" || typeof pageEnd2 !== "number") continue;
+    const childIds = rootPages.filter(
+      (page) => !claimed.has(page.id) && typeof page.pageStart === "number" && page.pageStart >= pageStart2 && page.pageStart <= pageEnd2
+    ).map((page) => page.id);
+    if (childIds.length === 0) continue;
+    nextTree = groupAdjacentChildren({
+      sourceTree: nextTree,
+      children,
+      childIds,
+      kind: config.kind,
+      title: config.title,
+      description: config.description,
+      organizer: config.organizer
+    });
+    childIds.forEach((id) => claimed.add(id));
+  }
+  return normalizeDocumentSourceTreePaths(nextTree);
+}
 function looksLikeDeclarationsStart(node) {
   const title = cleanText(node.title, "");
   const text = sourceNodeText(node);
@@ -9325,6 +9527,21 @@ function groupAdjacentChildren(params) {
     groupNode
   ];
 }
+function reparentNodes(sourceTree, childIds, parentId, organizerRepair) {
+  const wanted = new Set(childIds);
+  if (wanted.size === 0) return sourceTree;
+  return sourceTree.map(
+    (node) => wanted.has(node.id) ? {
+      ...node,
+      parentId,
+      order: node.order + 1e-3,
+      metadata: {
+        ...node.metadata,
+        organizerRepair
+      }
+    } : node
+  );
+}
 function applySemanticPageGrouping(sourceTree) {
   const relabeled = sourceTree.map((node) => {
     if (node.kind === "document" || node.kind === "page_group") return node;
@@ -9384,7 +9601,13 @@ function applySemanticPageGrouping(sourceTree) {
       if (!looksLikeDeclarationsContinuation(child)) break;
       declarationIds.push(child.id);
     }
-    nextTree = groupAdjacentChildren({
+    const existingDeclarations = children[declarationsStartIndex];
+    nextTree = isDeclarationsNode(existingDeclarations) ? reparentNodes(
+      nextTree,
+      declarationIds.filter((id) => id !== existingDeclarations.id),
+      existingDeclarations.id,
+      "semantic_declarations_continuation"
+    ) : groupAdjacentChildren({
       sourceTree: nextTree,
       children,
       childIds: declarationIds,
@@ -9408,7 +9631,13 @@ function applySemanticPageGrouping(sourceTree) {
       if (!looksLikePolicyFormContinuation(child)) break;
       policyIds.push(child.id);
     }
-    nextTree = groupAdjacentChildren({
+    const existingPolicyForm = children[policyStartIndex];
+    nextTree = isPolicyFormNode(existingPolicyForm) ? reparentNodes(
+      nextTree,
+      policyIds.filter((id) => id !== existingPolicyForm.id),
+      existingPolicyForm.id,
+      "semantic_policy_form_continuation"
+    ) : groupAdjacentChildren({
       sourceTree: nextTree,
       children,
       childIds: policyIds,
@@ -9605,6 +9834,130 @@ function normalizeContainerEvidenceFromChildren(sourceTree) {
   }
   return sourceTree.map((node) => byId.get(node.id) ?? node);
 }
+function metadataText(node, key) {
+  const value = node.metadata?.[key];
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function isTitleBlockNode(node) {
+  if (node.kind !== "text") return false;
+  return metadataText(node, "organizer") === "title_block" || metadataText(node, "elementType") === "title" || metadataText(node, "sourceUnit") === "title";
+}
+function isRejectableSectionHeading(text, container) {
+  const normalized = cleanText(text, "");
+  if (!normalized) return true;
+  if (normalized.length > 160) return true;
+  if (/^page\s+\d+$/i.test(normalized)) return true;
+  if (/^table\s+\d+$/i.test(normalized)) return true;
+  if (/^(document|text|header row|row\s+\d+)$/i.test(normalized)) return true;
+  if (/^(northwoods continental insurance company|specimen policy|for testing only)$/i.test(normalized)) return true;
+  if (/^technology errors?\s*&\s*omissions and cyber liability insurance policy$/i.test(normalized)) return true;
+  if (/^declarations(?:\s+page)?$/i.test(normalized) && /^declarations$/i.test(container.title)) return true;
+  if (/^policy\s+form$/i.test(normalized) && /^policy\s+form$/i.test(container.title)) return true;
+  if (/^endorsement\s+(?:no\.?|number|#)/i.test(normalized) && container.kind === "endorsement") return true;
+  if (/\b(policyholder|policyholders)\b/i.test(normalized) && normalized.length < 40) return true;
+  return false;
+}
+function sectionHeadingTitle(node, container) {
+  if (!isTitleBlockNode(node)) return void 0;
+  const text = cleanText(node.title || node.textExcerpt, "");
+  if (isRejectableSectionHeading(text, container)) return void 0;
+  const words = text.split(/\s+/);
+  if (words.length > 18) return void 0;
+  const structured = /^(SECTION|PART|ARTICLE|SCHEDULE)\b/i.test(text) || /^Item\s+\d+[\.:]/i.test(text) || /^Coverage\s+Part\b/i.test(text) || /^Endorsement\s+(?:No\.?|Number|#)\s+/i.test(text);
+  const uppercaseLetters = [...text].filter((char) => /[A-Z]/.test(char)).length;
+  const lowercaseLetters = [...text].filter((char) => /[a-z]/.test(char)).length;
+  const mostlyUppercase = uppercaseLetters > 0 && uppercaseLetters >= lowercaseLetters * 1.5;
+  const hasSentencePunctuation = /[.;:]\s+\S/.test(text) || /[.;:]$/.test(text);
+  const sentenceLike = /\b(is|are|was|were|will|shall|may|must|means|includes|provided|subject|available|attached|remain|constitutes)\b/i.test(text) && /[a-z]/.test(text);
+  if (!structured && (!mostlyUppercase || hasSentencePunctuation || sentenceLike)) return void 0;
+  return simplifyOrganizerTitle(text, text, node.kind);
+}
+function sectionKindForTitle(title) {
+  if (/^schedule\b/i.test(title) || /\b(forms? and endorsements?|coverage parts?|limits?|premium|declarations?)\b/i.test(title)) return "schedule";
+  if (/^(section|part|article|item)\b/i.test(title)) return "section";
+  return "section";
+}
+function hasAncestor(node, ancestorId, byId) {
+  let parentId = node.parentId;
+  const seen = /* @__PURE__ */ new Set();
+  while (parentId) {
+    if (parentId === ancestorId) return true;
+    if (seen.has(parentId)) return false;
+    seen.add(parentId);
+    parentId = byId.get(parentId)?.parentId;
+  }
+  return false;
+}
+function shouldBuildSectionsForContainer(node) {
+  if (isNoticesGroup(node)) return false;
+  if (isEndorsementGroup(node)) return false;
+  return node.kind === "form" || node.kind === "page_group" || node.kind === "endorsement";
+}
+function applyTitleSectionHierarchy(sourceTree) {
+  const byId = new Map(sourceTree.map((node) => [node.id, node]));
+  const byParent = nodesByParent(sourceTree);
+  const updates = /* @__PURE__ */ new Map();
+  for (const container of sourceTree.filter(shouldBuildSectionsForContainer)) {
+    const pageIds = new Set(
+      sourceTree.filter((node) => node.kind === "page" && hasAncestor(node, container.id, byId)).map((node) => node.id)
+    );
+    if (pageIds.size === 0) continue;
+    const directPageChildren = sourceTree.filter(
+      (node) => node.parentId !== void 0 && pageIds.has(node.parentId) && node.kind !== "table_row" && node.kind !== "table_cell"
+    ).sort(
+      (left, right) => (left.pageStart ?? Number.MAX_SAFE_INTEGER) - (right.pageStart ?? Number.MAX_SAFE_INTEGER) || left.order - right.order || left.id.localeCompare(right.id)
+    );
+    if (directPageChildren.length === 0) continue;
+    let currentSectionId;
+    for (let index = 0; index < directPageChildren.length; index += 1) {
+      const child = directPageChildren[index];
+      const current = updates.get(child.id) ?? child;
+      const heading = sectionHeadingTitle(current, container);
+      if (heading) {
+        const descendants = byParent.get(child.id) ?? [];
+        const hasOwnContent = descendants.some((descendant) => descendant.kind !== "table_row" && descendant.kind !== "table_cell");
+        let hasFollowingContent = false;
+        for (const nextChild of directPageChildren.slice(index + 1)) {
+          const next = updates.get(nextChild.id) ?? nextChild;
+          if (sectionHeadingTitle(next, container)) break;
+          hasFollowingContent = true;
+          break;
+        }
+        if (!hasOwnContent && !hasFollowingContent) {
+          currentSectionId = void 0;
+          continue;
+        }
+        currentSectionId = child.id;
+        updates.set(child.id, {
+          ...current,
+          parentId: container.id,
+          kind: sectionKindForTitle(heading),
+          title: heading,
+          description: descriptionWithPages(cleanText([heading, "section"].join(" "), heading), [current, ...descendants]),
+          metadata: {
+            ...current.metadata,
+            organizer: "title_section",
+            sourceTreeVersion: "v3"
+          }
+        });
+        continue;
+      }
+      if (!currentSectionId) continue;
+      const parent = current.parentId ? byId.get(current.parentId) : void 0;
+      if (!parent || parent.kind !== "page") continue;
+      updates.set(child.id, {
+        ...current,
+        parentId: currentSectionId,
+        metadata: {
+          ...current.metadata,
+          organizerRepair: "title_section_continuation"
+        }
+      });
+    }
+  }
+  if (updates.size === 0) return sourceTree;
+  return normalizeDocumentSourceTreePaths(sourceTree.map((node) => updates.get(node.id) ?? node));
+}
 function normalizeSemanticHierarchy(sourceTree) {
   const normalized = normalizeDocumentSourceTreePaths(
     normalizePolicyFormStructure(
@@ -9613,7 +9966,8 @@ function normalizeSemanticHierarchy(sourceTree) {
   );
   const nested = normalizeDocumentSourceTreePaths(nestEndorsementContinuationPages(normalized));
   const mergedNotices = normalizeDocumentSourceTreePaths(mergeAdministrativeNoticesIntoFrontMatter(nested));
-  const withEvidence = normalizeContainerEvidenceFromChildren(mergedNotices);
+  const sectioned = normalizeDocumentSourceTreePaths(applyTitleSectionHierarchy(mergedNotices));
+  const withEvidence = normalizeContainerEvidenceFromChildren(sectioned);
   return normalizeDocumentSourceTreePaths(
     normalizeRootSemanticOrder(normalizeContainerEvidenceFromChildren(withEvidence))
   );
@@ -9832,7 +10186,7 @@ function mergeOrganizationResults(results) {
     groups: [...groups.values()]
   };
 }
-function buildOrganizationPrompt(batch) {
+function buildOrganizationPrompt(batch, formHints) {
   const nodes = batch.nodes.map((node) => compactNode(node, node.kind === "page" ? 900 : 320));
   return `You organize an insurance document source tree.
 
@@ -9841,10 +10195,15 @@ Scope:
 - The provided list is a bounded extraction-time batch. It is not necessarily the whole document.
 - Top-level page/form candidates in this batch: ${JSON.stringify(batch.topLevelNodeIds)}
 
+Expected form inventory / page ranges:
+${formatFormHintsForPrompt(formHints)}
+
 Rules:
 - Use only node IDs from the provided list.
 - Do not invent text, page numbers, source spans, limits, or policy facts.
 - You may relabel existing nodes and group adjacent top-level/page nodes from this batch only when they are clearly one continuous form, one declarations set, one schedule, or one clause family.
+- Treat the form inventory as a page-range hint for the expected order: front matter/notices, declarations, policy form, then endorsements.
+- Prefer section hierarchy from printed title elements inside a form over page-by-page grouping.
 - Group adjacent separately numbered endorsements under a single generic "Endorsements" page_group parent, with each individual endorsement preserved as its own child node.
 - Never create rollup titles such as "Endorsements 1-3 (...)" or merge multiple endorsements into one endorsement node.
 - Add concise, human-readable titles to generic text, table, row, and cell nodes when the text makes their role clear.
@@ -9868,7 +10227,7 @@ function shouldRunOutlineCleanup(sourceTree) {
   if (hasDeclarations && hasPolicyForm && hasEndorsements) return false;
   return genericPages.length > 0 || topLevel.length > 6 || !hasDeclarations || !hasPolicyForm || !hasEndorsements;
 }
-function buildOutlineCleanupPrompt(sourceTree) {
+function buildOutlineCleanupPrompt(sourceTree, formHints) {
   const topLevel = rootChildren(sourceTree).slice(0, OUTLINE_CLEANUP_MAX_TOP_LEVEL_NODES);
   const nodes = topLevel.map((node) => compactNode(node, 900));
   return `You clean a top-level source outline for an insurance policy.
@@ -9879,6 +10238,9 @@ Expected product-facing order:
 3. Policy Form: the main policy wording, insuring agreements, definitions, exclusions, conditions, claim provisions, and general policy terms.
 4. Endorsements: one generic "Endorsements" page_group containing each separately numbered endorsement as its own child.
 
+Expected form inventory / page ranges:
+${formatFormHintsForPrompt(formHints)}
+
 Rules:
 - Use only node IDs from this top-level list: ${JSON.stringify(topLevel.map((node) => node.id))}
 - Group only adjacent top-level nodes.
@@ -9887,6 +10249,7 @@ Rules:
 - Use canonical terse titles: "Notices and Jacket", "Declarations", "Policy Form", "Endorsements", or the printed endorsement number.
 - Keep page_group descriptions short and include the page range when pages are known, for example "Declarations pages 6-8".
 - If a page is an OFAC, privacy, terrorism/TRIA, claim-reporting notice, signature page, or jacket, do not label it as declarations or policy form.
+- If the form inventory provides page ranges, keep groups aligned to those ranges unless the source node text clearly contradicts them.
 - If the existing deterministic outline is already correct, return empty labels and groups.
 
 Top-level source nodes:
@@ -10061,6 +10424,14 @@ function materializeDocument(params) {
     insuredName,
     premium,
     policyTypes: profile.policyTypes,
+    formInventory: params.formInventory.filter((form) => typeof form.formNumber === "string" && form.formNumber.trim().length > 0).map((form) => ({
+      formNumber: form.formNumber,
+      editionDate: form.editionDate,
+      title: form.title,
+      formType: form.formType,
+      pageStart: form.pageStart,
+      pageEnd: form.pageEnd
+    })),
     coverages,
     documentMetadata,
     documentOutline,
@@ -10101,7 +10472,8 @@ function materializeDocument(params) {
 }
 async function runSourceTreeExtraction(params) {
   const sourceSpans = normalizeSourceSpans(params.sourceSpans);
-  let sourceTree = applySemanticPageGrouping(buildDocumentSourceTree(sourceSpans, params.id));
+  const formHints = normalizeFormHints(params.formInventory?.forms, sourceSpans);
+  let sourceTree = applySemanticPageGrouping(applyFormInventoryHints(buildDocumentSourceTree(sourceSpans, params.id), formHints));
   const warnings = [];
   let modelCalls = 0;
   let callsWithUsage = 0;
@@ -10133,7 +10505,7 @@ async function runSourceTreeExtraction(params) {
         const response = await safeGenerateObject(
           params.generateObject,
           {
-            prompt: buildOrganizationPrompt(batch),
+            prompt: buildOrganizationPrompt(batch, formHints),
             schema: SourceTreeOrganizationSchema,
             maxTokens: budget.maxTokens,
             taskKind: "extraction_source_tree",
@@ -10167,7 +10539,7 @@ async function runSourceTreeExtraction(params) {
       const response = await safeGenerateObject(
         params.generateObject,
         {
-          prompt: buildOutlineCleanupPrompt(sourceTree),
+          prompt: buildOutlineCleanupPrompt(sourceTree, formHints),
           schema: SourceTreeOrganizationSchema,
           maxTokens,
           taskKind: "extraction_source_tree",
@@ -10232,12 +10604,14 @@ async function runSourceTreeExtraction(params) {
   const document = materializeDocument({
     id: params.id,
     sourceTree,
+    formInventory: formHints,
     operationalProfile
   });
   return {
     sourceTree,
     sourceSpans,
     sourceChunks: chunkSourceSpans(sourceSpans),
+    formInventory: formHints,
     operationalProfile,
     document,
     chunks: [],
@@ -10587,16 +10961,66 @@ ${span.text}` : span.text;
       }
     }
     if (sourceSpans.length > 0) {
+      const pageCount2 = Math.max(
+        1,
+        ...sourceSpans.map((span) => span.pageEnd ?? span.pageStart ?? span.location?.endPage ?? span.location?.page ?? 1)
+      );
+      let formInventory2 = options?.formInventory;
+      if (!formInventory2) {
+        onProgress?.("Building form inventory from source spans...");
+        const budget = resolveBudget("extraction_form_inventory", 2048);
+        const startedAt = Date.now();
+        const templateHints2 = buildTemplateHints("other", "policy", pageCount2, getTemplate("other"));
+        const sourceText = formatSourceSpanText(sourceSpans);
+        const prompt = `${buildFormInventoryPrompt(templateHints2)}
+
+SOURCE SPAN DOCUMENT TEXT:
+${sourceText}`;
+        const response = await safeGenerateObject(
+          generateObject,
+          {
+            prompt,
+            schema: FormInventorySchema,
+            maxTokens: budget.maxTokens,
+            taskKind: "extraction_form_inventory",
+            budgetDiagnostics: budget
+          },
+          {
+            fallback: { forms: [] },
+            log,
+            onError: (err, attempt) => log?.(`Form inventory attempt ${attempt + 1} failed: ${err instanceof Error ? err.message : String(err)}`)
+          }
+        );
+        trackUsage(response.usage, {
+          taskKind: "extraction_form_inventory",
+          label: "form_inventory",
+          maxTokens: budget.maxTokens,
+          durationMs: Date.now() - startedAt
+        });
+        formInventory2 = response.object;
+      }
       onProgress?.("Building source-native document tree...");
       const v3 = await runSourceTreeExtraction({
         id,
         sourceSpans,
+        formInventory: formInventory2,
         generateObject,
         providerOptions: activeProviderOptions,
         resolveBudget,
         trackUsage,
         log
       });
+      const sourceTreeFormInventory = v3.formInventory.flatMap((form) => {
+        const formNumber = typeof form.formNumber === "string" ? form.formNumber.trim() : "";
+        if (!formNumber) return [];
+        return [{
+          formNumber,
+          title: form.title,
+          pageStart: form.pageStart,
+          pageEnd: form.pageEnd,
+          sources: ["source_tree"]
+        }];
+      });
       const reviewReport2 = {
         issues: v3.warnings.map((warning) => ({
           code: "source_tree_warning",
@@ -10610,7 +11034,7 @@ ${span.text}` : span.text;
           { kind: "operational_profile", label: "Operational Profile", itemCount: v3.operationalProfile.coverages.length }
         ],
         reviewRoundRecords: [],
-        formInventory: [],
+        formInventory: sourceTreeFormInventory,
         qualityGateStatus: v3.warnings.length > 0 ? "warning" : "passed"
       };
       if (shouldFailQualityGate(qualityGate, reviewReport2.qualityGateStatus)) {