@claritylabs/cl-sdk 1.3.8 → 2.0.1

package/dist/index.js

@@ -103,6 +103,11 @@ __export(index_exports, {
   DeductibleTypeSchema: () => DeductibleTypeSchema,
   DefenseCostTreatmentSchema: () => DefenseCostTreatmentSchema,
   DefinitionSchema: () => DefinitionSchema,
+  DocumentAgentGuidanceSchema: () => DocumentAgentGuidanceSchema,
+  DocumentMetadataSchema: () => DocumentMetadataSchema,
+  DocumentNodeSchema: () => DocumentNodeSchema,
+  DocumentPageMapEntrySchema: () => DocumentPageMapEntrySchema,
+  DocumentTableOfContentsEntrySchema: () => DocumentTableOfContentsEntrySchema,
   DocumentTypeSchema: () => DocumentTypeSchema,
   DriverRecordSchema: () => DriverRecordSchema,
   DwellingDetailsSchema: () => DwellingDetailsSchema,
@@ -905,14 +910,20 @@ var FormReferenceSchema = import_zod3.z.object({
   title: import_zod3.z.string().optional(),
   formType: import_zod3.z.enum(["coverage", "endorsement", "declarations", "application", "notice", "other"]),
   pageStart: import_zod3.z.number().optional(),
-  pageEnd: import_zod3.z.number().optional()
+  pageEnd: import_zod3.z.number().optional(),
+  documentNodeId: import_zod3.z.string().optional(),
+  sourceSpanIds: import_zod3.z.array(import_zod3.z.string()).optional(),
+  sourceTextHash: import_zod3.z.string().optional()
 });
 var TaxFeeItemSchema = import_zod3.z.object({
   name: import_zod3.z.string(),
   amount: import_zod3.z.string(),
   amountValue: import_zod3.z.number().optional(),
   type: import_zod3.z.enum(["tax", "fee", "surcharge", "assessment"]).optional(),
-  description: import_zod3.z.string().optional()
+  description: import_zod3.z.string().optional(),
+  documentNodeId: import_zod3.z.string().optional(),
+  sourceSpanIds: import_zod3.z.array(import_zod3.z.string()).optional(),
+  sourceTextHash: import_zod3.z.string().optional()
 });
 var RatingBasisSchema = import_zod3.z.object({
   type: RatingBasisTypeSchema,
@@ -968,6 +979,7 @@ var CoverageSchema = import_zod4.z.object({
   sectionRef: import_zod4.z.string().optional(),
   originalContent: import_zod4.z.string().optional(),
   recordId: import_zod4.z.string().optional(),
+  documentNodeId: import_zod4.z.string().optional(),
   sourceSpanIds: import_zod4.z.array(import_zod4.z.string()).optional(),
   sourceTextHash: import_zod4.z.string().optional()
 });
@@ -997,6 +1009,7 @@ var EnrichedCoverageSchema = import_zod4.z.object({
   sectionRef: import_zod4.z.string().optional(),
   originalContent: import_zod4.z.string().optional(),
   recordId: import_zod4.z.string().optional(),
+  documentNodeId: import_zod4.z.string().optional(),
   sourceSpanIds: import_zod4.z.array(import_zod4.z.string()).optional(),
   sourceTextHash: import_zod4.z.string().optional()
 });
@@ -1025,6 +1038,7 @@ var EndorsementSchema = import_zod5.z.object({
   pageStart: import_zod5.z.number(),
   pageEnd: import_zod5.z.number().optional(),
   recordId: import_zod5.z.string().optional(),
+  documentNodeId: import_zod5.z.string().optional(),
   sourceSpanIds: import_zod5.z.array(import_zod5.z.string()).optional(),
   sourceTextHash: import_zod5.z.string().optional()
 });
@@ -1043,6 +1057,7 @@ var ExclusionSchema = import_zod6.z.object({
   content: import_zod6.z.string(),
   pageNumber: import_zod6.z.number().optional(),
   recordId: import_zod6.z.string().optional(),
+  documentNodeId: import_zod6.z.string().optional(),
   sourceSpanIds: import_zod6.z.array(import_zod6.z.string()).optional(),
   sourceTextHash: import_zod6.z.string().optional()
 });
@@ -1060,6 +1075,7 @@ var PolicyConditionSchema = import_zod7.z.object({
   keyValues: import_zod7.z.array(ConditionKeyValueSchema).optional(),
   pageNumber: import_zod7.z.number().optional(),
   recordId: import_zod7.z.string().optional(),
+  documentNodeId: import_zod7.z.string().optional(),
   sourceSpanIds: import_zod7.z.array(import_zod7.z.string()).optional(),
   sourceTextHash: import_zod7.z.string().optional()
 });
@@ -1636,6 +1652,7 @@ var SubsectionSchema = import_zod16.z.object({
   pageNumber: import_zod16.z.number().optional(),
   excerpt: import_zod16.z.string().optional(),
   content: import_zod16.z.string().optional(),
+  documentNodeId: import_zod16.z.string().optional(),
   sourceSpanIds: import_zod16.z.array(import_zod16.z.string()).optional(),
   sourceTextHash: import_zod16.z.string().optional()
 });
@@ -1650,6 +1667,7 @@ var SectionSchema = import_zod16.z.object({
   content: import_zod16.z.string().optional(),
   subsections: import_zod16.z.array(SubsectionSchema).optional(),
   recordId: import_zod16.z.string().optional(),
+  documentNodeId: import_zod16.z.string().optional(),
   sourceSpanIds: import_zod16.z.array(import_zod16.z.string()).optional(),
   sourceTextHash: import_zod16.z.string().optional()
 });
@@ -1663,13 +1681,19 @@ var UnderwritingConditionSchema = import_zod16.z.object({
 var PremiumLineSchema = import_zod16.z.object({
   line: import_zod16.z.string(),
   amount: import_zod16.z.string(),
-  amountValue: import_zod16.z.number().optional()
+  amountValue: import_zod16.z.number().optional(),
+  documentNodeId: import_zod16.z.string().optional(),
+  sourceSpanIds: import_zod16.z.array(import_zod16.z.string()).optional(),
+  sourceTextHash: import_zod16.z.string().optional()
 });
 var AuxiliaryFactSchema = import_zod16.z.object({
   key: import_zod16.z.string(),
   value: import_zod16.z.string(),
   subject: import_zod16.z.string().optional(),
-  context: import_zod16.z.string().optional()
+  context: import_zod16.z.string().optional(),
+  documentNodeId: import_zod16.z.string().optional(),
+  sourceSpanIds: import_zod16.z.array(import_zod16.z.string()).optional(),
+  sourceTextHash: import_zod16.z.string().optional()
 });
 var DefinitionSchema = import_zod16.z.object({
   term: import_zod16.z.string(),
@@ -1680,6 +1704,7 @@ var DefinitionSchema = import_zod16.z.object({
   sectionRef: import_zod16.z.string().optional(),
   originalContent: import_zod16.z.string().optional(),
   recordId: import_zod16.z.string().optional(),
+  documentNodeId: import_zod16.z.string().optional(),
   sourceSpanIds: import_zod16.z.array(import_zod16.z.string()).optional(),
   sourceTextHash: import_zod16.z.string().optional()
 });
@@ -1697,9 +1722,60 @@ var CoveredReasonSchema = import_zod16.z.object({
   sectionRef: import_zod16.z.string().optional(),
   originalContent: import_zod16.z.string().optional(),
   recordId: import_zod16.z.string().optional(),
+  documentNodeId: import_zod16.z.string().optional(),
   sourceSpanIds: import_zod16.z.array(import_zod16.z.string()).optional(),
   sourceTextHash: import_zod16.z.string().optional()
 });
+var DocumentTableOfContentsEntrySchema = import_zod16.z.object({
+  title: import_zod16.z.string(),
+  level: import_zod16.z.number().int().positive().optional(),
+  pageStart: import_zod16.z.number().optional(),
+  pageEnd: import_zod16.z.number().optional(),
+  documentNodeId: import_zod16.z.string().optional(),
+  sourceSpanIds: import_zod16.z.array(import_zod16.z.string()).optional()
+});
+var DocumentPageMapEntrySchema = import_zod16.z.object({
+  page: import_zod16.z.number().int().positive(),
+  label: import_zod16.z.string().optional(),
+  formNumber: import_zod16.z.string().optional(),
+  formTitle: import_zod16.z.string().optional(),
+  sectionTitle: import_zod16.z.string().optional(),
+  extractorNames: import_zod16.z.array(import_zod16.z.string()).optional(),
+  sourceSpanIds: import_zod16.z.array(import_zod16.z.string()).optional()
+});
+var DocumentAgentGuidanceSchema = import_zod16.z.object({
+  kind: import_zod16.z.string(),
+  title: import_zod16.z.string(),
+  detail: import_zod16.z.string(),
+  sourceSpanIds: import_zod16.z.array(import_zod16.z.string()).optional()
+});
+var DocumentMetadataSchema = import_zod16.z.object({
+  formInventory: import_zod16.z.array(FormReferenceSchema).optional(),
+  tableOfContents: import_zod16.z.array(DocumentTableOfContentsEntrySchema).optional(),
+  pageMap: import_zod16.z.array(DocumentPageMapEntrySchema).optional(),
+  agentGuidance: import_zod16.z.array(DocumentAgentGuidanceSchema).optional()
+});
+var DocumentNodeSchema = import_zod16.z.lazy(
+  () => import_zod16.z.object({
+    id: import_zod16.z.string(),
+    title: import_zod16.z.string(),
+    originalTitle: import_zod16.z.string().optional(),
+    type: import_zod16.z.string().optional(),
+    label: import_zod16.z.string().optional(),
+    level: import_zod16.z.number().int().positive().optional(),
+    sectionNumber: import_zod16.z.string().optional(),
+    pageStart: import_zod16.z.number().optional(),
+    pageEnd: import_zod16.z.number().optional(),
+    formNumber: import_zod16.z.string().optional(),
+    formTitle: import_zod16.z.string().optional(),
+    excerpt: import_zod16.z.string().optional(),
+    content: import_zod16.z.string().optional(),
+    interpretationLabels: import_zod16.z.array(import_zod16.z.string()).optional(),
+    sourceSpanIds: import_zod16.z.array(import_zod16.z.string()).optional(),
+    sourceTextHash: import_zod16.z.string().optional(),
+    children: import_zod16.z.array(DocumentNodeSchema).optional()
+  })
+);
 var BaseDocumentFields = {
   id: import_zod16.z.string(),
   carrier: import_zod16.z.string(),
@@ -1710,6 +1786,8 @@ var BaseDocumentFields = {
   summary: import_zod16.z.string().optional(),
   policyTypes: import_zod16.z.array(import_zod16.z.string()).optional(),
   coverages: import_zod16.z.array(CoverageSchema),
+  documentMetadata: DocumentMetadataSchema,
+  documentOutline: import_zod16.z.array(DocumentNodeSchema),
   sections: import_zod16.z.array(SectionSchema).optional(),
   definitions: import_zod16.z.array(DefinitionSchema).optional(),
   coveredReasons: import_zod16.z.array(CoveredReasonSchema).optional(),
@@ -3609,6 +3687,8 @@ function assembleDocument(documentId, documentType, memory) {
     carrier: readRecordValue(carrier, "carrierName") ?? "Unknown",
     insuredName: readRecordValue(insured, "insuredName") ?? "Unknown",
     coverages: coverageRecords,
+    documentMetadata: {},
+    documentOutline: [],
     policyTypes: readRecordValue(classify, "policyTypes"),
     ...sanitizeNulls(carrier ?? {}),
     ...sanitizeNulls(insured ?? {}),
@@ -3660,6 +3740,247 @@ function assembleDocument(documentId, documentType, memory) {
   return doc;
 }
 
+// src/extraction/document-structure.ts
+var FACT_ARRAY_PATHS = [
+  "coverages",
+  "enrichedCoverages",
+  "endorsements",
+  "exclusions",
+  "conditions",
+  "definitions",
+  "coveredReasons",
+  "taxesAndFees",
+  "premiumBreakdown",
+  "supplementaryFacts"
+];
+function slugPart(value) {
+  const text = String(value ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return text || "node";
+}
+function numberValue(record, ...keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return void 0;
+}
+function stringValue2(record, ...keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return void 0;
+}
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.length > 0) : [];
+}
+function sourceUnit3(span) {
+  return span.sourceUnit ?? span.metadata?.sourceUnit;
+}
+function spanPage(span) {
+  return span.pageStart ?? span.location?.page ?? span.location?.startPage;
+}
+function spanPageEnd(span) {
+  return span.pageEnd ?? span.location?.endPage ?? spanPage(span);
+}
+function sourceSpansForPage(sourceSpans, page) {
+  return sourceSpans.filter((span) => spanPage(span) === page && sourceUnit3(span) === "page").map((span) => span.id);
+}
+function nodePageOverlaps(node, record) {
+  const recordStart = numberValue(record, "pageNumber", "pageStart", "resolvedFromPage");
+  const recordEnd = numberValue(record, "pageNumber", "pageEnd", "resolvedFromPage") ?? recordStart;
+  if (!recordStart) return false;
+  const nodeStart = node.pageStart ?? node.pageEnd;
+  const nodeEnd = node.pageEnd ?? node.pageStart;
+  if (!nodeStart) return false;
+  return recordStart <= (nodeEnd ?? nodeStart) && (recordEnd ?? recordStart) >= nodeStart;
+}
+function nodeFormMatches(node, record) {
+  const formNumber = stringValue2(record, "formNumber");
+  return Boolean(formNumber && node.formNumber && formNumber.toLowerCase() === node.formNumber.toLowerCase());
+}
+function nodeSourceOverlaps(node, record) {
+  const nodeSourceIds = new Set(node.sourceSpanIds ?? []);
+  if (nodeSourceIds.size === 0) return false;
+  return stringArray(record.sourceSpanIds).some((id) => nodeSourceIds.has(id));
+}
+function findBestNode(nodes, record) {
+  let best;
+  const visit = (node) => {
+    let score = 0;
+    if (nodeSourceOverlaps(node, record)) score += 8;
+    if (nodeFormMatches(node, record)) score += 4;
+    if (nodePageOverlaps(node, record)) score += 3;
+    if (score > 0 && (!best || score > best.score)) {
+      best = { node, score };
+    }
+    for (const child of node.children ?? []) visit(child);
+  };
+  for (const node of nodes) visit(node);
+  return best?.node;
+}
+function attachDocumentNodeIds(document, nodes) {
+  const doc = document;
+  for (const path of FACT_ARRAY_PATHS) {
+    const value = doc[path];
+    if (!Array.isArray(value)) continue;
+    doc[path] = value.map((item) => {
+      if (!item || typeof item !== "object" || Array.isArray(item)) return item;
+      const record = item;
+      if (typeof record.documentNodeId === "string" && record.documentNodeId.length > 0) return record;
+      const node = findBestNode(nodes, record);
+      return node ? { ...record, documentNodeId: node.id } : record;
+    });
+  }
+}
+function buildNodeFromSection(section, index) {
+  const title = stringValue2(section, "title", "name", "sectionRef") ?? `Section ${index + 1}`;
+  const id = stringValue2(section, "documentNodeId", "recordId") ?? `section:${index}:${slugPart(title)}`;
+  const pageStart = numberValue(section, "pageStart", "pageNumber");
+  const pageEnd = numberValue(section, "pageEnd", "pageNumber") ?? pageStart;
+  const type = stringValue2(section, "type");
+  const coverageType = stringValue2(section, "coverageType");
+  const sourceSpanIds = stringArray(section.sourceSpanIds);
+  const children = Array.isArray(section.subsections) ? section.subsections.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item)).map((subsection, childIndex) => {
+    const childTitle = stringValue2(subsection, "title", "name") ?? `${title} ${childIndex + 1}`;
+    const childId = stringValue2(subsection, "documentNodeId", "recordId") ?? `${id}:subsection:${childIndex}:${slugPart(childTitle)}`;
+    return {
+      id: childId,
+      title: childTitle,
+      originalTitle: childTitle,
+      type,
+      label: type,
+      level: 2,
+      sectionNumber: stringValue2(subsection, "sectionNumber"),
+      pageStart: numberValue(subsection, "pageNumber") ?? pageStart,
+      pageEnd: numberValue(subsection, "pageNumber") ?? pageStart,
+      excerpt: stringValue2(subsection, "excerpt"),
+      content: stringValue2(subsection, "content"),
+      sourceSpanIds: stringArray(subsection.sourceSpanIds),
+      sourceTextHash: stringValue2(subsection, "sourceTextHash")
+    };
+  }) : void 0;
+  return {
+    id,
+    title,
+    originalTitle: title,
+    type,
+    label: type,
+    level: 1,
+    sectionNumber: stringValue2(section, "sectionNumber"),
+    pageStart,
+    pageEnd,
+    formNumber: stringValue2(section, "formNumber"),
+    formTitle: stringValue2(section, "formTitle"),
+    excerpt: stringValue2(section, "excerpt"),
+    content: stringValue2(section, "content"),
+    interpretationLabels: [type, coverageType].filter((value) => Boolean(value)),
+    sourceSpanIds: sourceSpanIds.length > 0 ? sourceSpanIds : void 0,
+    sourceTextHash: stringValue2(section, "sourceTextHash"),
+    children: children && children.length > 0 ? children : void 0
+  };
+}
+function buildNodesFromSourceSpans(sourceSpans) {
+  const candidates = sourceSpans.filter((span) => {
+    const unit = sourceUnit3(span);
+    return unit === "section" || unit === "section_candidate" || unit === "page";
+  });
+  return candidates.sort((left, right) => (spanPage(left) ?? 0) - (spanPage(right) ?? 0) || left.id.localeCompare(right.id)).map((span, index) => {
+    const title = span.sectionId ?? span.formNumber ?? (sourceUnit3(span) === "page" && spanPage(span) ? `Page ${spanPage(span)}` : `Source unit ${index + 1}`);
+    return {
+      id: `source:${index}:${slugPart(span.id)}`,
+      title,
+      originalTitle: title,
+      type: sourceUnit3(span),
+      label: sourceUnit3(span),
+      level: 1,
+      pageStart: spanPage(span),
+      pageEnd: spanPageEnd(span),
+      formNumber: span.formNumber,
+      excerpt: span.text.slice(0, 500),
+      sourceSpanIds: [span.id],
+      sourceTextHash: span.textHash ?? span.hash
+    };
+  });
+}
+function flattenToc(nodes) {
+  const entries = [];
+  const visit = (node) => {
+    entries.push({
+      title: node.title,
+      level: node.level,
+      pageStart: node.pageStart,
+      pageEnd: node.pageEnd,
+      documentNodeId: node.id,
+      sourceSpanIds: node.sourceSpanIds
+    });
+    for (const child of node.children ?? []) visit(child);
+  };
+  for (const node of nodes) visit(node);
+  return entries;
+}
+function buildPageMap(pageAssignments, sourceSpans, document) {
+  const forms = document.formInventory ?? [];
+  return pageAssignments.sort((left, right) => left.localPageNumber - right.localPageNumber).map((assignment) => {
+    const form = forms.find((item) => {
+      const start = item.pageStart;
+      const end = item.pageEnd ?? start;
+      return start != null && end != null && assignment.localPageNumber >= start && assignment.localPageNumber <= end;
+    });
+    return {
+      page: assignment.localPageNumber,
+      label: assignment.notes,
+      formNumber: form?.formNumber,
+      formTitle: form?.title,
+      extractorNames: assignment.extractorNames,
+      sourceSpanIds: sourceSpansForPage(sourceSpans, assignment.localPageNumber)
+    };
+  });
+}
+function buildAgentGuidance(document) {
+  const guidance = [
+    {
+      kind: "source_structure",
+      title: "Use the source outline as navigation",
+      detail: "The documentOutline preserves source order and page ranges. Treat interpretation labels as hints, not as a replacement for the source document structure."
+    }
+  ];
+  if (document.declarations) {
+    guidance.push({
+      kind: "declarations",
+      title: "Declarations establish policy facts",
+      detail: "Declarations and schedules generally establish named insured, policy period, limits, deductibles, premium, and rating facts unless modified elsewhere."
+    });
+  }
+  if (document.endorsements?.length || document.formInventory?.some((form) => form.formType === "endorsement")) {
+    guidance.push({
+      kind: "endorsement_override",
+      title: "Endorsements may override base terms",
+      detail: "Endorsements and change forms can add, remove, or override base policy wording. When terms conflict, inspect the effective endorsement language and source page."
+    });
+  }
+  return guidance;
+}
+function attachDocumentStructure(params) {
+  const docRecord = params.document;
+  const sections = Array.isArray(params.document.sections) ? params.document.sections : [];
+  const existingOutline = Array.isArray(docRecord.documentOutline) ? docRecord.documentOutline : [];
+  const documentOutline = existingOutline.length > 0 ? existingOutline : sections.length > 0 ? sections.map((section, index) => buildNodeFromSection(section, index)) : buildNodesFromSourceSpans(params.sourceSpans);
+  if (documentOutline.length > 0) {
+    attachDocumentNodeIds(params.document, documentOutline);
+  }
+  const metadata = {
+    ...docRecord.documentMetadata && typeof docRecord.documentMetadata === "object" ? docRecord.documentMetadata : {},
+    ...params.document.formInventory?.length ? { formInventory: params.document.formInventory } : {},
+    ...documentOutline.length > 0 ? { tableOfContents: flattenToc(documentOutline) } : {},
+    ...params.pageAssignments.length > 0 ? { pageMap: buildPageMap(params.pageAssignments, params.sourceSpans, params.document) } : {},
+    agentGuidance: buildAgentGuidance(params.document)
+  };
+  docRecord.documentMetadata = metadata;
+  docRecord.documentOutline = documentOutline;
+  return params.document;
+}
+
 // src/prompts/coordinator/format.ts
 function buildFormatPrompt(entries) {
   const block = entries.map((e) => `===ENTRY ${e.id}===
@@ -4259,6 +4580,8 @@ function chunkDocument(doc) {
       {
         formNumber: form.formNumber,
         formType: form.formType,
+        documentNodeId: form.documentNodeId,
+        sourceSpanIds: form.sourceSpanIds?.join(","),
         documentType: doc.type
       }
     );
@@ -4285,6 +4608,7 @@ function chunkDocument(doc) {
         formNumber: end.formNumber,
         pageStart: end.pageStart,
         pageEnd: end.pageEnd,
+        documentNodeId: end.documentNodeId,
         sourceSpanIds: end.sourceSpanIds?.join(","),
         sourceTextHash: end.sourceTextHash,
         documentType: doc.type
@@ -4296,6 +4620,8 @@ function chunkDocument(doc) {
 ${exc.content}`.trim(), {
       formNumber: exc.formNumber,
       pageNumber: exc.pageNumber,
+      documentNodeId: exc.documentNodeId,
+      sourceSpanIds: exc.sourceSpanIds?.join(","),
       documentType: doc.type
     });
   });
@@ -4313,6 +4639,8 @@ ${exc.content}`.trim(), {
         conditionName: cond.name,
         conditionType: cond.conditionType,
         pageNumber: cond.pageNumber,
+        documentNodeId: cond.documentNodeId,
+        sourceSpanIds: cond.sourceSpanIds?.join(","),
         documentType: doc.type
       }
     );
@@ -4334,6 +4662,9 @@ ${exc.content}`.trim(), {
         formTitle: firstString2(definition, ["formTitle"]),
         pageNumber: typeof definition.pageNumber === "number" ? definition.pageNumber : void 0,
         sectionRef: firstString2(definition, ["sectionRef", "sectionTitle"]),
+        documentNodeId: firstString2(definition, ["documentNodeId"]),
+        sourceSpanIds: Array.isArray(definition.sourceSpanIds) ? definition.sourceSpanIds.join(",") : void 0,
+        sourceTextHash: firstString2(definition, ["sourceTextHash"]),
         documentType: doc.type
       }
     );
@@ -4362,6 +4693,9 @@ ${exc.content}`.trim(), {
         formTitle: firstString2(coveredReason, ["formTitle"]),
         pageNumber: typeof coveredReason.pageNumber === "number" ? coveredReason.pageNumber : void 0,
         sectionRef: firstString2(coveredReason, ["sectionRef", "sectionTitle"]),
+        documentNodeId: firstString2(coveredReason, ["documentNodeId"]),
+        sourceSpanIds: Array.isArray(coveredReason.sourceSpanIds) ? coveredReason.sourceSpanIds.join(",") : void 0,
+        sourceTextHash: firstString2(coveredReason, ["sourceTextHash"]),
         documentType: doc.type
       }
     );
@@ -4423,6 +4757,7 @@ ${declLines.join("\n")}`, declMeta);
         evidenceKind: "navigation",
         sectionType: sec.type,
         sectionNumber: sec.sectionNumber,
+        documentNodeId: sec.documentNodeId,
         pageStart: sec.pageStart,
         pageEnd: sec.pageEnd,
         sourceSpanIds: sec.sourceSpanIds?.join(","),
@@ -4446,6 +4781,7 @@ ${declLines.join("\n")}`, declMeta);
           sectionType: sec.type,
           parentSection: sec.title,
           sectionNumber: sub.sectionNumber,
+          documentNodeId: sub.documentNodeId,
           pageNumber: sub.pageNumber,
           sourceSpanIds: sub.sourceSpanIds?.join(","),
           sourceTextHash: sub.sourceTextHash,
@@ -4454,6 +4790,31 @@ ${declLines.join("\n")}`, declMeta);
       );
     });
   });
