Add alpha layout confidence policy

crates/ethos-layout/src/lib.rs

@@ -21,10 +21,11 @@
 //! emitted as grounded headings, and multi-column text is ordered by column before
 //! vertical position.
 
+use ethos_core::codes::WarningCode;
 use ethos_core::error::EthosError;
 use ethos_core::geom::QRect;
-use ethos_core::ids::element_id;
-use ethos_core::model::{Element, ElementType, Span};
+use ethos_core::ids::{element_id, warning_id};
+use ethos_core::model::{Element, ElementType, Span, Warning};
 use ethos_core::traits::{Extraction, LayoutEngine, LayoutOutput};
 
 /// Deterministic paragraph-level layout engine.
@@ -37,12 +38,16 @@ const HEADING_MAX_WORDS: usize = 12;
 const HEADING_CONFIDENCE_LARGER_AND_BOLD: u16 = 900;
 const HEADING_CONFIDENCE_LARGER: u16 = 850;
 const HEADING_CONFIDENCE_BOLD_SAME_SIZE: u16 = 720;
+const LAYOUT_CONFIDENCE_WARNING_THRESHOLD: u16 = 800;
+const LOW_CONFIDENCE_READING_ORDER_MESSAGE: &str = "layout confidence below alpha threshold";
 const MAX_HEADING_LEVEL: u8 = 3;
 
 impl LayoutEngine for BasicLayoutEngine {
     fn layout(&self, extraction: &Extraction) -> Result<LayoutOutput, EthosError> {
         let mut elements = Vec::new();
+        let mut warnings = Vec::new();
         let mut next_element = 1u32;
+        let mut next_warning = 1u32;
 
         for page in &extraction.pages {
             let page_spans: Vec<SpanRef<'_>> = extraction
@@ -64,21 +69,18 @@ impl LayoutEngine for BasicLayoutEngine {
             let heading_sizes = heading_size_levels(&columns, body_font_size_q);
 
             for column in columns {
-                layout_column_lines(
-                    column.lines,
-                    body_font_size_q,
-                    &heading_sizes,
-                    &page.id,
-                    &mut next_element,
-                    &mut elements,
-                )?;
+                let mut sink = LayoutColumnSink {
+                    page_id: &page.id,
+                    next_element: &mut next_element,
+                    next_warning: &mut next_warning,
+                    elements: &mut elements,
+                    warnings: &mut warnings,
+                };
+                layout_column_lines(column.lines, body_font_size_q, &heading_sizes, &mut sink)?;
             }
         }
 
-        Ok(LayoutOutput {
-            elements,
-            warnings: Vec::new(),
-        })
+        Ok(LayoutOutput { elements, warnings })
     }
 }
 
@@ -106,6 +108,14 @@ struct Paragraph<'a> {
     bbox: QRect,
 }
 
