docs: separate precision suite roles and ForthWall safety

README.adoc

@@ -20,17 +20,58 @@ This project must declare **MPL-2.0-or-later** for platform/tooling compatibilit
 
 Philosophy: **Palimpsest**. The MPL-2.0 (PMPL) text is provided in `license/MPL-2.0.txt`, and the canonical source is the palimpsest-license repository.
 
-Cross-platform document editor with format tabs (TXT/MD/ADOC/DJOT/ORG/RST/TYP). Gossamer GUI + Ada TUI. Graph visualization, OCR, TTS/STT, Nickel pipelines.
+DocMatrix is multi-format document conversion and precision infrastructure for
+the wider document suite. The tabbed multi-format viewer/editor is the separate
+*Formatrix Docs* project. GUI, TUI, graph, and editor claims in copied or
+ecosystem-level documents must not be attributed to DocMatrix itself.
+
+ForthWall is a proposed capability-bounded Forth execution layer for critical
+precision operations. It is not currently implemented or proved.
 
 == Features
 
-* *Format Tabs* - View and edit the same document in multiple markup formats
-* *Unified AST* - Lossless conversion between formats
-* *GUI* - Gossamer with AffineScript frontend
-* *TUI* - Ada with AdaCurses for terminal usage
-* *Graph Visualization* - ArangoDB for document relationships
-* *Accessibility* - OCR, TTS, STT support
-* *Pipelines* - Nickel-based import/export transformations
+* *Current core* - Parse and render supported formats through a unified AST
+* *Current interfaces* - Rust conversion APIs plus a C ABI/FFI surface
+* *Suite boundary* - Formatrix Docs owns the tabbed viewer/editor experience
+* *Critical-mode proposal* - ForthWall rules bounded to declared inputs,
+  approved document operations, and independently verified outputs
+
+== Precision document suite
+
+DocMatrix is designed to cooperate with two distinct user-facing tools:
+
+* https://github.com/hyperpolymath/formatrix-docs[Formatrix Docs] — view one
+  logical document through tabbed TXT, delimiter-selected tabular text,
+  Markdown, AsciiDoc, Djot, and A2ML representations, with synchronised editing
+  as the intended progression; and
+* https://github.com/hyperpolymath/blocky-writer[Blocky Writer] — fit content
+  into fixed-layout PDF and application-form boxes, baselines, and
+  per-character cells that were designed for hand spacing rather than reliable
+  computer entry.
+
+The responsibilities must remain separate in code and evidence. Conversion
+correctness does not prove synchronised editing, and synchronised editing does
+not prove page-coordinate placement. A ForthWall operation may coordinate a
+bounded critical step only after the relevant component's own semantic,
+round-trip, geometry, confinement, and independent-verification gates pass.
+The versioned composition contract is tracked in
+https://github.com/hyperpolymath/docmatrix/issues/71[issue #71]; it explicitly
+forbids making Microsoft Word or another lossy hub format mandatory.
+
+== Conversion delivery gate
+
+DocMatrix conversion claims require independently reproducible tests that
+round trips preserve every construct described as lossless, lossy conversions
+are reported, input and output formats are identified, and malformed or
+ambiguous documents fail without silent rewriting. Viewer/editor behaviours
+such as cursor mapping, synchronised tabs, and undo/redo belong to Formatrix
+Docs and must be proved there.
+
+Critical-mode automatic editing through the proposed ForthWall layer has an
+additional safety gate: bounded capabilities, exact input hashes and evidence
+spans, semantic refusal conditions, replay traces, and independent verification
+of every applied edit. See
+https://github.com/hyperpolymath/docmatrix/issues/70[issue #70].
 
 == Supported Formats
 
@@ -57,11 +98,10 @@ just deps
 # Build all components
 just build
 
-# Run GUI
-just run-gui
+# Exercise the currently evidenced conversion core
+just test-core
 
-# Run TUI
-just run-tui
+# GUI and TUI recipes are ecosystem scaffolding, not DocMatrix capability proof
 ----
 
 == Architecture

crates/formatrix-core/benches/format_bench.rs

@@ -2,12 +2,12 @@
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 //! Benchmark tests for format conversion performance
 
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
 use formatrix_core::{
     ast::{Block, Document, DocumentMeta, Inline, SourceFormat},
-    traits::{Parser, ParseConfig, RenderConfig, Renderer},
     formats::PlainTextHandler,
+    traits::{ParseConfig, Parser, RenderConfig, Renderer},
 };