+  asRecordArray(extendedDoc.documentOutline).forEach((node, i) => {
+    const title = firstString2(node, ["title", "originalTitle"]) ?? `Document Node ${i + 1}`;
+    const children = asRecordArray(node.children);
+    pushChunk(
+      `section:outline:${i}`,
+      "section",
+      lines([
+        `Document Outline: ${title}`,
+        firstString2(node, ["label", "type"]) ? `Label: ${firstString2(node, ["label", "type"])}` : null,
+        typeof node.pageStart === "number" ? `Pages: ${node.pageStart}${typeof node.pageEnd === "number" ? `-${node.pageEnd}` : ""}` : null,
+        firstString2(node, ["excerpt", "content"]),
+        children.length > 0 ? `Children: ${children.map((child, childIndex) => firstString2(child, ["title", "originalTitle"]) ?? `Child ${childIndex + 1}`).join(", ")}` : null
+      ]),
+      {
+        evidenceKind: "navigation",
+        documentNodeId: firstString2(node, ["id"]),
+        sectionType: firstString2(node, ["type", "label"]),
+        pageStart: typeof node.pageStart === "number" ? node.pageStart : void 0,
+        pageEnd: typeof node.pageEnd === "number" ? node.pageEnd : void 0,
+        sourceSpanIds: Array.isArray(node.sourceSpanIds) ? node.sourceSpanIds.join(",") : void 0,
+        sourceTextHash: firstString2(node, ["sourceTextHash"]),
+        documentType: doc.type
+      }
+    );
+  });
   doc.locations?.forEach((loc, i) => {
     chunks.push({
       id: `${docId}:location:${i}`,
@@ -7277,13 +7638,13 @@ async function resolveReferentialCoverages(params) {
 function textValue(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
-function numberValue(value) {
+function numberValue2(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
 function normalize(value) {
   return value.toLowerCase().replace(/&/g, "and").replace(/[^a-z0-9]+/g, " ").trim();
 }
-function sourceUnit3(span) {
+function sourceUnit4(span) {
   return span.sourceUnit ?? span.metadata?.sourceUnit;
 }
 function pageNumber(span) {
@@ -7353,7 +7714,7 @@ function firstField(fields, patterns) {
 }
 function coverageFromRow(span) {
   const rowText = span.text.trim();
-  if (!rowText || sourceUnit3(span) !== "table_row") return void 0;
+  if (!rowText || sourceUnit4(span) !== "table_row") return void 0;
   if (span.table?.isHeader || span.metadata?.isHeader === "true") return void 0;
   const fields = splitRowFields(rowText);
   let name;
@@ -7415,7 +7776,7 @@ function coverageKey(coverage) {
     textValue(coverage.name) ?? "",
     textValue(coverage.limit) ?? "",
     textValue(coverage.limitType) ?? "",
-    numberValue(coverage.pageNumber) ?? ""
+    numberValue2(coverage.pageNumber) ?? ""
   ].map((part) => normalize(String(part))).join("|");
 }
 function rowMatchesExisting(row, existing) {
@@ -7433,7 +7794,7 @@ function recoverCoverageScheduleRows(params) {
   const payload = params.memory.get("coverage_limits");
   const existing = Array.isArray(payload?.coverages) ? payload.coverages : [];
   const pages = coveragePages(params.pageAssignments);
-  const candidates = params.sourceSpans.filter((span) => sourceUnit3(span) === "table_row").filter((span) => {
+  const candidates = params.sourceSpans.filter((span) => sourceUnit4(span) === "table_row").filter((span) => {
     const page = pageNumber(span);
     return page !== void 0 && pages.has(page);
   }).map(coverageFromRow).filter((coverage) => Boolean(coverage));
@@ -8108,7 +8469,10 @@ var ARRAY_PATHS = [
   { memoryKey: "sections", arrayKeys: ["sections"] },
   { memoryKey: "definitions", arrayKeys: ["definitions"] },
   { memoryKey: "covered_reasons", arrayKeys: ["coveredReasons", "covered_reasons"] },
-  { memoryKey: "declarations", arrayKeys: ["fields"] }
+  { memoryKey: "declarations", arrayKeys: ["fields"] },
+  { memoryKey: "premium_breakdown", arrayKeys: ["premiumBreakdown", "taxesAndFees"] },
+  { memoryKey: "supplementary", arrayKeys: ["auxiliaryFacts", "supplementaryFacts"] },
+  { memoryKey: "form_inventory", arrayKeys: ["forms"] }
 ];
 function normalize2(value) {
   return value.replace(/\s+/g, " ").trim().toLowerCase();
@@ -8120,7 +8484,7 @@ function textValue2(record, ...keys) {
   }
   return void 0;
 }
-function numberValue2(record, ...keys) {
+function numberValue3(record, ...keys) {
   for (const key of keys) {
     const value = record[key];
     if (typeof value === "number" && Number.isFinite(value)) return value;
@@ -8153,11 +8517,11 @@ function textMatches(record, span) {
 function sourceHashFor(spans) {
   return spans.map((span) => span.textHash ?? span.hash).filter(Boolean).join(":") || void 0;
 }
-function sourceUnit4(span) {
+function sourceUnit5(span) {
   return span.sourceUnit ?? span.metadata?.sourceUnit;
 }
 function hierarchyScore(span) {
-  switch (sourceUnit4(span)) {
+  switch (sourceUnit5(span)) {
     case "table_row":
       return 5;
     case "table":
@@ -8180,8 +8544,8 @@ function preferParentRows(matches, sourceSpans) {
   const expanded = [];
   const seen = /* @__PURE__ */ new Set();
   for (const match of matches) {
-    const parent = sourceUnit4(match) === "table_cell" ? byId.get(parentRowId(match) ?? "") : void 0;
-    const preferred = parent && sourceUnit4(parent) === "table_row" ? parent : match;
+    const parent = sourceUnit5(match) === "table_cell" ? byId.get(parentRowId(match) ?? "") : void 0;
+    const preferred = parent && sourceUnit5(parent) === "table_row" ? parent : match;
     if (seen.has(preferred.id)) continue;
     seen.add(preferred.id);
     expanded.push(preferred);
@@ -8190,8 +8554,8 @@ function preferParentRows(matches, sourceSpans) {
 }
 function findSourceSpansForRecord(record, sourceSpans) {
   if (sourceSpans.length === 0) return [];
-  const pageStart = numberValue2(record, "pageNumber", "pageStart");
-  const pageEnd = numberValue2(record, "pageNumber", "pageEnd");
+  const pageStart = numberValue3(record, "pageNumber", "pageStart");
+  const pageEnd = numberValue3(record, "pageNumber", "pageEnd");
   const scored = sourceSpans.map((span) => {
     let score = 0;
     if (pageOverlaps(pageStart, pageEnd, span)) score += 4;
@@ -9134,6 +9498,7 @@ ${pageText}`;
     }));
     onProgress?.("Assembling document...");
     const document = assembleDocument(id, documentType, memory);
+    attachDocumentStructure({ document, pageAssignments, sourceSpans });
     await pipelineCtx.save("assemble", {
       id,
       pageCount,
@@ -12932,6 +13297,11 @@ var AGENT_TOOLS = [
   DeductibleTypeSchema,
   DefenseCostTreatmentSchema,
   DefinitionSchema,
+  DocumentAgentGuidanceSchema,
+  DocumentMetadataSchema,
+  DocumentNodeSchema,
+  DocumentPageMapEntrySchema,
+  DocumentTableOfContentsEntrySchema,
   DocumentTypeSchema,
   DriverRecordSchema,
   DwellingDetailsSchema,