@claritylabs/cl-sdk 3.0.17 → 3.0.18

package/README.md

@@ -12,7 +12,7 @@ npm install @claritylabs/cl-sdk pdf-lib zod
 
 ## What It Does
 
-- **Document Extraction** — Source-tree extraction that turns parser-provided PDF spans into a canonical hierarchy of document, page group, form, endorsement, section, schedule, clause, table, row, cell, and text nodes. Operational policy facts are source-backed projections from that tree, not the canonical source of truth.
+- **Document Extraction** — Source-tree extraction that turns parser-provided PDF spans into a canonical hierarchy of document, page group, form, endorsement, section, schedule, clause, table, row, cell, and text nodes. Form-inventory page ranges and parser title elements guide the hierarchy, but every node remains backed by real source spans. Operational policy facts are projections from that tree, not the canonical source of truth.
 - **Source Grounding** — Shared source spans, source nodes, hierarchical table row/cell evidence, source stores, quoted evidence validation, and deterministic evidence ordering across extraction, query, application, PCE, and case workflows.
 - **Query Agent** — Citation-backed question answering over stored source nodes, exact source spans, and inbound photos/PDFs/text with sub-question decomposition, bounded retrieval planning, attachment-only reasoning when retrieval is unnecessary, and grounding verification.
 - **Application Processing** — Bounded workflows handle intake with deterministic planning — field extraction, prior-answer backfill, context auto-fill, document lookup gating, topic-based question batching, reply parsing, source-backed field provenance, and PDF mapping
@@ -81,7 +81,7 @@ const extractor = createExtractor({ generateText, generateObject, sourceStore })
 const result = await extractor.extract(pdfBase64, "policy-123", { sourceSpans });
 ```
 
-When source spans are available, extraction returns `sourceTree`, `sourceSpans`, `operationalProfile`, `warnings`, `tokenUsage`, and `performanceReport`. The source tree is canonical for policy wording and hierarchy. The operational profile contains policy metadata, parties, coverage lines, limits, deductibles, premiums, key dates, and endorsement-support facts, each with `sourceNodeIds` and `sourceSpanIds`.
+When source spans are available, extraction returns `sourceTree`, `sourceSpans`, `operationalProfile`, `warnings`, `tokenUsage`, and `performanceReport`. The source tree is canonical for policy wording and hierarchy. The extractor uses form/page-range hints to group declarations, policy forms, and endorsements, then promotes title elements into section/schedule nodes that can span page breaks. The operational profile contains policy metadata, parties, coverage lines, limits, deductibles, premiums, key dates, and endorsement-support facts, each with `sourceNodeIds` and `sourceSpanIds`.
 
 Store `result.sourceTree` in a retrievable node index and embed node `description` values for search. Keep `result.sourceSpans` as the exact PDF highlighting layer. `result.document` and its `documentOutline` remain compatibility projections for existing host screens; do not treat broad structured policy JSON as canonical extraction truth.
 

package/dist/index.d.mts

@@ -34613,6 +34613,8 @@ interface ExtractionResult {
 interface ExtractOptions {
     /** Resume extraction from a previously saved checkpoint. */
     resumeFrom?: PipelineCheckpoint<ExtractionState>;
+    /** Optional form inventory/page-range hints to guide v3 source-tree hierarchy when source spans are provided. */
+    formInventory?: FormInventoryResult;
     /** Caller-provided raw source spans for this document, reused for evidence grounding and optional persistence. */
     sourceSpans?: SourceSpan[];
 }
@@ -34621,10 +34623,19 @@ declare function createExtractor(config: ExtractorConfig): {
     extract: (input: ExtractionInput, documentId?: string, options?: ExtractOptions) => Promise<ExtractionResult>;
 };
 
+type SourceTreeFormHint = {
+    formNumber?: string;
+    editionDate?: string;
+    title?: string;
+    formType: "coverage" | "endorsement" | "declarations" | "application" | "notice" | "other";
+    pageStart?: number;
+    pageEnd?: number;
+};
 type ExtractionV3Result = {
     sourceTree: DocumentSourceNode[];
     sourceSpans: SourceSpan[];
     sourceChunks: SourceChunk[];
+    formInventory: SourceTreeFormHint[];
     operationalProfile: PolicyOperationalProfile;
     document: InsuranceDocument;
     chunks: [];

package/dist/index.d.ts

@@ -34613,6 +34613,8 @@ interface ExtractionResult {
 interface ExtractOptions {
     /** Resume extraction from a previously saved checkpoint. */
     resumeFrom?: PipelineCheckpoint<ExtractionState>;
+    /** Optional form inventory/page-range hints to guide v3 source-tree hierarchy when source spans are provided. */
+    formInventory?: FormInventoryResult;
     /** Caller-provided raw source spans for this document, reused for evidence grounding and optional persistence. */
     sourceSpans?: SourceSpan[];
 }
@@ -34621,10 +34623,19 @@ declare function createExtractor(config: ExtractorConfig): {
     extract: (input: ExtractionInput, documentId?: string, options?: ExtractOptions) => Promise<ExtractionResult>;
 };
 
+type SourceTreeFormHint = {
+    formNumber?: string;
+    editionDate?: string;
+    title?: string;
+    formType: "coverage" | "endorsement" | "declarations" | "application" | "notice" | "other";
+    pageStart?: number;
+    pageEnd?: number;
+};
 type ExtractionV3Result = {
     sourceTree: DocumentSourceNode[];
     sourceSpans: SourceSpan[];
     sourceChunks: SourceChunk[];
+    formInventory: SourceTreeFormHint[];
     operationalProfile: PolicyOperationalProfile;
     document: InsuranceDocument;
     chunks: [];

package/dist/index.js

@@ -9515,6 +9515,17 @@ var OperationalProfilePromptSchema = import_zod41.z.object({
   sourceNodeIds: import_zod41.z.array(import_zod41.z.string()).optional(),
   sourceSpanIds: import_zod41.z.array(import_zod41.z.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;
@@ -9612,6 +9623,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);
@@ -9672,6 +9874,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;
@@ -9731,7 +9948,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,
@@ -9755,7 +9978,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,
@@ -9952,6 +10181,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(
@@ -9960,7 +10313,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))
   );
@@ -10179,7 +10533,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.
 
@@ -10188,10 +10542,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.
@@ -10215,7 +10574,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.
@@ -10226,6 +10585,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.
@@ -10234,6 +10596,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:
@@ -10408,6 +10771,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,
@@ -10448,7 +10819,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;
@@ -10480,7 +10852,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",
@@ -10514,7 +10886,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",
@@ -10579,12 +10951,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: [],
@@ -10938,12 +11312,24 @@ ${span.text}` : span.text;
       const v3 = await runSourceTreeExtraction({
         id,
         sourceSpans,
+        formInventory: options?.formInventory,
         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",
@@ -10957,7 +11343,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)) {