+struct LayoutColumnSink<'a> {
+    page_id: &'a str,
+    next_element: &'a mut u32,
+    next_warning: &'a mut u32,
+    elements: &'a mut Vec<Element>,
+    warnings: &'a mut Vec<Warning>,
+}
+
 #[derive(Clone, Copy)]
 struct HeadingSignal {
     size_q: i64,
@@ -269,29 +279,27 @@ fn layout_column_lines<'a>(
     mut lines: Vec<Line<'a>>,
     body_font_size_q: Option<i64>,
     heading_sizes: &[i64],
-    page_id: &str,
-    next_element: &mut u32,
-    elements: &mut Vec<Element>,
+    sink: &mut LayoutColumnSink<'_>,
 ) -> Result<(), EthosError> {
     lines.sort_by(line_order);
     let mut text_lines = Vec::new();
     let mut line_iter = lines.into_iter().peekable();
 
     while let Some(line) = line_iter.next() {
         if is_list_item_line(&line) {
-            flush_text_lines(&mut text_lines, page_id, next_element, elements)?;
+            flush_text_lines(&mut text_lines, sink)?;
             let list_item_spans = line_spans(&line);
-            elements.push(build_element(
-                *next_element,
-                page_id,
+            sink.elements.push(build_element(
+                *sink.next_element,
+                sink.page_id,
                 &list_item_spans,
                 ElementType::ListItem,
                 None,
                 None,
             )?);
-            *next_element += 1;
+            *sink.next_element += 1;
         } else if let Some(signal) = heading_signal(&line, body_font_size_q) {
-            flush_text_lines(&mut text_lines, page_id, next_element, elements)?;
+            flush_text_lines(&mut text_lines, sink)?;
             let level = heading_level(signal.size_q, heading_sizes);
             let mut confidence = signal.confidence;
             let mut heading_lines = vec![line];
@@ -316,43 +324,68 @@ fn layout_column_lines<'a>(
                 heading_lines.push(next_line);
             }
             let heading_spans = lines_spans(&heading_lines);
-            elements.push(build_element(
-                *next_element,
-                page_id,
+            let mut element = build_element(
+                *sink.next_element,
+                sink.page_id,
                 &heading_spans,
                 ElementType::Heading,
                 Some(level),
                 Some(confidence),
-            )?);
-            *next_element += 1;
+            )?;
+            apply_confidence_policy(&mut element, sink.next_warning, sink.warnings)?;
+            sink.elements.push(element);
+            *sink.next_element += 1;
         } else {
             text_lines.push(line);
         }
     }
 
-    flush_text_lines(&mut text_lines, page_id, next_element, elements)
+    flush_text_lines(&mut text_lines, sink)
 }
 
 fn flush_text_lines<'a>(
     text_lines: &mut Vec<Line<'a>>,
-    page_id: &str,
-    next_element: &mut u32,
-    elements: &mut Vec<Element>,
+    sink: &mut LayoutColumnSink<'_>,
 ) -> Result<(), EthosError> {
     if text_lines.is_empty() {
         return Ok(());
     }
     for paragraph in group_paragraphs(std::mem::take(text_lines)) {
         let paragraph_spans = paragraph_spans(&paragraph);
-        elements.push(build_element(
-            *next_element,
-            page_id,
+        sink.elements.push(build_element(
+            *sink.next_element,
+            sink.page_id,
             &paragraph_spans,
             ElementType::TextBlock,
             None,
             None,
         )?);
-        *next_element += 1;
+        *sink.next_element += 1;
+    }
+    Ok(())
+}
+
+fn apply_confidence_policy(
+    element: &mut Element,
+    next_warning: &mut u32,
+    warnings: &mut Vec<Warning>,
+) -> Result<(), EthosError> {
+    if element
+        .confidence
+        .is_some_and(|confidence| confidence < LAYOUT_CONFIDENCE_WARNING_THRESHOLD)
+    {
+        let id = warning_id(*next_warning)?;
+        *next_warning += 1;
+        element.warning_refs.push(id.clone());
+        warnings.push(Warning {
+            id,
+            code: WarningCode::LowConfidenceReadingOrder,
+            message: LOW_CONFIDENCE_READING_ORDER_MESSAGE.to_string(),
+            page: Some(element.page.clone()),
+            element_ref: Some(element.id.clone()),
+            span_ref: None,
+            region_ref: None,
+        });
     }
     Ok(())
 }
@@ -865,10 +898,12 @@ mod tests {
         assert_eq!(output.elements[0].element_type, ElementType::Heading);
         assert_eq!(output.elements[0].heading_level, Some(1));
         assert_eq!(output.elements[0].confidence, Some(850));
+        assert!(output.elements[0].warning_refs.is_empty());
         assert_eq!(output.elements[0].text.as_deref(), Some("Overview"));
         assert_eq!(output.elements[0].span_refs, vec!["s000001".to_string()]);
         assert_eq!(output.elements[1].element_type, ElementType::TextBlock);
         assert_eq!(output.elements[1].text.as_deref(), Some("Body text"));
+        assert!(output.warnings.is_empty());
     }
 
     #[test]
@@ -902,8 +937,23 @@ mod tests {
         assert_eq!(output.elements[0].element_type, ElementType::Heading);
         assert_eq!(output.elements[0].heading_level, Some(1));
         assert_eq!(output.elements[0].confidence, Some(720));
+        assert_eq!(output.elements[0].warning_refs, vec!["w0001".to_string()]);
         assert_eq!(output.elements[0].text.as_deref(), Some("Background"));
         assert_eq!(output.elements[1].text.as_deref(), Some("Plain body"));
+        assert_eq!(output.warnings.len(), 1);
+        assert_eq!(output.warnings[0].id, "w0001");
+        assert_eq!(
+            output.warnings[0].code,
+            WarningCode::LowConfidenceReadingOrder
+        );
+        assert_eq!(
+            output.warnings[0].message,
+            LOW_CONFIDENCE_READING_ORDER_MESSAGE
+        );
+        assert_eq!(output.warnings[0].page.as_deref(), Some("p0001"));
+        assert_eq!(output.warnings[0].element_ref.as_deref(), Some("e000001"));
+        assert_eq!(output.warnings[0].span_ref, None);
+        assert_eq!(output.warnings[0].region_ref, None);
     }
 
     #[test]

docs/execution-status.md

@@ -15,8 +15,8 @@ The committed implementation now includes:
 - Runtime checks that reject missing or mismatched PDFium versions, release artifacts, and extracted libraries with stable errors before dynamic loading.
 - The determinism workflow includes a Windows x64 preflight lane for core c14n/profile/fingerprint contract tests, while PDFium-backed corpus work remains explicitly skipped unless the pinned runtime is configured on that runner. A static workflow test guards that matrix wiring.
 - `ethos doc parse` / `ethos fingerprint` PDF execution through a worker process with `max_parse_ms` timeout enforcement, stable error-envelope relay, diagnostics-gated worker stderr, and page-range validation/filtering.
-- Quantized page/span extraction at the backend boundary, plus a basic deterministic layout pass that assembles paragraph `text_block` elements, fixture-backed alpha heading and flat list-item elements, and simple column reading order for the current born-digital fixtures. Fixture validation binds selected `fixture.json` expectations to committed extraction/layout goldens and binds current alpha text/Markdown exports to committed layout output so current read-order, element-type, heading-export, list-item, and export cases fail closed on drift.
-- An internal layout evaluator scaffold exists at `fixtures/evaluate_layout_alpha.py` and `make layout-evaluator-alpha`. It reads committed `fixture.json` and `layout.json` files, summarizes alpha element-type and subset coverage, and fails closed on missing layout expectations or drift in fixture-backed reading order / heading / list-item cases.
+- Quantized page/span extraction at the backend boundary, plus a basic deterministic layout pass that assembles paragraph `text_block` elements, fixture-backed alpha heading and flat list-item elements, and simple column reading order for the current born-digital fixtures. Current alpha layout confidence is explicit for heading signals, and below-threshold layout confidence emits deterministic `low_confidence_reading_order` diagnostics instead of staying silent. Fixture validation binds selected `fixture.json` expectations to committed extraction/layout goldens and binds current alpha text/Markdown exports to committed layout output so current read-order, element-type, heading-export, list-item, and export cases fail closed on drift.
+- An internal layout evaluator scaffold exists at `fixtures/evaluate_layout_alpha.py` and `make layout-evaluator-alpha`. It reads committed `fixture.json` and `layout.json` files, summarizes alpha element-type and subset coverage, and fails closed on missing layout expectations, confidence-policy drift, or drift in fixture-backed reading order / heading / list-item cases.
 - Schema/example/profile validation is green through `schemas/validate_examples.py` using `jsonschema` draft 2020-12 validation, including the crop descriptor artifact contract plus referential-integrity and bbox sanity checks outside JSON Schema.
 - `ethos verify` now produces non-empty quote, value, presence, and table-cell verification checks over native Ethos document JSON and synthetic OpenDataLoader-style JSON through `--grounding opendataloader-json`; it also verifies quote/value/presence citations over pinned real OpenDataLoader 2.4.7 JSON, including grounded and ungrounded cases. Citation/config inputs are rejected when they drift outside the closed schemas. The public demo harness covers grounded, ungrounded, split-quote, not-found, stale-fingerprint, unsupported non-v1 claim, capability-limited, malformed-citation, malformed OpenDataLoader-style input, and summary-format reject paths.
 - Verification semantics are now trust-honest at alpha scope: quote containment is explicitly labeled, value/table-cell checks require normalized equality, fingerprint-pinned citations fail closed when source fingerprints are unavailable, and structured capability limits explain why a run is downgraded.
@@ -52,8 +52,8 @@ Milestone A has an accepted internal Gate Zero decision for roadmap control, so
 | PDFium Phase 1 profile | Landed: pinned profile, V8/XFA-disabled state, platform hashes, runtime library hashes, and provenance are recorded | Phase 2 project-maintained builds still block Public Beta |
 | PDFium loader/runtime checks | Landed: missing/mismatched version, artifact, and runtime library hashes fail deterministically | Release packaging and operator setup path still need hardening |
 | Real PDF backend | Landed for simple born-digital PDFs: page count, quantized spans, worker execution, timeout, page filtering, and fingerprint path exist | Wider corpus coverage, failure fixtures, memory-limit behavior, quirk log, and Gate Zero run are still missing |
-| Layout groundwork | Landed: basic paragraph text blocks, fixture-backed alpha heading and flat list-item elements, simple column reading order over quantized spans, fixture metadata checks against committed extraction/layout goldens for current read-order and element-type expectations, and alpha text/Markdown export goldens derived from committed layout output | Tables, nested/richer list and heading semantics, rotation/quirk handling, and confidence policy remain future work |
-| Layout evaluator scaffold | Landed: deterministic internal evaluator over committed layout fixture expectations, with heading/list/reading-order coverage checks, expectation drift diagnostics, report JSON, Make target, and unit coverage | Broader evaluator dimensions and CI matrix integration remain future work |
+| Layout groundwork | Landed: basic paragraph text blocks, fixture-backed alpha heading and flat list-item elements, simple column reading order over quantized spans, explicit alpha heading-confidence values, deterministic below-threshold confidence diagnostics, fixture metadata checks against committed extraction/layout goldens for current read-order and element-type expectations, and alpha text/Markdown export goldens derived from committed layout output | Tables, nested/richer list and heading semantics, rotation/quirk handling, and broader confidence dimensions remain future work |
+| Layout evaluator scaffold | Landed: deterministic internal evaluator over committed layout fixture expectations, with heading/list/reading-order coverage checks, confidence-policy checks, expectation drift diagnostics, report JSON, Make target, and unit coverage | Broader evaluator dimensions and CI matrix integration remain future work |
 | Python surface scaffold | Landed: internal stdlib wrapper over a caller-provided local `ethos doc parse` command, with explicit JSON/Markdown/text methods, page selection passthrough, diagnostics passthrough, timeout handling, command failure reporting, and mocked-command unit coverage | Native binding work, broader API design, and public setup path remain future work |
 | Font policy groundwork | Partially landed: substitution table and profile policy are present; fixture output uses deterministic substitution IDs | Bundled fallback asset hashing and broader font/CID validation remain open |
 | Schema/example validation | Landed: schemas, examples, deterministic profile, referential integrity, and bbox sanity pass the `jsonschema` validation gate | Contract changes still require explicit versioning and compatibility review |