-use criterion::{black_box, criterion_group, criterion_main, Criterion};
 
 /// Benchmark plaintext parsing of small documents
 fn bench_parse_small_plaintext(c: &mut Criterion) {
@@ -26,7 +26,8 @@ fn bench_parse_medium_plaintext(c: &mut Criterion) {
     c.bench_function("parse_medium_plaintext_10kb", |b| {
         b.iter(|| {
             let parser = PlainTextHandler::new();
-            let input = black_box(&"Lorem ipsum dolor sit amet.\n\n".repeat(500));
+            let source = "Lorem ipsum dolor sit amet.\n\n".repeat(500);
+            let input = black_box(source.as_str());
             let config = ParseConfig::default();
             parser.parse(input, &config)
         })
@@ -38,7 +39,8 @@ fn bench_parse_large_plaintext(c: &mut Criterion) {
     c.bench_function("parse_large_plaintext_100kb", |b| {
         b.iter(|| {
             let parser = PlainTextHandler::new();
-            let input = black_box(&"Lorem ipsum dolor sit amet.\n\n".repeat(5000));
+            let source = "Lorem ipsum dolor sit amet.\n\n".repeat(5000);
+            let input = black_box(source.as_str());
             let config = ParseConfig::default();
             parser.parse(input, &config)
         })
@@ -51,14 +53,12 @@ fn bench_render_plaintext(c: &mut Criterion) {
         let doc = Document {
             source_format: SourceFormat::PlainText,
             meta: DocumentMeta::default(),
-            content: vec![
-                Block::Paragraph {
-                    content: vec![Inline::Text {
-                        content: "Test paragraph content.".to_string(),
-                    }],
-                    span: None,
-                },
-            ],
+            content: vec![Block::Paragraph {
+                content: vec![Inline::Text {
+                    content: "Test paragraph content.".to_string(),
+                }],
+                span: None,
+            }],
             raw_source: None,
         };
 
@@ -93,8 +93,10 @@ fn bench_parse_with_source_preservation(c: &mut Criterion) {
         b.iter(|| {
             let parser = PlainTextHandler::new();
             let input = black_box("Test content with preservation.\n\nAnother paragraph.");
-            let mut config = ParseConfig::default();
-            config.preserve_raw_source = true;
+            let config = ParseConfig {
+                preserve_raw_source: true,
+                ..Default::default()
+            };
 
             parser.parse(input, &config)
         })
@@ -107,8 +109,10 @@ fn bench_parse_with_span_preservation(c: &mut Criterion) {
         b.iter(|| {
             let parser = PlainTextHandler::new();
             let input = black_box("Test content with spans.\n\nAnother paragraph.");
-            let mut config = ParseConfig::default();
-            config.preserve_spans = true;
+            let config = ParseConfig {
+                preserve_spans: true,
+                ..Default::default()
+            };
 
             parser.parse(input, &config)
         })
@@ -118,26 +122,22 @@ fn bench_parse_with_span_preservation(c: &mut Criterion) {
 /// Benchmark document creation
 fn bench_document_creation(c: &mut Criterion) {
     c.bench_function("create_document_with_metadata", |b| {
-        b.iter(|| {
-            Document {
-                source_format: SourceFormat::PlainText,
-                meta: DocumentMeta {
-                    title: Some("Test Title".to_string()),
-                    authors: vec!["Author".to_string()],
-                    date: Some("2026-04-04".to_string()),
-                    language: Some("en".to_string()),
-                    ..Default::default()
-                },
-                content: vec![
-                    Block::Paragraph {
-                        content: vec![Inline::Text {
-                            content: black_box("Content".to_string()),
-                        }],
-                        span: None,
-                    },
-                ],
-                raw_source: None,
-            }
+        b.iter(|| Document {
+            source_format: SourceFormat::PlainText,
+            meta: DocumentMeta {
+                title: Some("Test Title".to_string()),
+                authors: vec!["Author".to_string()],
+                date: Some("2026-04-04".to_string()),
+                language: Some("en".to_string()),
+                ..Default::default()
+            },
+            content: vec![Block::Paragraph {
+                content: vec![Inline::Text {
+                    content: black_box("Content".to_string()),
+                }],
+                span: None,
+            }],
+            raw_source: None,
         })
     });
 }
@@ -150,7 +150,8 @@ fn bench_batch_parsing(c: &mut Criterion) {
             let config = ParseConfig::default();
 
             for i in 0..10 {
-                let input = black_box(&format!("Document {}.\n\nContent.", i));
+                let source = format!("Document {}.\n\nContent.", i);
+                let input = black_box(source.as_str());
                 let _ = parser.parse(input, &config);
             }
         })

crates/formatrix-core/src/ast.rs

@@ -683,16 +683,18 @@ mod proptests {
             prop_assert!(format.extension() != format.label() || format.extension() == format.label().to_lowercase());
         }
 
-        // Property: Document word_count is non-negative
+        // Property: Document word_count composes from its blocks
         #[test]
-        fn prop_document_word_count_nonnegative(doc in document_strategy()) {
-            prop_assert!(doc.word_count() >= 0);
+        fn prop_document_word_count_composes(doc in document_strategy()) {
+            let expected: usize = doc.content.iter().map(Block::word_count).sum();
+            prop_assert_eq!(doc.word_count(), expected);
         }
 
-        // Property: Document char_count is non-negative
+        // Property: Document char_count composes from its blocks
         #[test]
-        fn prop_document_char_count_nonnegative(doc in document_strategy()) {
-            prop_assert!(doc.char_count() >= 0);
+        fn prop_document_char_count_composes(doc in document_strategy()) {
+            let expected: usize = doc.content.iter().map(Block::char_count).sum();
+            prop_assert_eq!(doc.char_count(), expected);
         }
 
         // Property: Empty document has zero word count
@@ -742,7 +744,7 @@ mod proptests {
                 span: None,
             };
             if let Block::Heading { level: l, .. } = block {
-                prop_assert!(l >= 1 && l <= 6);
+                prop_assert!((1..=6).contains(&l));
             }
         }
 

crates/formatrix-core/src/formats/djot.rs

@@ -280,7 +280,7 @@ fn container_to_block(
 
         Container::Div { class } => {
             // Check if it's an admonition
-            let admonition = match class.as_ref() {
+            let admonition = match class {
                 "note" => Some(AdmonitionType::Note),
                 "tip" => Some(AdmonitionType::Tip),
                 "warning" => Some(AdmonitionType::Warning),
@@ -537,11 +537,11 @@ fn render_inline(output: &mut String, inline: &Inline) {
         }
 
         Inline::Strong { content } => {
-            output.push_str("*");
+            output.push('*');
             for i in content {
                 render_inline(output, i);
             }
-            output.push_str("*");
+            output.push('*');
         }
 
         Inline::Strikethrough { content } => {
@@ -602,9 +602,9 @@ fn render_inline(output: &mut String, inline: &Inline) {
         }
 
         Inline::RawInline { content, .. } => {
-            output.push_str("`");
+            output.push('`');
             output.push_str(content);
-            output.push_str("`");
+            output.push('`');
         }
 
         _ => {}

crates/formatrix-core/src/formats/markdown.rs

@@ -159,29 +159,26 @@ fn parse_node<'a>(node: &'a AstNode<'a>) -> Option<Block> {
             let columns = Vec::new(); // Would need to extract from table alignments
 
             for child in node.children() {
-                match child.data.borrow().value {
-                    NodeValue::TableRow(is_header) => {
-                        let cells: Vec<TableCell> = child
-                            .children()
-                            .map(|cell| TableCell {
-                                content: vec![Block::Paragraph {
-                                    content: parse_inlines(cell),
-                                    span: None,
-                                }],
-                                colspan: 1,
-                                rowspan: 1,
-                                alignment: None,
-                            })
-                            .collect();
-
-                        let row = TableRow { cells };
-                        if is_header {
-                            header = Some(row);
-                        } else {
-                            body.push(row);
-                        }
+                if let NodeValue::TableRow(is_header) = child.data.borrow().value {
+                    let cells: Vec<TableCell> = child
+                        .children()
+                        .map(|cell| TableCell {
+                            content: vec![Block::Paragraph {
+                                content: parse_inlines(cell),
+                                span: None,
+                            }],
+                            colspan: 1,
+                            rowspan: 1,
+                            alignment: None,
+                        })
+                        .collect();
+
+                    let row = TableRow { cells };
+                    if is_header {
+                        header = Some(row);
+                    } else {
+                        body.push(row);
                     }
-                    _ => {}
                 }
             }
 

crates/formatrix-core/src/formats/orgmode.rs

@@ -276,7 +276,7 @@ where
     use orgize::Event;
     let mut inlines = Vec::new();
 
-    while let Some(event) = events.next() {
+    for event in events.by_ref() {
         match &event {
             Event::End(elem) if is_end_element(elem) => break,
             Event::Start(Element::Text { value }) | Event::End(Element::Text { value }) => {
@@ -480,7 +480,7 @@ where
     I: Iterator<Item = orgize::Event<'a, 'b>>,
 {
     use orgize::Event;
-    while let Some(event) = events.next() {
+    for event in events.by_ref() {
         if matches!(event, Event::End(Element::TableRow(_))) {
             break;
         }
@@ -531,11 +531,11 @@ where
     use orgize::Event;
     let mut text = String::new();
 
-    while let Some(event) = events.next() {
+    for event in events.by_ref() {
         match event {
             Event::End(Element::TableCell(_)) => break,
             Event::Start(Element::Text { value }) | Event::End(Element::Text { value }) => {
-                text.push_str(&value);
+                text.push_str(value);
             }
             _ => {}
         }