@claritylabs/cl-sdk 1.3.7 → 2.0.1

package/dist/index.mjs

@@ -567,14 +567,20 @@ var FormReferenceSchema = z3.object({
   title: z3.string().optional(),
   formType: z3.enum(["coverage", "endorsement", "declarations", "application", "notice", "other"]),
   pageStart: z3.number().optional(),
-  pageEnd: z3.number().optional()
+  pageEnd: z3.number().optional(),
+  documentNodeId: z3.string().optional(),
+  sourceSpanIds: z3.array(z3.string()).optional(),
+  sourceTextHash: z3.string().optional()
 });
 var TaxFeeItemSchema = z3.object({
   name: z3.string(),
   amount: z3.string(),
   amountValue: z3.number().optional(),
   type: z3.enum(["tax", "fee", "surcharge", "assessment"]).optional(),
-  description: z3.string().optional()
+  description: z3.string().optional(),
+  documentNodeId: z3.string().optional(),
+  sourceSpanIds: z3.array(z3.string()).optional(),
+  sourceTextHash: z3.string().optional()
 });
 var RatingBasisSchema = z3.object({
   type: RatingBasisTypeSchema,
@@ -623,11 +629,14 @@ var CoverageSchema = z4.object({
   deductible: z4.string().optional(),
   deductibleAmount: z4.number().optional(),
   deductibleValueType: CoverageValueTypeSchema.optional(),
+  trigger: CoverageTriggerSchema.optional(),
+  retroactiveDate: z4.string().optional(),
   formNumber: z4.string().optional(),
   pageNumber: z4.number().optional(),
   sectionRef: z4.string().optional(),
   originalContent: z4.string().optional(),
   recordId: z4.string().optional(),
+  documentNodeId: z4.string().optional(),
   sourceSpanIds: z4.array(z4.string()).optional(),
   sourceTextHash: z4.string().optional()
 });
@@ -657,6 +666,7 @@ var EnrichedCoverageSchema = z4.object({
   sectionRef: z4.string().optional(),
   originalContent: z4.string().optional(),
   recordId: z4.string().optional(),
+  documentNodeId: z4.string().optional(),
   sourceSpanIds: z4.array(z4.string()).optional(),
   sourceTextHash: z4.string().optional()
 });
@@ -685,6 +695,7 @@ var EndorsementSchema = z5.object({
   pageStart: z5.number(),
   pageEnd: z5.number().optional(),
   recordId: z5.string().optional(),
+  documentNodeId: z5.string().optional(),
   sourceSpanIds: z5.array(z5.string()).optional(),
   sourceTextHash: z5.string().optional()
 });
@@ -703,6 +714,7 @@ var ExclusionSchema = z6.object({
   content: z6.string(),
   pageNumber: z6.number().optional(),
   recordId: z6.string().optional(),
+  documentNodeId: z6.string().optional(),
   sourceSpanIds: z6.array(z6.string()).optional(),
   sourceTextHash: z6.string().optional()
 });
@@ -720,6 +732,7 @@ var PolicyConditionSchema = z7.object({
   keyValues: z7.array(ConditionKeyValueSchema).optional(),
   pageNumber: z7.number().optional(),
   recordId: z7.string().optional(),
+  documentNodeId: z7.string().optional(),
   sourceSpanIds: z7.array(z7.string()).optional(),
   sourceTextHash: z7.string().optional()
 });
@@ -1296,6 +1309,7 @@ var SubsectionSchema = z16.object({
   pageNumber: z16.number().optional(),
   excerpt: z16.string().optional(),
   content: z16.string().optional(),
+  documentNodeId: z16.string().optional(),
   sourceSpanIds: z16.array(z16.string()).optional(),
   sourceTextHash: z16.string().optional()
 });
@@ -1310,6 +1324,7 @@ var SectionSchema = z16.object({
   content: z16.string().optional(),
   subsections: z16.array(SubsectionSchema).optional(),
   recordId: z16.string().optional(),
+  documentNodeId: z16.string().optional(),
   sourceSpanIds: z16.array(z16.string()).optional(),
   sourceTextHash: z16.string().optional()
 });
@@ -1323,13 +1338,19 @@ var UnderwritingConditionSchema = z16.object({
 var PremiumLineSchema = z16.object({
   line: z16.string(),
   amount: z16.string(),
-  amountValue: z16.number().optional()
+  amountValue: z16.number().optional(),
+  documentNodeId: z16.string().optional(),
+  sourceSpanIds: z16.array(z16.string()).optional(),
+  sourceTextHash: z16.string().optional()
 });
 var AuxiliaryFactSchema = z16.object({
   key: z16.string(),
   value: z16.string(),
   subject: z16.string().optional(),
-  context: z16.string().optional()
+  context: z16.string().optional(),
+  documentNodeId: z16.string().optional(),
+  sourceSpanIds: z16.array(z16.string()).optional(),
+  sourceTextHash: z16.string().optional()
 });
 var DefinitionSchema = z16.object({
   term: z16.string(),
@@ -1340,6 +1361,7 @@ var DefinitionSchema = z16.object({
   sectionRef: z16.string().optional(),
   originalContent: z16.string().optional(),
   recordId: z16.string().optional(),
+  documentNodeId: z16.string().optional(),
   sourceSpanIds: z16.array(z16.string()).optional(),
   sourceTextHash: z16.string().optional()
 });
@@ -1357,9 +1379,60 @@ var CoveredReasonSchema = z16.object({
   sectionRef: z16.string().optional(),
   originalContent: z16.string().optional(),
   recordId: z16.string().optional(),
+  documentNodeId: z16.string().optional(),
   sourceSpanIds: z16.array(z16.string()).optional(),
   sourceTextHash: z16.string().optional()
 });
+var DocumentTableOfContentsEntrySchema = z16.object({
+  title: z16.string(),
+  level: z16.number().int().positive().optional(),
+  pageStart: z16.number().optional(),
+  pageEnd: z16.number().optional(),
+  documentNodeId: z16.string().optional(),
+  sourceSpanIds: z16.array(z16.string()).optional()
+});
+var DocumentPageMapEntrySchema = z16.object({
+  page: z16.number().int().positive(),
+  label: z16.string().optional(),
+  formNumber: z16.string().optional(),
+  formTitle: z16.string().optional(),
+  sectionTitle: z16.string().optional(),
+  extractorNames: z16.array(z16.string()).optional(),
+  sourceSpanIds: z16.array(z16.string()).optional()
+});
+var DocumentAgentGuidanceSchema = z16.object({
+  kind: z16.string(),
+  title: z16.string(),
+  detail: z16.string(),
+  sourceSpanIds: z16.array(z16.string()).optional()
+});
+var DocumentMetadataSchema = z16.object({
+  formInventory: z16.array(FormReferenceSchema).optional(),
+  tableOfContents: z16.array(DocumentTableOfContentsEntrySchema).optional(),
+  pageMap: z16.array(DocumentPageMapEntrySchema).optional(),
+  agentGuidance: z16.array(DocumentAgentGuidanceSchema).optional()
+});
+var DocumentNodeSchema = z16.lazy(
+  () => z16.object({
+    id: z16.string(),
+    title: z16.string(),
+    originalTitle: z16.string().optional(),
+    type: z16.string().optional(),
+    label: z16.string().optional(),
+    level: z16.number().int().positive().optional(),
+    sectionNumber: z16.string().optional(),
+    pageStart: z16.number().optional(),
+    pageEnd: z16.number().optional(),
+    formNumber: z16.string().optional(),
+    formTitle: z16.string().optional(),
+    excerpt: z16.string().optional(),
+    content: z16.string().optional(),
+    interpretationLabels: z16.array(z16.string()).optional(),
+    sourceSpanIds: z16.array(z16.string()).optional(),
+    sourceTextHash: z16.string().optional(),
+    children: z16.array(DocumentNodeSchema).optional()
+  })
+);
 var BaseDocumentFields = {
   id: z16.string(),
   carrier: z16.string(),
@@ -1370,6 +1443,8 @@ var BaseDocumentFields = {
   summary: z16.string().optional(),
   policyTypes: z16.array(z16.string()).optional(),
   coverages: z16.array(CoverageSchema),
+  documentMetadata: DocumentMetadataSchema,
+  documentOutline: z16.array(DocumentNodeSchema),
   sections: z16.array(SectionSchema).optional(),
   definitions: z16.array(DefinitionSchema).optional(),
   coveredReasons: z16.array(CoveredReasonSchema).optional(),
@@ -1851,6 +1926,15 @@ var SourceSpanKindSchema = z20.enum([
   "plain_text",
   "structured_field"
 ]);
+var SourceSpanUnitSchema = z20.enum([
+  "page",
+  "section",
+  "table",
+  "table_row",
+  "table_cell",
+  "key_value",
+  "text"
+]);
 var SourceKindSchema = z20.enum([
   "policy_pdf",
   "application_pdf",
@@ -1875,6 +1959,15 @@ var SourceSpanLocationSchema = z20.object({
   lineEnd: z20.number().int().positive().optional(),
   fieldPath: z20.string().optional()
 });
+var SourceSpanTableLocationSchema = z20.object({
+  tableId: z20.string().optional(),
+  rowIndex: z20.number().int().nonnegative().optional(),
+  columnIndex: z20.number().int().nonnegative().optional(),
+  columnName: z20.string().optional(),
+  rowSpanId: z20.string().optional(),
+  tableSpanId: z20.string().optional(),
+  isHeader: z20.boolean().optional()
+});
 var SourceSpanSchema = z20.object({
   id: z20.string().min(1),
   documentId: z20.string().min(1),
@@ -1888,6 +1981,9 @@ var SourceSpanSchema = z20.object({
   pageEnd: z20.number().int().positive().optional(),
   sectionId: z20.string().optional(),
   formNumber: z20.string().optional(),
+  sourceUnit: SourceSpanUnitSchema.optional(),
+  parentSpanId: z20.string().optional(),
+  table: SourceSpanTableLocationSchema.optional(),
   bbox: z20.array(SourceSpanBBoxSchema).optional(),
   location: SourceSpanLocationSchema.optional(),
   metadata: z20.record(z20.string(), z20.string()).optional()
@@ -2006,6 +2102,9 @@ function buildSourceSpan(input, localIndex = 0) {
     pageEnd: input.pageEnd,
     sectionId: input.sectionId,
     formNumber: input.formNumber,
+    sourceUnit: input.sourceUnit,
+    parentSpanId: input.parentSpanId,
+    table: input.table,
     location: {
       page: input.pageStart === input.pageEnd ? input.pageStart : void 0,
       startPage: input.pageStart,
@@ -2026,7 +2125,11 @@ function buildPageSourceSpans(pages) {
         pageEnd: page.pageNumber,
         sectionId: page.sectionId,
         formNumber: page.formNumber,
-        metadata: page.metadata
+        sourceUnit: "page",
+        metadata: {
+          ...page.metadata ?? {},
+          sourceUnit: page.metadata?.sourceUnit ?? "page"
+        }
       },
       index
     )
@@ -2048,6 +2151,7 @@ function buildSectionSourceSpans(pages, options = {}) {
           pageEnd: page.pageNumber,
           sectionId: section.title,
           formNumber: inferFormNumber(section.text),
+          sourceUnit: "section",
           metadata: {
             ...page.metadata ?? {},
             sourceUnit: "section_candidate"
@@ -2080,6 +2184,7 @@ function chunkSourceSpans(spans, options = {}) {
   const chunks = [];
   let current = [];
   let currentLength = 0;
+  const spansForChunking = filterChunkableSourceSpans(spans);
   const flush = () => {
     if (current.length === 0) return;
     const text = current.map((span) => span.text).join("\n\n");
@@ -2103,7 +2208,7 @@ function chunkSourceSpans(spans, options = {}) {
     current = [];
     currentLength = 0;
   };
-  for (const span of spans) {
+  for (const span of spansForChunking) {
     const nextLength = currentLength + span.text.length + (current.length > 0 ? 2 : 0);
     if (current.length > 0 && nextLength > maxChars) {
       flush();
@@ -2114,6 +2219,20 @@ function chunkSourceSpans(spans, options = {}) {
   flush();
   return chunks;
 }
+function sourceUnit(span) {
+  return span.sourceUnit ?? span.metadata?.sourceUnit;
+}
+function filterChunkableSourceSpans(spans) {
+  const rowIds = new Set(
+    spans.filter((span) => sourceUnit(span) === "table_row").map((span) => span.id)
+  );
+  if (rowIds.size === 0) return spans;
+  return spans.filter((span) => {
+    if (sourceUnit(span) !== "table_cell") return true;
+    const rowId = span.parentSpanId ?? span.table?.rowSpanId ?? span.metadata?.rowSpanId;
+    return !rowId || !rowIds.has(rowId);
+  });
+}
 function splitPageIntoSections(text, headingPattern, minSectionChars) {
   const lines = text.split(/\r?\n/);
   const sections = [];
@@ -2506,36 +2625,18 @@ function normalizeDoclingDocument(document, options) {
     pageTexts.set(page, appendText(pageTexts.get(page), unit.text));
   }
   const fullText = Array.from({ length: pageCount }, (_, index) => {
-    const pageNumber = index + 1;
-    const text = pageTexts.get(pageNumber)?.trim();
-    return text ? `Page ${pageNumber}
+    const pageNumber2 = index + 1;
+    const text = pageTexts.get(pageNumber2)?.trim();
+    return text ? `Page ${pageNumber2}
 ${text}` : "";
   }).filter(Boolean).join("\n\n");
   const sourceKind = options.sourceKind ?? "policy_pdf";
-  const sourceSpans = units.map((unit, index) => {
-    const span = buildSourceSpan(
-      {
-        documentId: options.documentId,
-        sourceKind,
-        text: unit.text,
-        pageStart: unit.pageStart,
-        pageEnd: unit.pageEnd,
-        sectionId: unit.label,
-        metadata: {
-          sourceSystem: "docling",
-          sourceUnit: "docling_item",
-          doclingRef: unit.ref,
-          ...unit.label ? { doclingLabel: unit.label } : {}
-        }
-      },
-      index
-    );
-    return {
-      ...span,
-      kind: "plain_text",
-      bbox: unit.bboxes?.length ? unit.bboxes : void 0
-    };
-  });
+  const sourceSpans = units.flatMap(
+    (unit, index) => buildSourceSpansForUnit(unit, index, {
+      documentId: options.documentId,
+      sourceKind
+    })
+  );
   return {
     pageCount,
     fullText,
@@ -2573,6 +2674,11 @@ function mergeSourceSpans(spans) {
       span.pageStart ?? span.location?.startPage ?? span.location?.page ?? "na",
       span.pageEnd ?? span.location?.endPage ?? span.pageStart ?? "na",
       span.sectionId ?? span.location?.fieldPath ?? "na",
+      span.sourceUnit ?? span.metadata?.sourceUnit ?? "na",
+      span.parentSpanId ?? "na",
+      span.table?.tableId ?? span.metadata?.tableId ?? "na",
+      span.table?.rowIndex ?? span.metadata?.rowIndex ?? "na",
+      span.table?.columnIndex ?? span.metadata?.columnIndex ?? "na",
       span.textHash ?? sourceSpanTextHash(span.text)
     ].join(":");
     if (seen.has(key)) continue;
@@ -2635,6 +2741,7 @@ function getOrderedBodyRefs(document, itemMap) {
 function normalizeItem(ref, item) {
   const text = getItemText(item).trim();
   if (!text) return void 0;
+  const table = getItemTable(item);
   const pages = (item.prov ?? []).map((prov) => getPageNumber(prov)).filter((page) => typeof page === "number" && page > 0);
   const pageStart = pages.length ? Math.min(...pages) : void 0;
   const pageEnd = pages.length ? Math.max(...pages) : pageStart;
@@ -2645,17 +2752,143 @@ function normalizeItem(ref, item) {
     text,
     pageStart,
     pageEnd,
-    bboxes: bboxes.length ? bboxes : void 0
+    bboxes: bboxes.length ? bboxes : void 0,
+    table
   };
 }
+function buildSourceSpansForUnit(unit, index, options) {
+  const baseMetadata = {
+    sourceSystem: "docling",
+    sourceUnit: unit.table ? "table" : "docling_item",
+    doclingRef: unit.ref,
+    ...unit.label ? { doclingLabel: unit.label } : {}
+  };
+  const tableId = unit.table ? `${unit.ref}:table` : void 0;
+  const tableSpan = withDoclingKind(buildSourceSpan(
+    {
+      documentId: options.documentId,
+      sourceKind: options.sourceKind,
+      text: unit.text,
+      pageStart: unit.pageStart,
+      pageEnd: unit.pageEnd,
+      sectionId: unit.label,
+      sourceUnit: unit.table ? "table" : labelToSourceUnit(unit.label),
+      table: tableId ? { tableId } : void 0,
+      metadata: baseMetadata
+    },
+    index * 1e3
+  ), unit);
+  if (!unit.table) return [tableSpan];
+  const spans = [tableSpan];
+  const table = unit.table;
+  for (let rowIndex = 0; rowIndex < table.rows.length; rowIndex += 1) {
+    const row = table.rows[rowIndex];
+    const isHeader = rowIndex === 0 && table.headers.length > 0;
+    const rowText = tableRowText(table, rowIndex);
+    if (!rowText) continue;
+    const rowSpan = withDoclingKind(buildSourceSpan(
+      {
+        documentId: options.documentId,
+        sourceKind: options.sourceKind,
+        text: rowText,
+        pageStart: unit.pageStart,
+        pageEnd: unit.pageEnd,
+        sectionId: unit.label,
+        sourceUnit: "table_row",
+        parentSpanId: tableSpan.id,
+        table: {
+          tableId,
+          tableSpanId: tableSpan.id,
+          rowIndex,
+          isHeader
+        },
+        metadata: {
+          ...baseMetadata,
+          sourceUnit: "table_row",
+          tableId: tableId ?? "",
+          tableSpanId: tableSpan.id,
+          rowIndex: String(rowIndex),
+          isHeader: String(isHeader)
+        }
+      },
+      index * 1e3 + 1 + rowIndex
+    ), unit);
+    spans.push(rowSpan);
+    for (let columnIndex = 0; columnIndex < row.length; columnIndex += 1) {
+      const text = row[columnIndex]?.trim();
+      if (!text) continue;
+      const columnName = table.headers[columnIndex]?.trim() || void 0;
+      const cellSpan = withDoclingKind(buildSourceSpan(
+        {
+          documentId: options.documentId,
+          sourceKind: options.sourceKind,
+          text,
+          pageStart: unit.pageStart,
+          pageEnd: unit.pageEnd,
+          sectionId: unit.label,
+          sourceUnit: "table_cell",
+          parentSpanId: rowSpan.id,
+          table: {
+            tableId,
+            tableSpanId: tableSpan.id,
+            rowSpanId: rowSpan.id,
+            rowIndex,
+            columnIndex,
+            columnName,
+            isHeader
+          },
+          metadata: {
+            ...baseMetadata,
+            sourceUnit: "table_cell",
+            tableId: tableId ?? "",
+            tableSpanId: tableSpan.id,
+            rowSpanId: rowSpan.id,
+            rowIndex: String(rowIndex),
+            columnIndex: String(columnIndex),
+            ...columnName ? { columnName } : {},
+            isHeader: String(isHeader)
+          }
+        },
+        index * 1e3 + 100 + rowIndex * 100 + columnIndex
+      ), unit);
+      spans.push(cellSpan);
+    }
+  }
+  return spans;
+}
+function withDoclingKind(span, unit) {
+  return {
+    ...span,
+    kind: "plain_text",
+    bbox: unit.bboxes?.length ? unit.bboxes : void 0
+  };
+}
+function labelToSourceUnit(label) {
+  const normalized = label?.toLowerCase() ?? "";
+  if (normalized.includes("table")) return "table";
+  if (normalized.includes("key")) return "key_value";
+  if (normalized.includes("section") || normalized.includes("header")) return "section";
+  return "text";
+}
+function tableRowText(table, rowIndex) {
+  const row = table.rows[rowIndex] ?? [];
+  const headers = table.headers;
+  if (rowIndex === 0 && headers.length > 0) return row.filter(Boolean).join(" | ");
+  return row.map((value, columnIndex) => {
+    const trimmed = value.trim();
+    if (!trimmed) return "";
+    const header = headers[columnIndex]?.trim();
+    return header ? `${header}: ${trimmed}` : trimmed;
+  }).filter(Boolean).join(" | ");
+}
 function getItemText(item) {
   if (typeof item.text === "string" && item.text.trim()) return item.text;
   if (typeof item.orig === "string" && item.orig.trim()) return item.orig;
-  const table = tableToMarkdown(item.data);
-  if (table) return table;
+  const table = parseTableData(item.data);
+  if (table) return table.markdown;
   return "";
 }
-function tableToMarkdown(data) {
+function parseTableData(data) {
   const record = asRecord(data);
   const cells = Array.isArray(record?.table_cells) ? record.table_cells : Array.isArray(record?.tableCells) ? record.tableCells : void 0;
   if (!cells) return void 0;
@@ -2671,10 +2904,20 @@ function tableToMarkdown(data) {
   for (const cell of parsedCells) {
     rows[cell.row][cell.col] = cell.text;
   }
-  if (rows.length === 1) return rows[0].filter(Boolean).join(" | ");
+  if (rows.length === 1) {
+    const markdown2 = rows[0].filter(Boolean).join(" | ");
+    return { markdown: markdown2, headers: [], rows, cells: parsedCells };
+  }
   const header = rows[0];
   const separator = header.map(() => "---");
-  return [header, separator, ...rows.slice(1)].map((row) => `| ${row.map((value) => value.trim()).join(" | ")} |`).join("\n");
+  const markdown = [header, separator, ...rows.slice(1)].map((row) => `| ${row.map((value) => value.trim()).join(" | ")} |`).join("\n");
+  return { markdown, headers: header, rows, cells: parsedCells };
+}
+function getItemTable(item) {
+  if (typeof item.text === "string" && item.text.trim() || typeof item.orig === "string" && item.orig.trim()) {
+    return void 0;
+  }
+  return parseTableData(item.data);
 }
 function inferPageCount(document, units) {
   const pages = document.pages;
@@ -2751,8 +2994,18 @@ function buildSourceContext(spans, maxChars = 12e3) {
   if (spans.length === 0) return "";
   const lines = [];
   let length = 0;
-  for (const span of spans) {
-    const header = `[sourceSpan:${span.id}${span.pageStart ? ` page:${span.pageStart}${span.pageEnd && span.pageEnd !== span.pageStart ? `-${span.pageEnd}` : ""}` : ""}${span.sectionId ? ` section:${span.sectionId}` : ""}${span.formNumber ? ` form:${span.formNumber}` : ""}]`;
+  for (const span of orderSourceSpansForContext(spans)) {
+    const unit = sourceUnit2(span);
+    const table = span.table;
+    const tableContext = [
+      unit ? ` unit:${unit}` : "",
+      table?.tableId ? ` table:${table.tableId}` : "",
+      table?.rowIndex != null ? ` row:${table.rowIndex}` : "",
+      table?.columnIndex != null ? ` col:${table.columnIndex}` : "",
+      table?.columnName ? ` column:${table.columnName}` : "",
+      span.parentSpanId ? ` parent:${span.parentSpanId}` : ""
+    ].join("");
+    const header = `[sourceSpan:${span.id}${span.pageStart ? ` page:${span.pageStart}${span.pageEnd && span.pageEnd !== span.pageStart ? `-${span.pageEnd}` : ""}` : ""}${span.sectionId ? ` section:${span.sectionId}` : ""}${span.formNumber ? ` form:${span.formNumber}` : ""}${tableContext}]`;
     const text = `${header}
 ${span.text}`;
     if (length + text.length > maxChars && lines.length > 0) break;
@@ -2766,6 +3019,49 @@ ${lines.join("\n\n")}
 
 Use sourceSpan IDs when grounding extracted contractual values.`;
 }
+function sourceUnit2(span) {
+  return span.sourceUnit ?? span.metadata?.sourceUnit;
+}
+function sourceContextRank(span) {
+  switch (sourceUnit2(span)) {
+    case "table_row":
+      return 0;
+    case "table":
+      return 1;
+    case "section":
+      return 2;
+    case "page":
+      return 3;
+    case "key_value":
+      return 4;
+    case "table_cell":
+      return 8;
+    default:
+      return 5;
+  }
+}
+function orderSourceSpansForContext(spans) {
+  const parentRows = new Set(
+    spans.filter((span) => sourceUnit2(span) === "table_row").map((span) => span.id)
+  );
+  const filtered = spans.filter((span) => {
+    if (sourceUnit2(span) !== "table_cell") return true;
+    const parent = span.parentSpanId ?? span.table?.rowSpanId ?? span.metadata?.rowSpanId;
+    return !parent || !parentRows.has(parent);
+  });
+  return [...filtered].sort((left, right) => {
+    const leftPage = left.pageStart ?? left.location?.startPage ?? left.location?.page ?? 0;
+    const rightPage = right.pageStart ?? right.location?.startPage ?? right.location?.page ?? 0;
+    if (leftPage !== rightPage) return leftPage - rightPage;
+    const leftRank = sourceContextRank(left);
+    const rightRank = sourceContextRank(right);
+    if (leftRank !== rightRank) return leftRank - rightRank;
+    const leftRow = left.table?.rowIndex ?? Number(left.metadata?.rowIndex ?? Number.NaN);
+    const rightRow = right.table?.rowIndex ?? Number(right.metadata?.rowIndex ?? Number.NaN);
+    if (Number.isFinite(leftRow) && Number.isFinite(rightRow) && leftRow !== rightRow) return leftRow - rightRow;
+    return left.id.localeCompare(right.id);
+  });
+}
 async function runExtractor(params) {
   const {
     name,
@@ -3056,6 +3352,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 ?? {}),
@@ -3107,6 +3405,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}===
@@ -3706,6 +4245,8 @@ function chunkDocument(doc) {
       {
         formNumber: form.formNumber,
         formType: form.formType,
+        documentNodeId: form.documentNodeId,
+        sourceSpanIds: form.sourceSpanIds?.join(","),
         documentType: doc.type
       }
     );
@@ -3732,6 +4273,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
@@ -3743,6 +4285,8 @@ function chunkDocument(doc) {
 ${exc.content}`.trim(), {
       formNumber: exc.formNumber,
       pageNumber: exc.pageNumber,
+      documentNodeId: exc.documentNodeId,
+      sourceSpanIds: exc.sourceSpanIds?.join(","),
       documentType: doc.type
     });
   });
@@ -3760,6 +4304,8 @@ ${exc.content}`.trim(), {
         conditionName: cond.name,
         conditionType: cond.conditionType,
         pageNumber: cond.pageNumber,
+        documentNodeId: cond.documentNodeId,
+        sourceSpanIds: cond.sourceSpanIds?.join(","),
         documentType: doc.type
       }
     );
@@ -3781,6 +4327,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
       }
     );
@@ -3809,6 +4358,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
       }
     );
@@ -3870,6 +4422,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(","),
@@ -3893,6 +4446,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,
@@ -3901,6 +4455,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}`,
@@ -4364,7 +4943,7 @@ function mergeCoverageLimits(existing, incoming) {
   const merged = mergeShallowPreferPresent(existing, incoming);
   const existingCoverages = Array.isArray(existing.coverages) ? existing.coverages : [];
   const incomingCoverages = Array.isArray(incoming.coverages) ? incoming.coverages : [];
-  const coverageKey = (coverage) => keyFromParts(
+  const coverageKey2 = (coverage) => keyFromParts(
     coverage.name,
     coverage.limitType,
     coverage.limit,
@@ -4373,7 +4952,7 @@ function mergeCoverageLimits(existing, incoming) {
   );
   const byKey = /* @__PURE__ */ new Map();
   for (const coverage of [...existingCoverages, ...incomingCoverages]) {
-    const key = coverageKey(coverage);
+    const key = coverageKey2(coverage);
     const current = byKey.get(key);
     byKey.set(key, current ? mergeShallowPreferPresent(current, coverage) : coverage);
   }
@@ -6720,6 +7299,190 @@ async function resolveReferentialCoverages(params) {
   };
 }
 
+// src/extraction/coverage-schedule-recovery.ts
+function textValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+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 sourceUnit4(span) {
+  return span.sourceUnit ?? span.metadata?.sourceUnit;
+}
+function pageNumber(span) {
+  return span.pageStart ?? span.location?.page ?? span.location?.startPage;
+}
+function coveragePages(pageAssignments) {
+  const pages = /* @__PURE__ */ new Set();
+  for (const assignment of pageAssignments) {
+    if (assignment.extractorNames.includes("coverage_limits") || assignment.hasScheduleValues) {
+      pages.add(assignment.localPageNumber);
+    }
+  }
+  return pages;
+}
+function parseCurrencyAmount(value) {
+  const match = value.match(/(?:CAD|USD|US)?\s*\$?\s*([0-9][0-9,]*(?:\.\d+)?)/i);
+  if (!match) return void 0;
+  const amount = Number(match[1].replace(/,/g, ""));
+  return Number.isFinite(amount) ? amount : void 0;
+}
+function limitTypeFrom(value) {
+  const normalized = normalize(value);
+  if (normalized.includes("/") || normalized.includes("each claim") && normalized.includes("aggregate")) return "scheduled";
+  if (normalized.includes("each claim") || normalized.includes("per claim")) return "per_claim";
+  if (normalized.includes("each occurrence") || normalized.includes("per occurrence")) return "per_occurrence";
+  if (normalized.includes("aggregate")) return "aggregate";
+  if (normalized.includes("shared within") || normalized.includes("within coverage")) return "scheduled";
+  if (normalized.includes("/")) return "scheduled";
+  return void 0;
+}
+function limitValueTypeFrom(value) {
+  const normalized = normalize(value);
+  if (parseCurrencyAmount(value) !== void 0) return "numeric";
+  if (normalized.includes("shared within") || normalized.includes("within coverage") || normalized.includes("shown above")) {
+    return "referential";
+  }
+  if (normalized.includes("included")) return "included";
+  if (normalized.includes("not included") || normalized === "nil" || normalized === "none") return "not_included";
+  if (normalized.includes("as stated")) return "as_stated";
+  return "other";
+}
+function cleanName(value) {
+  return value.replace(/\s*\([^)]*part of and not in addition to[^)]*\)\s*/gi, " ").replace(/\s+/g, " ").trim().replace(/[.:;-]+$/, "").trim();
+}
+function isDeductibleOnly(name, rowText) {
+  const normalizedName = normalize(name);
+  const normalizedRow = normalize(rowText);
+  if (!/\b(deductible|retention|sir)\b/.test(`${normalizedName} ${normalizedRow}`)) return false;
+  if (/\b(coverage|sub limit|sublimit|limit)\b/.test(normalizedName) && !/\b(enhanced|standard)\s+deductible\b/.test(normalizedName)) {
+    return false;
+  }
+  return /\b(enhanced|standard)?\s*(deductible|retention|sir)\b/.test(normalizedName) || /^\s*(deductible|retention|sir)\b/.test(normalizedRow);
+}
+function splitRowFields(rowText) {
+  return rowText.split(/\s+\|\s+/).map((part) => part.trim()).filter(Boolean).map((part) => {
+    const match = part.match(/^([^:]{1,100}):\s*(.*)$/);
+    if (!match) return { value: part };
+    return { key: match[1].trim(), value: match[2].trim() };
+  });
+}
+function firstField(fields, patterns) {
+  for (const field of fields) {
+    const target = `${field.key ?? ""} ${field.value}`;
+    if (patterns.some((pattern) => pattern.test(target))) return field.value || field.key;
+  }
+  return void 0;
+}
+function coverageFromRow(span) {
+  const rowText = span.text.trim();
+  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;
+  let limit;
+  for (const field of fields) {
+    const key = field.key?.trim();
+    const value = field.value.trim();
+    if (!key || !value) continue;
+    if (!name && /^coverage$/i.test(key)) name = cleanName(value);
+    if (!limit && /\blimit\b/i.test(key)) limit = value;
+    if (!name && /\b(sub[-\s]?limit|aggregate|each claim)\b/i.test(key) && parseCurrencyAmount(value) !== void 0) {
+      name = cleanName(key);
+      limit = limit ?? value;
+    }
+  }
+  if (!name || !limit) {
+    for (const field of fields) {
+      const key = field.key?.trim();
+      const value = field.value.trim();
+      if (!key || !value) continue;
+      if (!name && /\b(sub[-\s]?limit|coverage|aggregate|each claim)\b/i.test(key) && !parseCurrencyAmount(key)) {
+        name = cleanName(key);
+        limit = limit ?? value;
+      }
+    }
+  }
+  if (!name || !limit) return void 0;
+  if (isDeductibleOnly(name, rowText)) return void 0;
+  const normalizedLimit = normalize(limit);
+  const hasUsableLimit = parseCurrencyAmount(limit) !== void 0 || /\b(shared within|within coverage|as stated|included|not included)\b/i.test(normalizedLimit);
+  if (!hasUsableLimit) return void 0;
+  const deductible = firstField(fields, [/\bdeductible\b/i, /\bretention\b/i, /\bsir\b/i]);
+  const basis = firstField(fields, [/\bbasis\b/i]);
+  const retroactiveDate = firstField(fields, [/\bretroactive date\b/i, /\bretro date\b/i]);
+  const page = pageNumber(span);
+  const limitAmount = parseCurrencyAmount(limit);
+  const deductibleAmount = deductible ? parseCurrencyAmount(deductible) : void 0;
+  return {
+    name,
+    limit,
+    ...limitAmount !== void 0 ? { limitAmount } : {},
+    ...limitTypeFrom(`${name} ${limit}`) ? { limitType: limitTypeFrom(`${name} ${limit}`) } : {},
+    limitValueType: limitValueTypeFrom(limit),
+    ...deductible && !/^nil|none$/i.test(deductible.trim()) ? { deductible } : {},
+    ...deductibleAmount !== void 0 ? { deductibleAmount } : {},
+    ...deductible ? { deductibleValueType: limitValueTypeFrom(deductible) } : {},
+    ...basis && /claims[- ]made/i.test(basis) ? { trigger: "claims_made" } : {},
+    ...retroactiveDate ? { retroactiveDate } : {},
+    ...span.formNumber ? { formNumber: span.formNumber } : {},
+    ...page ? { pageNumber: page } : {},
+    sectionRef: span.sectionId ?? "SCHEDULE",
+    originalContent: rowText,
+    sourceSpanIds: [span.id],
+    sourceTextHash: span.textHash ?? span.hash
+  };
+}
+function coverageKey(coverage) {
+  return [
+    textValue(coverage.name) ?? "",
+    textValue(coverage.limit) ?? "",
+    textValue(coverage.limitType) ?? "",
+    numberValue2(coverage.pageNumber) ?? ""
+  ].map((part) => normalize(String(part))).join("|");
+}
+function rowMatchesExisting(row, existing) {
+  const rowKey = coverageKey(row);
+  const rowName = normalize(textValue(row.name) ?? "");
+  const rowLimit = normalize(textValue(row.limit) ?? "");
+  return existing.some((coverage) => {
+    if (coverageKey(coverage) === rowKey) return true;
+    const name = normalize(textValue(coverage.name) ?? "");
+    const limit = normalize(textValue(coverage.limit) ?? "");
+    return Boolean(rowName && rowLimit && name === rowName && limit === rowLimit);
+  });
+}
+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) => sourceUnit4(span) === "table_row").filter((span) => {
+    const page = pageNumber(span);
+    return page !== void 0 && pages.has(page);
+  }).map(coverageFromRow).filter((coverage) => Boolean(coverage));
+  const recovered = [];
+  for (const coverage of candidates) {
+    if (rowMatchesExisting(coverage, [...existing, ...recovered])) continue;
+    recovered.push(coverage);
+  }
+  if (recovered.length > 0) {
+    params.memory.set("coverage_limits", {
+      ...payload ?? {},
+      coverages: [...existing, ...recovered]
+    });
+  }
+  return {
+    recovered,
+    missingSourceRows: recovered.map((coverage) => {
+      const id = Array.isArray(coverage.sourceSpanIds) ? coverage.sourceSpanIds[0] : void 0;
+      return params.sourceSpans.find((span) => span.id === id);
+    }).filter((span) => Boolean(span))
+  };
+}
+
 // src/extraction/focused-dispatch.ts
 async function runFocusedExtractorWithFallback(params) {
   const {
@@ -6922,6 +7685,29 @@ function buildExtractionReviewReport(params) {
     addMissingSourceGroundingIssues(deterministicIssues, "definitions", "definitions", definitions, "term");
     addMissingSourceGroundingIssues(deterministicIssues, "covered_reasons", "coveredReasons", coveredReasons, "name");
   }
+  if (params.sourceSpans?.length) {
+    const tempCoveragePayload = {
+      ...memory.get("coverage_limits") ?? {},
+      coverages: coverages.map((coverage) => ({ ...coverage }))
+    };
+    const tempMemory = new Map(memory);
+    tempMemory.set("coverage_limits", tempCoveragePayload);
+    const scheduleRecovery = recoverCoverageScheduleRows({
+      memory: tempMemory,
+      sourceSpans: params.sourceSpans,
+      pageAssignments: params.pageAssignments
+    });
+    for (const recovered of scheduleRecovery.recovered) {
+      deterministicIssues.push({
+        code: "coverage_schedule_row_missing",
+        severity: "blocking",
+        message: `Coverage schedule row "${String(recovered.name ?? "unknown")}" is present in source table evidence but missing from extracted coverages.`,
+        extractorName: "coverage_limits",
+        pageNumber: typeof recovered.pageNumber === "number" ? recovered.pageNumber : void 0,
+        itemName: typeof recovered.name === "string" ? recovered.name : void 0
+      });
+    }
+  }
   if (mappedDefinitions && definitions.length === 0) {
     deterministicIssues.push({
       code: "definitions_mapped_but_empty",
@@ -7348,19 +8134,22 @@ 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 normalize(value) {
+function normalize2(value) {
   return value.replace(/\s+/g, " ").trim().toLowerCase();
 }
-function textValue(record, ...keys) {
+function textValue2(record, ...keys) {
   for (const key of keys) {
     const value = record[key];
     if (typeof value === "string" && value.trim()) return value.trim();
   }
   return void 0;
 }
-function numberValue(record, ...keys) {
+function numberValue3(record, ...keys) {
   for (const key of keys) {
     const value = record[key];
     if (typeof value === "number" && Number.isFinite(value)) return value;
@@ -7377,37 +8166,73 @@ function pageOverlaps(recordStart, recordEnd, span) {
   return start <= (spanEnd ?? spanStart) && end >= spanStart;
 }
 function formMatches(record, span) {
-  const formNumber = textValue(record, "formNumber");
+  const formNumber = textValue2(record, "formNumber");
   if (!formNumber || !span.formNumber) return false;
-  return normalize(formNumber) === normalize(span.formNumber);
+  return normalize2(formNumber) === normalize2(span.formNumber);
 }
 function textMatches(record, span) {
-  const spanText = normalize(span.text);
+  const spanText = normalize2(span.text);
   const candidates = [
-    textValue(record, "originalContent", "content", "definition", "value"),
-    textValue(record, "name", "title", "term", "field", "coverageName"),
-    textValue(record, "limit", "deductible", "premium")
+    textValue2(record, "originalContent", "content", "definition", "value"),
+    textValue2(record, "name", "title", "term", "field", "coverageName"),
+    textValue2(record, "limit", "deductible", "premium")
   ].filter((value) => !!value && value.length >= 3);
-  return candidates.some((candidate) => spanText.includes(normalize(candidate)));
+  return candidates.some((candidate) => spanText.includes(normalize2(candidate)));
 }
 function sourceHashFor(spans) {
   return spans.map((span) => span.textHash ?? span.hash).filter(Boolean).join(":") || void 0;
 }
+function sourceUnit5(span) {
+  return span.sourceUnit ?? span.metadata?.sourceUnit;
+}
+function hierarchyScore(span) {
+  switch (sourceUnit5(span)) {
+    case "table_row":
+      return 5;
+    case "table":
+      return 3;
+    case "section":
+    case "page":
+      return 2;
+    case "table_cell":
+      return -2;
+    default:
+      return 0;
+  }
+}
+function parentRowId(span) {
+  return span.parentSpanId ?? span.table?.rowSpanId ?? span.metadata?.rowSpanId;
+}
+function preferParentRows(matches, sourceSpans) {
+  if (matches.length === 0) return matches;
+  const byId = new Map(sourceSpans.map((span) => [span.id, span]));
+  const expanded = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const match of matches) {
+    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);
+  }
+  return expanded;
+}
 function findSourceSpansForRecord(record, sourceSpans) {
   if (sourceSpans.length === 0) return [];
-  const pageStart = numberValue(record, "pageNumber", "pageStart");
-  const pageEnd = numberValue(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;
     if (formMatches(record, span)) score += 3;
     if (textMatches(record, span)) score += 2;
+    if (score > 0) score += hierarchyScore(span);
     return { span, score };
   }).filter((item) => item.score >= 2).sort((left, right) => {
     if (right.score !== left.score) return right.score - left.score;
     return left.span.id.localeCompare(right.span.id);
   });
-  return scored.slice(0, 3).map((item) => item.span);
+  return preferParentRows(scored.slice(0, 5).map((item) => item.span), sourceSpans).slice(0, 3);
 }
 function groundRecord(record, sourceSpans) {
   if (Array.isArray(record.sourceSpanIds) && record.sourceSpanIds.length > 0 && record.sourceTextHash) {
@@ -8115,6 +8940,14 @@ ${pageText}`;
           mergeMemoryResult(result.name, result.data, memory);
         }
       }
+      const recoveredCoverages = recoverCoverageScheduleRows({
+        memory,
+        sourceSpans,
+        pageAssignments
+      });
+      if (recoveredCoverages.recovered.length > 0) {
+        await log?.(`Recovered ${recoveredCoverages.recovered.length} source-backed coverage schedule row(s) from table evidence`);
+      }
       const planIncludesSupplementary = tasks.some((task) => task.extractorName === "supplementary");
       if (!planIncludesSupplementary && hasSupplementaryExtractionSignal(pageAssignments, formInventory, memory)) {
         onProgress?.("Extracting supplementary retrieval facts...");
@@ -8211,7 +9044,8 @@ ${pageText}`;
         memory,
         pageAssignments,
         reviewRounds,
-        sourceSpansAvailable: sourceSpans.length > 0
+        sourceSpansAvailable: sourceSpans.length > 0,
+        sourceSpans
       });
       if (shouldRunLlmReview(reviewMode, preReviewReport, sourceSpans.length > 0)) {
         for (let round = 0; round < maxReviewRounds; round++) {
@@ -8280,6 +9114,14 @@ ${pageText}`;
               mergeMemoryResult(result.name, result.data, memory);
             }
           }
+          const recoveredCoverages = recoverCoverageScheduleRows({
+            memory,
+            sourceSpans,
+            pageAssignments
+          });
+          if (recoveredCoverages.recovered.length > 0) {
+            await log?.(`Recovered ${recoveredCoverages.recovered.length} source-backed coverage schedule row(s) from follow-up table evidence`);
+          }
         }
       } else {
         onProgress?.("Skipping LLM extraction review; deterministic checks passed.");
@@ -8289,7 +9131,8 @@ ${pageText}`;
         memory,
         pageAssignments,
         reviewRounds,
-        sourceSpansAvailable: sourceSpans.length > 0
+        sourceSpansAvailable: sourceSpans.length > 0,
+        sourceSpans
       });
       if (reviewReport.issues.length > 0) {
         await log?.(
@@ -8315,10 +9158,12 @@ ${pageText}`;
       memory,
       pageAssignments,
       reviewRounds,
-      sourceSpansAvailable: sourceSpans.length > 0
+      sourceSpansAvailable: sourceSpans.length > 0,
+      sourceSpans
     }));
     onProgress?.("Assembling document...");
     const document = assembleDocument(id, documentType, memory);
+    attachDocumentStructure({ document, pageAssignments, sourceSpans });
     await pipelineCtx.save("assemble", {
       id,
       pageCount,
@@ -12116,6 +12961,11 @@ export {
   DeductibleTypeSchema,
   DefenseCostTreatmentSchema,
   DefinitionSchema,
+  DocumentAgentGuidanceSchema,
+  DocumentMetadataSchema,
+  DocumentNodeSchema,
+  DocumentPageMapEntrySchema,
+  DocumentTableOfContentsEntrySchema,
   DocumentTypeSchema,
   DriverRecordSchema,
   DwellingDetailsSchema,
@@ -12237,6 +13087,8 @@ export {
   SourceSpanLocationSchema,
   SourceSpanRefSchema,
   SourceSpanSchema,
+  SourceSpanTableLocationSchema,
+  SourceSpanUnitSchema,
   SubAnswerSchema,
   SubQuestionSchema,
   SubjectivityCategorySchema,