formats: add txt conversion cli

Cargo.lock

@@ -5,3 +5,18 @@ version = 4
 [[package]]
 name = "mb3-dat"
 version = "0.1.0"
+
+[[package]]
+name = "mb3-txt"
+version = "0.1.0"
+dependencies = [
+ "mb3-dat",
+]
+
+[[package]]
+name = "nanobrush-cli"
+version = "0.1.0"
+dependencies = [
+ "mb3-dat",
+ "mb3-txt",
+]

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["crates/mb3-dat"]
+members = ["crates/mb3-dat", "crates/mb3-txt", "crates/nanobrush-cli"]
 resolver = "3"
 
 [workspace.package]

README.md

@@ -70,3 +70,9 @@ See [setup validation](docs/SETUP.md) for the implementation, checks, and remain
 `crates/mb3-dat` provides dependency-free bounded readers/writers for both recovered DAT versions. Run `cargo test --workspace --locked --offline` inside `nix develop` after hydrating and verifying the converter fixtures (`analyze-converter check`). All 58 captured DAT outputs are tested for exact byte round trips. See [API, compatibility and limits](docs/RUST_DAT.md).
 
 The asset-free Nix check `nix build .#checks.aarch64-darwin.rust --no-link` runs formatting, Clippy, unit tests and doctests; full converter integration tests require Xet assets.
+
+## Native TXT/DAT CLI
+
+`nix run .#nanobrush -- inspect FILE` prints a JSON summary; `validate FILE` checks structure. Convert with `convert INPUT OUTPUT --to txt`, `--to dat-201501280`, or `--to dat-201512200`. Inside the dev shell, use `cargo run -p nanobrush-cli -- ...`. Existing outputs require `--force`; source aliases and output symlinks are refused.
+
+[TXT compatibility](docs/RUST_TXT.md) documents strict UTF-8 input, BOM output, finite numbers and computed-data consistency. [CLI usage and publication](docs/CLI.md) covers limits, exit codes and atomic saves. Full Cargo tests require hydrated converter fixtures; Nix checks and the native package build exclude assets.

crates/mb3-txt/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "mb3-txt"
+version = "0.1.0"
+description = "Bounded UTF-8 Microbrush 3 TXT readers and writers"
+edition.workspace = true
+rust-version.workspace = true
+publish = false
+
+[dependencies]
+mb3-dat = { path = "../mb3-dat" }
+
+[lints]
+workspace = true

crates/mb3-txt/src/lib.rs

@@ -0,0 +1,197 @@
+//! Bounded MB3 TXT serialization using the shared `mb3_dat::World` model.
+//! Input is UTF-8 with an optional BOM. Output is canonical UTF-8 with a BOM.
+//! No geometry is evaluated, property tables optimized, or data silently dropped.
+//!
+//! ```
+//! use mb3_dat::{Limits, World};
+//! let world = World::default();
+//! let bytes = mb3_txt::encode(&world, &Limits::default())?;
+//! assert_eq!(mb3_txt::decode(&bytes, &Limits::default())?, world);
+//! # Ok::<(), mb3_txt::Error>(())
+//! ```
+mod parser;
+mod writer;
+use mb3_dat::Limits;
+pub use parser::decode;
+use std::fmt;
+use std::io::{self, Read, Write};
+use std::mem::size_of;
+pub use writer::encode;
+
+#[derive(Debug)]
+#[non_exhaustive]
+pub enum ErrorKind {
+    Io(io::Error),
+    InvalidUtf8,
+    Syntax(&'static str),
+    InvalidNumber,
+    NonFinite,
+    InvalidEscape,
+    EmbeddedNul,
+    UnterminatedString,
+    UnterminatedComment,
+    LimitExceeded(&'static str),
+    Allocation,
+    CountOverflow,
+    DuplicateName,
+    DuplicateProperty(u32),
+    PropertyIndex(u32),
+    UnsortedProperties,
+    InconsistentComputedData,
+    InvalidPatchLength,
+}
+#[derive(Debug)]
+pub struct Error {
+    pub offset: usize,
+    pub kind: ErrorKind,
+}
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "MB3 TXT at byte {}: {:?}", self.offset, self.kind)
+    }
+}
+impl std::error::Error for Error {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match &self.kind {
+            ErrorKind::Io(e) => Some(e),
+            _ => None,
+        }
+    }
+}
+type Result<T> = std::result::Result<T, Error>;
+fn err(offset: usize, kind: ErrorKind) -> Error {
+    Error { offset, kind }
+}
+
+#[derive(Default)]
+struct Budget {
+    items: usize,
+    owned: usize,
+}
+impl Budget {
+    fn items(&mut self, n: usize, limits: &Limits, at: usize) -> Result<()> {
+        self.items = self
+            .items
+            .checked_add(n)
+            .ok_or_else(|| err(at, ErrorKind::CountOverflow))?;
+        if self.items > limits.max_items {
+            return Err(err(at, ErrorKind::LimitExceeded("aggregate items")));
+        }
+        Ok(())
+    }
+    fn bytes(&mut self, n: usize, limits: &Limits, at: usize) -> Result<()> {
+        self.owned = self
+            .owned
+            .checked_add(n)
+            .ok_or_else(|| err(at, ErrorKind::CountOverflow))?;
+        if self.owned > limits.max_owned_bytes {
+            return Err(err(at, ErrorKind::LimitExceeded("owned storage")));
+        }
+        Ok(())
+    }
+    fn push<T>(&mut self, out: &mut Vec<T>, value: T, limits: &Limits, at: usize) -> Result<()> {
+        self.items(1, limits, at)?;
+        if out.len() == out.capacity() {
+            let cap = out
+                .capacity()
+                .saturating_mul(2)
+                .max(1)
+                .min(limits.max_items);
+            let bytes = (cap - out.capacity())
+                .checked_mul(size_of::<T>())
+                .ok_or_else(|| err(at, ErrorKind::CountOverflow))?;
+            self.bytes(bytes, limits, at)?;
+            out.try_reserve_exact(cap - out.len())
+                .map_err(|_| err(at, ErrorKind::Allocation))?;
+        }
+        out.push(value);
+        Ok(())
+    }
+}
+
+fn unique_names(names: &[String], budget: &mut Budget, limits: &Limits, at: usize) -> Result<()> {
+    budget.bytes(
+        names
+            .len()
+            .checked_mul(size_of::<usize>())
+            .ok_or_else(|| err(at, ErrorKind::CountOverflow))?,
+        limits,
+        at,
+    )?;
+    let mut indices = Vec::new();
+    indices
+        .try_reserve_exact(names.len())
+        .map_err(|_| err(at, ErrorKind::Allocation))?;
+    indices.extend(0..names.len());
+    indices.sort_unstable_by(|a, b| names[*a].cmp(&names[*b]));
+    if indices.windows(2).any(|p| names[p[0]] == names[p[1]]) {
+        return Err(err(at, ErrorKind::DuplicateName));
+    }
+    Ok(())
+}
+fn product(a: usize, b: usize, at: usize) -> Result<usize> {
+    a.checked_mul(b)
+        .ok_or_else(|| err(at, ErrorKind::CountOverflow))
+}
+fn grid(au: u32, av: u32, qu: u32, qv: u32, at: usize) -> Result<usize> {
+    let u = product(au as usize / 2, qu as usize, at)?
+        .checked_add(1)
+        .ok_or_else(|| err(at, ErrorKind::CountOverflow))?;
+    let v = product(av as usize / 2, qv as usize, at)?
+        .checked_add(1)
+        .ok_or_else(|| err(at, ErrorKind::CountOverflow))?;
+    product(u, v, at)
+}
+fn append(out: &mut Vec<u8>, bytes: &[u8], limit: usize) -> Result<()> {
+    let at = out.len();
+    let n = at
+        .checked_add(bytes.len())
+        .ok_or_else(|| err(at, ErrorKind::CountOverflow))?;
+    if n > limit {
+        return Err(err(at, ErrorKind::LimitExceeded("file bytes")));
+    }
+    if n > out.capacity() {
+        let cap = n.max(out.capacity().saturating_mul(2)).min(limit);
+        out.try_reserve_exact(cap - at)
+            .map_err(|_| err(at, ErrorKind::Allocation))?;
+    }
+    out.extend_from_slice(bytes);
+    Ok(())
+}
+/// Bounded buffering, then strict decoding; interrupted and short reads work.
+pub fn read(mut source: impl Read, limits: &Limits) -> Result<mb3_dat::World> {
+    let mut data = Vec::new();
+    let mut chunk = [0; 8192];
+    loop {
+        let n = limits
+            .max_bytes
+            .saturating_sub(data.len())
+            .saturating_add(1)
+            .min(chunk.len());
+        let n = match source.read(&mut chunk[..n]) {
+            Ok(0) => break,
+            Ok(n) => n,
+            Err(e) if e.kind() == io::ErrorKind::Interrupted => continue,
+            Err(e) => return Err(err(data.len(), ErrorKind::Io(e))),
+        };
+        append(&mut data, &chunk[..n], limits.max_bytes)?;
+    }
+    decode(&data, limits)
+}
+/// Validate/encode before touching the destination; does not flush or promise
+/// filesystem atomicity. Later I/O failure can leave a completed prefix.
+pub fn write(mut destination: impl Write, world: &mb3_dat::World, limits: &Limits) -> Result<()> {
+    let data = encode(world, limits)?;
+    let mut written = 0;
+    while written != data.len() {
+        match destination.write(&data[written..]) {
+            Ok(0) => return Err(err(written, ErrorKind::Io(io::ErrorKind::WriteZero.into()))),
+            Ok(n) => written += n,
+            Err(e) if e.kind() == io::ErrorKind::Interrupted => continue,
+            Err(e) => return Err(err(written, ErrorKind::Io(e))),
+        }
+    }
+    Ok(())
+}
+#[cfg(test)]
+mod tests;

crates/mb3-txt/src/parser.rs

@@ -0,0 +1,468 @@
+use super::*;
+use mb3_dat::{Brush, Patch9, PatchComputed, Plane, Property, Uv, Vec3, World};
+
+#[derive(Clone, Copy, PartialEq)]
+enum Kind<'a> {
+    Word(&'a str),
+    Number(&'a str, bool),
+    Str(&'a str),
+    Symbol(u8),
+    End,
+}
+#[derive(Clone, Copy)]
+struct Token<'a> {
+    kind: Kind<'a>,
+    at: usize,
+}
+struct Parser<'a> {
+    source: &'a str,
+    pos: usize,
+    look: Option<Token<'a>>,
+    limits: &'a Limits,
+    budget: Budget,
+}
+impl<'a> Parser<'a> {
+    fn lex(&mut self) -> Result<Token<'a>> {
+        let bytes = self.source.as_bytes();
+        loop {
+            while self.pos < bytes.len() && matches!(bytes[self.pos], b' ' | b'\t' | b'\r' | b'\n')
+            {
+                self.pos += 1;
+            }
+            if bytes.get(self.pos..self.pos.saturating_add(2)) == Some(b"//") {
+                self.pos += 2;
+                while self.pos < bytes.len() && !matches!(bytes[self.pos], b'\r' | b'\n') {
+                    self.pos += 1;
+                }
+            } else if bytes.get(self.pos..self.pos.saturating_add(2)) == Some(b"/*") {
+                let at = self.pos;
+                self.pos += 2;
+                while self.pos + 1 < bytes.len() && &bytes[self.pos..self.pos + 2] != b"*/" {
+                    self.pos += 1;
+                }
+                if self.pos + 1 >= bytes.len() {
+                    return Err(err(at, ErrorKind::UnterminatedComment));
+                }
+                self.pos += 2;
+            } else {
+                break;
+            }
+        }
+        let at = self.pos;
+        let kind = match bytes.get(at).copied() {
+            None => Kind::End,
+            Some(b'(' | b')' | b'[' | b']' | b',') => {
+                self.pos += 1;
+                Kind::Symbol(bytes[at])
+            }
+            Some(b'"') => {
+                self.pos += 1;
+                let start = self.pos;
+                while self.pos < bytes.len() && bytes[self.pos] != b'"' {
+                    match bytes[self.pos] {
+                        0 => return Err(err(self.pos, ErrorKind::EmbeddedNul)),
+                        b'\'' => {
+                            return Err(err(self.pos, ErrorKind::Syntax("escape single quote")));
+                        }
+                        b'\\' => {
+                            self.pos += 1;
+                            if !matches!(
+                                bytes.get(self.pos),
+                                Some(b'r' | b'n' | b't' | b'\'' | b'"' | b'\\')
+                            ) {
+                                return Err(err(self.pos, ErrorKind::InvalidEscape));
+                            }
+                        }
+                        _ => (),
+                    }
+                    self.pos += 1;
+                }
+                if self.pos == bytes.len() {
+                    return Err(err(at, ErrorKind::UnterminatedString));
+                }
+                let raw = &self.source[start..self.pos];
+                self.pos += 1;
+                Kind::Str(raw)
+            }
+            Some(b'a'..=b'z' | b'A'..=b'Z' | b'_' | b'$') => {
+                self.pos += 1;
+                while matches!(
+                    bytes.get(self.pos),
+                    Some(b'a'..=b'z' | b'A'..=b'Z' | b'_' | b'$' | b'0'..=b'9')
+                ) {
+                    self.pos += 1;
+                }
+                Kind::Word(&self.source[at..self.pos])
+            }
+            Some(b'+' | b'-' | b'.' | b'0'..=b'9') => {
+                if matches!(bytes[self.pos], b'+' | b'-') {
+                    self.pos += 1;
+                }
+                let digits = self.pos;
+                self.digits(at)?;
+                let before = self.pos - digits;
+                let dot = bytes.get(self.pos) == Some(&b'.');
+                let mut after = 0;
+                if dot {
+                    self.pos += 1;
+                    let start = self.pos;
+                    self.digits(at)?;
+                    after = self.pos - start;
+                }
+                if before + after == 0 {
+                    return Err(err(at, ErrorKind::InvalidNumber));
+                }
+                let exponent = matches!(bytes.get(self.pos), Some(b'e' | b'E'));
+                if exponent {
+                    self.pos += 1;
+                    if matches!(bytes.get(self.pos), Some(b'+' | b'-')) {
+                        self.pos += 1;
+                    }
+                    let start = self.pos;
+                    self.digits(at)?;
+                    if start == self.pos {
+                        return Err(err(at, ErrorKind::InvalidNumber));
+                    }
+                }
+                if self.pos - at > 128 {
+                    return Err(err(at, ErrorKind::LimitExceeded("numeric token bytes")));
+                }
+                if !dot && before > 1 && bytes[digits] == b'0' {
+                    return Err(err(at, ErrorKind::InvalidNumber));
+                }
+                Kind::Number(&self.source[at..self.pos], !dot && !exponent)
+            }
+            _ => return Err(err(at, ErrorKind::Syntax("unexpected character"))),
+        };
+        Ok(Token { kind, at })
+    }
+    fn digits(&mut self, at: usize) -> Result<()> {
+        while matches!(self.source.as_bytes().get(self.pos), Some(b'0'..=b'9')) {
+            self.pos += 1;
+            if self.pos - at > 128 {
+                return Err(err(at, ErrorKind::LimitExceeded("numeric token bytes")));
+            }
+        }
+        Ok(())
+    }
+    fn peek(&mut self) -> Result<Token<'a>> {
+        if let Some(token) = self.look {
+            return Ok(token);
+        }
+        let token = self.lex()?;
+        self.look = Some(token);
+        Ok(token)
+    }
+    fn next(&mut self) -> Result<Token<'a>> {
+        let token = self.peek()?;
+        self.look = None;
+        Ok(token)
+    }
+    fn is(&mut self, kind: Kind<'a>) -> Result<bool> {
+        Ok(self.peek()?.kind == kind)
+    }
+    fn expect(&mut self, kind: Kind<'a>, message: &'static str) -> Result<()> {
+        let token = self.next()?;
+        if token.kind != kind {
+            return Err(err(token.at, ErrorKind::Syntax(message)));
+        }
+        Ok(())
+    }
+    fn symbol(&mut self, symbol: u8) -> Result<()> {
+        self.expect(Kind::Symbol(symbol), "expected punctuation")
+    }
+    fn word(&mut self, word: &'static str) -> Result<()> {
+        self.expect(Kind::Word(word), "expected keyword")
+    }
+    fn push<T>(&mut self, out: &mut Vec<T>, value: T) -> Result<()> {
+        self.budget.push(out, value, self.limits, self.pos)
+    }
+    fn string(&mut self) -> Result<String> {
+        let token = self.next()?;
+        let Kind::Str(raw) = token.kind else {
+            return Err(err(token.at, ErrorKind::Syntax("expected string")));
+        };
+        let mut out = String::new();
+        let mut chars = raw.chars();
+        while let Some(c) = chars.next() {
+            let c = if c == '\\' {
+                match chars.next() {
+                    Some('r') => '\r',
+                    Some('n') => '\n',
+                    Some('t') => '\t',
+                    Some('\'') => '\'',
+                    Some('"') => '"',
+                    Some('\\') => '\\',
+                    _ => return Err(err(token.at, ErrorKind::InvalidEscape)),
+                }
+            } else {
+                c
+            };
+            let n = out
+                .len()
+                .checked_add(c.len_utf8())
+                .ok_or_else(|| err(token.at, ErrorKind::CountOverflow))?;
+            if n > self.limits.max_string_bytes {
+                return Err(err(token.at, ErrorKind::LimitExceeded("string bytes")));
+            }
+            if n > out.capacity() {
+                let cap = n
+                    .max(out.capacity().saturating_mul(2))
+                    .min(self.limits.max_string_bytes);
+                self.budget
+                    .bytes(cap - out.capacity(), self.limits, token.at)?;
+                out.try_reserve_exact(cap - out.len())
+                    .map_err(|_| err(token.at, ErrorKind::Allocation))?;
+            }
+            out.push(c);
+        }
+        Ok(out)
+    }
+    fn integer(&mut self) -> Result<u32> {
+        let token = self.next()?;
+        let Kind::Number(raw, true) = token.kind else {
+            return Err(err(
+                token.at,
+                ErrorKind::Syntax("expected nonnegative integer"),
+            ));
+        };
+        let n = raw
+            .parse::<i32>()
+            .map_err(|_| err(token.at, ErrorKind::InvalidNumber))?;
+        u32::try_from(n).map_err(|_| err(token.at, ErrorKind::InvalidNumber))
+    }
+    fn float(&mut self) -> Result<f32> {
+        let token = self.next()?;
+        let Kind::Number(raw, _) = token.kind else {
+            return Err(err(token.at, ErrorKind::Syntax("expected number")));
+        };
+        let n = raw
+            .parse::<f32>()
+            .map_err(|_| err(token.at, ErrorKind::InvalidNumber))?;
+        if !n.is_finite() {
+            return Err(err(token.at, ErrorKind::NonFinite));
+        }
+        Ok(n)
+    }
+    fn vector(&mut self) -> Result<Vec3> {
+        Ok([self.float()?, self.float()?, self.float()?])
+    }
+    fn vectors(&mut self) -> Result<Vec<Vec3>> {
+        self.symbol(b'[')?;
+        let mut out = Vec::new();
+        if !self.is(Kind::Symbol(b']'))? {
+            loop {
+                let v = self.vector()?;
+                self.push(&mut out, v)?;
+                if !self.is(Kind::Symbol(b','))? {
+                    break;
+                }
+                self.next()?;
+            }
+        }
+        self.symbol(b']')?;
+        Ok(out)
+    }
+    fn names(&mut self) -> Result<Vec<String>> {
+        self.symbol(b'[')?;
+        let mut out = Vec::new();
+        if !self.is(Kind::Symbol(b']'))? {
+            loop {
+                let s = self.string()?;
+                self.push(&mut out, s)?;
+                if !self.is(Kind::Symbol(b','))? {
+                    break;
+                }
+                self.next()?;
+            }
+        }
+        self.symbol(b']')?;
+        unique_names(&out, &mut self.budget, self.limits, self.pos)?;
+        Ok(out)
+    }
+    fn properties<T>(
+        &mut self,
+        key: &'static str,
+        names: usize,
+        mut value: impl FnMut(&mut Self) -> Result<T>,
+    ) -> Result<Vec<Property<T>>> {
+        let mut out = Vec::new();
+        while self.is(Kind::Word(key))? {
+            self.next()?;
+            let at = self.pos;
+            let index = self.integer()?;
+            if index as usize >= names {
+                return Err(err(at, ErrorKind::PropertyIndex(index)));
+            }
+            if out.len() >= names {
+                return Err(err(at, ErrorKind::DuplicateProperty(index)));
+            }
+            let entry = Property {
+                index,
+                value: value(self)?,
+            };
+            self.push(&mut out, entry)?;
+        }
+        out.sort_unstable_by_key(|p| p.index);
+        for pair in out.windows(2) {
+            if pair[0].index == pair[1].index {
+                return Err(err(self.pos, ErrorKind::DuplicateProperty(pair[0].index)));
+            }
+        }
+        Ok(out)
+    }
+    fn uv(&mut self) -> Result<Uv> {
+        self.symbol(b'(')?;
+        let u = self.vector()?;
+        let u_scale = self.float()?;
+        let u_shift = self.float()?;
+        self.symbol(b',')?;
+        let v = self.vector()?;
+        let v_scale = self.float()?;
+        let v_shift = self.float()?;
+        self.symbol(b')')?;
+        Ok(Uv {
+            u,
+            v,
+            u_scale,
+            u_shift,
+            v_scale,
+            v_shift,
+        })
+    }
+    fn brush(&mut self, world: &World) -> Result<Brush> {
+        self.word("brush")?;
+        self.symbol(b'(')?;
+        let mut planes = Vec::new();
+        while self.is(Kind::Word("plane"))? {
+            self.next()?;
+            self.symbol(b'(')?;
+            let p0 = self.vector()?;
+            self.symbol(b',')?;
+            let u = self.vector()?;
+            self.symbol(b',')?;
+            let v = self.vector()?;
+            let strings = self.properties("s", world.string_properties.len(), Self::string)?;
+            let uv = self.properties("uv", world.uv_properties.len(), Self::uv)?;
+            let polygon = if self.is(Kind::Word("polygon"))? {
+                self.next()?;
+                Some(self.vectors()?)
+            } else {
+                None
+            };
+            if polygon.is_some() != world.computed {
+                return Err(err(self.pos, ErrorKind::InconsistentComputedData));
+            }
+            self.symbol(b')')?;
+            self.push(
+                &mut planes,
+                Plane {
+                    p0,
+                    u,
+                    v,
+                    strings,
+                    uv,
+                    polygon,
+                },
+            )?;
+        }
+        self.symbol(b')')?;
+        Ok(Brush { planes })
+    }
+    fn patch(&mut self, computed: bool) -> Result<Patch9> {
+        self.word("patch9")?;
+        self.symbol(b'(')?;
+        let au = self.integer()?;
+        let av = self.integer()?;
+        let qu = self.integer()?;
+        let qv = self.integer()?;
+        self.word("anchors")?;
+        let anchors = self.vectors()?;
+        if anchors.len() != product(au as usize, av as usize, self.pos)? {
+            return Err(err(self.pos, ErrorKind::InvalidPatchLength));
+        }
+        let data = if self.is(Kind::Word("points"))? {
+            self.next()?;
+            let points = self.vectors()?;
+            self.word("normals")?;
+            let normals = self.vectors()?;
+            let n = grid(au, av, qu, qv, self.pos)?;
+            if points.len() != n || normals.len() != n {
+                return Err(err(self.pos, ErrorKind::InvalidPatchLength));
+            }
+            Some(PatchComputed { points, normals })
+        } else {
+            None
+        };
+        if data.is_some() != computed {
+            return Err(err(self.pos, ErrorKind::InconsistentComputedData));
+        }
+        self.symbol(b')')?;
+        Ok(Patch9 {
+            anchors_u: au,
+            anchors_v: av,
+            quads_u: qu,
+            quads_v: qv,
+            anchors,
+            computed: data,
+        })
+    }
+}
+/// Parse one complete TXT world with the latest grammar (including the older
+/// property-free subset). Strict UTF-8, optional leading BOM, bounded ownership.
+pub fn decode(bytes: &[u8], limits: &Limits) -> Result<World> {
+    if bytes.len() > limits.max_bytes {
+        return Err(err(0, ErrorKind::LimitExceeded("file bytes")));
+    }
+    let source =
+        std::str::from_utf8(bytes).map_err(|e| err(e.valid_up_to(), ErrorKind::InvalidUtf8))?;
+    let mut p = Parser {
+        source,
+        pos: if source.starts_with('\u{feff}') { 3 } else { 0 },
+        look: None,
+        limits,
+        budget: Budget::default(),
+    };
+    p.word("world")?;
+    p.symbol(b'(')?;
+    p.word("computedFeatures")?;
+    let computed = match p.next()? {
+        Token {
+            kind: Kind::Word("true"),
+            ..
+        } => true,
+        Token {
+            kind: Kind::Word("false"),
+            ..
+        } => false,
+        t => return Err(err(t.at, ErrorKind::Syntax("expected boolean"))),
+    };
+    let mut world = World {
+        computed,
+        ..World::default()
+    };
+    if p.is(Kind::Word("stringProperties"))? {
+        p.next()?;
+        world.string_properties = p.names()?;
+    }
+    if p.is(Kind::Word("uvProperties"))? {
+        p.next()?;
+        world.uv_properties = p.names()?;
+    }
+    loop {
+        match p.peek()?.kind {
+            Kind::Word("brush") => {
+                let b = p.brush(&world)?;
+                p.push(&mut world.brushes, b)?;
+            }
+            Kind::Word("patch9") => {
+                let patch = p.patch(computed)?;
+                p.push(&mut world.patches, patch)?;
+            }
+            _ => break,
+        }
+    }
+    p.symbol(b')')?;
+    p.expect(Kind::End, "expected end of input")?;
+    Ok(world)
+}

crates/mb3-txt/src/tests.rs

@@ -0,0 +1,317 @@
+use super::*;
+use mb3_dat::World;
+use std::io::{Cursor, Read, Write};
+
+fn parse(s: &str) -> World {
+    decode(s.as_bytes(), &Limits::default()).unwrap()
+}
+fn rich() -> World {
+    parse(
+        "world(computedFeatures true stringProperties[\"unused\",\"name\"] uvProperties[\"uv\"] brush(plane(1 -0 3,4 5 6,7 8 9 s 1 \"é\\n\\t\\r\\'\\\"\\\\\" uv 0 (1 2 3 4 5,6 7 8 9 10) polygon[0 0 0,1 0 0,0 1 0])) patch9(1 1 0 0 anchors[1 2 3] points[4 5 6] normals[0 1 0]))",
+    )
+}
+#[test]
+fn canonical_semantics_unicode_and_bits() {
+    let w = rich();
+    let data = encode(&w, &Limits::default()).unwrap();
+    assert!(data.starts_with(b"\xef\xbb\xbf"));
+    let decoded = decode(&data, &Limits::default()).unwrap();
+    assert_eq!(decoded, w);
+    assert_eq!(
+        decoded.brushes[0].planes[0].p0[1].to_bits(),
+        (-0.0f32).to_bits()
+    );
+    assert_eq!(encode(&decoded, &Limits::default()).unwrap(), data);
+}
+#[test]
+fn old_subset_comments_and_signed_numbers() {
+    let w = parse(
+        "/*before*/world(// bool\n computedFeatures false brush(plane(+1 .2 3e-1,1. 2E+2 -3,0 0 1)))//EOF",
+    );
+    assert_eq!(w.brushes[0].planes[0].p0, [1., 0.2, 0.3]);
+    assert_eq!(w.brushes[0].planes[0].u, [1., 200., -3.]);
+    assert_eq!(
+        parse("world(computedFeatures true)"),
+        World {
+            computed: true,
+            ..World::default()
+        }
+    );
+}
+#[test]
+fn all_proper_prefixes_fail() {
+    let data = encode(&rich(), &Limits::default()).unwrap();
+    // A newline is optional after the closing world; exclude that valid prefix.
+    for n in 0..data.len() - 1 {
+        assert!(
+            decode(&data[..n], &Limits::default()).is_err(),
+            "prefix {n}"
+        );
+    }
+}
+#[test]
+fn bad_lexical_inputs_are_rejected() {
+    for s in [
+        "",
+        "world(computedFeatures false) trailing",
+        "world(computedFeatures false) /*",
+        "world(computedFeatures false stringProperties[\"unterminated])",
+        "world(computedFeatures false stringProperties[\"\\x\"])",
+        "world(computedFeatures false stringProperties[\"'\"])",
+        "world(computedFeatures false stringProperties[\"\0\"])",
+        "world(computedFeatures false stringProperties[\"a\",])",
+        "world(computedFeatures FALSE)",
+        "world(computedFeatures false worlds())",
+    ] {
+        assert!(decode(s.as_bytes(), &Limits::default()).is_err(), "{s:?}");
+    }
+    assert!(
+        decode(
+            b"world(computedFeatures false stringProperties[\"\xff\"])",
+            &Limits::default()
+        )
+        .is_err()
+    );
+}
+#[test]
+fn numeric_grammar_and_ranges() {
+    for number in [
+        "NaN", "Infinity", "1e99", "1e", "1e+", "+", ".", "01", "00e1", "1f",
+    ] {
+        let s = format!("world(computedFeatures false brush(plane({number} 0 0,0 1 0,0 0 1)))");
+        assert!(
+            decode(s.as_bytes(), &Limits::default()).is_err(),
+            "{number}"
+        );
+    }
+    for ints in ["-1 0 0 0", "2147483648 0 0 0", "1.0 1 1 1", "1e0 1 1 1"] {
+        assert!(
+            decode(
+                format!("world(computedFeatures false patch9({ints} anchors[]))").as_bytes(),
+                &Limits::default()
+            )
+            .is_err()
+        );
+    }
+    let number = "1".repeat(129);
+    assert!(
+        decode(
+            format!("world(computedFeatures false brush(plane({number} 0 0,0 0 0,0 0 0)))")
+                .as_bytes(),
+            &Limits::default()
+        )
+        .is_err()
+    );
+}
+#[test]
+fn strict_computed_and_patch_lengths() {
+    for s in [
+        "world(computedFeatures true brush(plane(0 0 0,0 0 0,0 0 0)))",
+        "world(computedFeatures false brush(plane(0 0 0,0 0 0,0 0 0 polygon[])))",
+        "world(computedFeatures false patch9(3 3 2 2 anchors[]))",
+        "world(computedFeatures true patch9(0 0 0 0 anchors[]))",
+        "world(computedFeatures true patch9(0 0 0 0 anchors[] points[] normals[]))",
+        "world(computedFeatures false patch9(0 0 0 0 anchors[] points[0 0 0] normals[0 0 0]))",
+    ] {
+        assert!(decode(s.as_bytes(), &Limits::default()).is_err(), "{s}");
+    }
+    let mut w = rich();
+    w.patches[0].anchors.clear();
+    assert!(encode(&w, &Limits::default()).is_err());
+    w = rich();
+    w.patches[0].computed.as_mut().unwrap().normals.clear();
+    assert!(encode(&w, &Limits::default()).is_err());
+    w = rich();
+    w.brushes[0].planes[0].polygon = None;
+    assert!(encode(&w, &Limits::default()).is_err());
+}
+#[test]
+fn sparse_slots_and_names() {
+    let w = parse(
+        "world(computedFeatures false stringProperties[\"a\",\"b\"] brush(plane(0 0 0,0 0 0,0 0 0 s 1 \"\" s 0 \"a\")))",
+    );
+    assert_eq!(w.brushes[0].planes[0].strings[0].index, 0);
+    for s in [
+        "world(computedFeatures false stringProperties[\"p\",\"p\"])",
+        "world(computedFeatures false uvProperties[\"p\",\"p\"])",
+        "world(computedFeatures false stringProperties[\"p\"] brush(plane(0 0 0,0 0 0,0 0 0 s 0 \"a\" s 0 \"b\")))",
+        "world(computedFeatures false brush(plane(0 0 0,0 0 0,0 0 0 s 0 \"a\")))",
+    ] {
+        assert!(decode(s.as_bytes(), &Limits::default()).is_err());
+    }
+    let mut w = w;
+    w.brushes[0].planes[0].strings.reverse();
+    assert!(encode(&w, &Limits::default()).is_err());
+    let mut w = rich();
+    w.string_properties[1] = w.string_properties[0].clone();
+    assert!(encode(&w, &Limits::default()).is_err());
+}
+#[test]
+fn finite_float_extremes_roundtrip() {
+    let mut w = rich();
+    w.brushes[0].planes[0].p0 = [f32::MAX, f32::MIN_POSITIVE, f32::from_bits(1)];
+    assert_eq!(
+        decode(&encode(&w, &Limits::default()).unwrap(), &Limits::default()).unwrap(),
+        w
+    );
+    for f in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] {
+        w.brushes[0].planes[0].uv[0].value.v_shift = f;
+        assert!(encode(&w, &Limits::default()).is_err());
+    }
+    w = rich();
+    w.string_properties[0].push('\0');
+    assert!(encode(&w, &Limits::default()).is_err());
+}
+#[test]
+fn all_limits_and_stream_size() {
+    let w = rich();
+    let data = encode(&w, &Limits::default()).unwrap();
+    for l in [
+        Limits {
+            max_bytes: data.len() - 1,
+            ..Limits::default()
+        },
+        Limits {
+            max_items: 1,
+            ..Limits::default()
+        },
+        Limits {
+            max_string_bytes: 1,
+            ..Limits::default()
+        },
+    ] {
+        assert!(decode(&data, &l).is_err());
+        assert!(encode(&w, &l).is_err());
+    }
+    assert!(
+        decode(
+            &data,
+            &Limits {
+                max_owned_bytes: 1,
+                ..Limits::default()
+            }
+        )
+        .is_err()
+    );
+    let mut source = Cursor::new(&data);
+    assert!(
+        read(
+            &mut source,
+            &Limits {
+                max_bytes: 20,
+                ..Limits::default()
+            }
+        )
+        .is_err()
+    );
+    assert_eq!(source.position(), 21);
+    let mut target = vec![1, 2];
+    let mut bad = w;
+    bad.computed = false;
+    assert!(write(&mut target, &bad, &Limits::default()).is_err());
+    assert_eq!(target, [1, 2]);
+}
+#[test]
+fn string_limit_measures_decoded_utf8() {
+    let data = "world(computedFeatures false stringProperties[\"é\\n\"])";
+    let l = Limits {
+        max_string_bytes: 3,
+        ..Limits::default()
+    };
+    let w = decode(data.as_bytes(), &l).unwrap();
+    assert!(encode(&w, &l).is_ok());
+    assert!(
+        decode(
+            data.as_bytes(),
+            &Limits {
+                max_string_bytes: 2,
+                ..l
+            }
+        )
+        .is_err()
+    );
+}
+struct Choppy {
+    data: Cursor<Vec<u8>>,
+    interrupt: bool,
+}
+impl Read for Choppy {
+    fn read(&mut self, b: &mut [u8]) -> io::Result<usize> {
+        if self.interrupt {
+            self.interrupt = false;
+            return Err(io::ErrorKind::Interrupted.into());
+        }
+        let n = b.len().min(1);
+        self.data.read(&mut b[..n])
+    }
+}
+impl Write for Choppy {
+    fn write(&mut self, b: &[u8]) -> io::Result<usize> {
+        if self.interrupt {
+            self.interrupt = false;
+            return Err(io::ErrorKind::Interrupted.into());
+        }
+        self.data.write(&b[..b.len().min(1)])
+    }
+    fn flush(&mut self) -> io::Result<()> {
+        Ok(())
+    }
+}
+#[test]
+fn short_io_interruptions_and_errors() {
+    let w = rich();
+    let data = encode(&w, &Limits::default()).unwrap();
+    assert_eq!(
+        read(
+            Choppy {
+                data: Cursor::new(data.clone()),
+                interrupt: true
+            },
+            &Limits::default()
+        )
+        .unwrap(),
+        w
+    );
+    let mut target = Choppy {
+        data: Cursor::new(Vec::new()),
+        interrupt: true,
+    };
+    write(&mut target, &w, &Limits::default()).unwrap();
+    assert_eq!(target.data.into_inner(), data);
+    assert!(matches!(
+        write([0u8; 0].as_mut_slice(), &w, &Limits::default())
+            .unwrap_err()
+            .kind,
+        ErrorKind::Io(_)
+    ));
+}
+#[test]
+fn bounded_mutations_and_no_recursion() {
+    let l = Limits {
+        max_bytes: 4096,
+        max_items: 256,
+        max_string_bytes: 64,
+        max_owned_bytes: 32768,
+    };
+    let seed = encode(&rich(), &l).unwrap();
+    let mut state = 0x12ab34cdu32;
+    for i in 0..3000 {
+        let mut data = seed.clone();
+        for _ in 0..1 + i % 7 {
+            state = state.wrapping_mul(1664525).wrapping_add(1013904223);
+            let at = state as usize % data.len();
+            data[at] ^= (state >> 24) as u8;
+        }
+        if let Ok(w) = decode(&data, &l) {
+            let canonical = encode(&w, &l).unwrap();
+            assert_eq!(decode(&canonical, &l).unwrap(), w);
+        }
+    }
+    assert!(
+        decode(
+            format!("world(computedFeatures false {} )", "brush(".repeat(1000)).as_bytes(),
+            &Limits::default()
+        )
+        .is_err()
+    );
+}

crates/mb3-txt/src/writer.rs

@@ -0,0 +1,244 @@
+use super::*;
+use mb3_dat::{Brush, Patch9, Property, Uv, Vec3, World};
+use std::fmt::Write as _;
+
+struct Number {
+    bytes: [u8; 128],
+    len: usize,
+}
+impl fmt::Write for Number {
+    fn write_str(&mut self, s: &str) -> fmt::Result {
+        if s.len() > self.bytes.len() - self.len {
+            return Err(fmt::Error);
+        }
+        self.bytes[self.len..self.len + s.len()].copy_from_slice(s.as_bytes());
+        self.len += s.len();
+        Ok(())
+    }
+}
+struct Encoder<'a> {
+    out: Vec<u8>,
+    limits: &'a Limits,
+    budget: Budget,
+}
+impl Encoder<'_> {
+    fn bytes(&mut self, s: &[u8]) -> Result<()> {
+        append(&mut self.out, s, self.limits.max_bytes)
+    }
+    fn text(&mut self, s: &str) -> Result<()> {
+        self.bytes(s.as_bytes())
+    }
+    fn items(&mut self, n: usize) -> Result<()> {
+        self.budget.items(n, self.limits, self.out.len())
+    }
+    fn integer(&mut self, n: u32) -> Result<()> {
+        if n > i32::MAX as u32 {
+            return Err(err(self.out.len(), ErrorKind::CountOverflow));
+        }
+        let mut buf = Number {
+            bytes: [0; 128],
+            len: 0,
+        };
+        write!(&mut buf, "{n}").map_err(|_| err(self.out.len(), ErrorKind::CountOverflow))?;
+        self.bytes(&buf.bytes[..buf.len])
+    }
+    fn float(&mut self, n: f32) -> Result<()> {
+        if !n.is_finite() {
+            return Err(err(self.out.len(), ErrorKind::NonFinite));
+        }
+        let mut buf = Number {
+            bytes: [0; 128],
+            len: 0,
+        };
+        write!(&mut buf, "{n}").map_err(|_| err(self.out.len(), ErrorKind::CountOverflow))?;
+        self.bytes(&buf.bytes[..buf.len])
+    }
+    fn vector(&mut self, v: &Vec3) -> Result<()> {
+        self.float(v[0])?;
+        self.text(" ")?;
+        self.float(v[1])?;
+        self.text(" ")?;
+        self.float(v[2])
+    }
+    fn vectors(&mut self, values: &[Vec3]) -> Result<()> {
+        self.items(values.len())?;
+        self.text("[")?;
+        for (i, v) in values.iter().enumerate() {
+            if i != 0 {
+                self.text(", ")?;
+            }
+            self.vector(v)?;
+        }
+        self.text("]")
+    }
+    fn string(&mut self, s: &str) -> Result<()> {
+        if s.len() > self.limits.max_string_bytes {
+            return Err(err(
+                self.out.len(),
+                ErrorKind::LimitExceeded("string bytes"),
+            ));
+        }
+        self.text("\"")?;
+        for c in s.chars() {
+            match c {
+                '\0' => return Err(err(self.out.len(), ErrorKind::EmbeddedNul)),
+                '\r' => self.text("\\r")?,
+                '\n' => self.text("\\n")?,
+                '\t' => self.text("\\t")?,
+                '\'' => self.text("\\'")?,
+                '"' => self.text("\\\"")?,
+                '\\' => self.text("\\\\")?,
+                _ => {
+                    let mut buf = [0; 4];
+                    self.text(c.encode_utf8(&mut buf))?;
+                }
+            }
+        }
+        self.text("\"")
+    }
+    fn names(&mut self, names: &[String], key: &str) -> Result<()> {
+        self.items(names.len())?;
+        unique_names(names, &mut self.budget, self.limits, self.out.len())?;
+        if names.is_empty() {
+            return Ok(());
+        }
+        self.text(key)?;
+        self.text(" [")?;
+        for (i, s) in names.iter().enumerate() {
+            if i != 0 {
+                self.text(", ")?;
+            }
+            self.string(s)?;
+        }
+        self.text("]\n")
+    }
+    fn properties<T>(
+        &mut self,
+        values: &[Property<T>],
+        names: usize,
+        key: &str,
+        mut value: impl FnMut(&mut Self, &T) -> Result<()>,
+    ) -> Result<()> {
+        self.items(values.len())?;
+        let mut previous = None;
+        for p in values {
+            if p.index as usize >= names {
+                return Err(err(self.out.len(), ErrorKind::PropertyIndex(p.index)));
+            }
+            if previous == Some(p.index) {
+                return Err(err(self.out.len(), ErrorKind::DuplicateProperty(p.index)));
+            }
+            if previous.is_some_and(|n| n > p.index) {
+                return Err(err(self.out.len(), ErrorKind::UnsortedProperties));
+            }
+            previous = Some(p.index);
+            self.text(key)?;
+            self.integer(p.index)?;
+            self.text(" ")?;
+            value(self, &p.value)?;
+        }
+        Ok(())
+    }
+    fn uv(&mut self, uv: &Uv) -> Result<()> {
+        self.text("(")?;
+        self.vector(&uv.u)?;
+        self.text(" ")?;
+        self.float(uv.u_scale)?;
+        self.text(" ")?;
+        self.float(uv.u_shift)?;
+        self.text(", ")?;
+        self.vector(&uv.v)?;
+        self.text(" ")?;
+        self.float(uv.v_scale)?;
+        self.text(" ")?;
+        self.float(uv.v_shift)?;
+        self.text(")")
+    }
+    fn brush(&mut self, brush: &Brush, world: &World) -> Result<()> {
+        self.items(brush.planes.len())?;
+        self.text("brush(\n")?;
+        for p in &brush.planes {
+            if p.polygon.is_some() != world.computed {
+                return Err(err(self.out.len(), ErrorKind::InconsistentComputedData));
+            }
+            self.text("plane(")?;
+            self.vector(&p.p0)?;
+            self.text(", ")?;
+            self.vector(&p.u)?;
+            self.text(", ")?;
+            self.vector(&p.v)?;
+            self.properties(&p.strings, world.string_properties.len(), " s ", |e, s| {
+                e.string(s)
+            })?;
+            self.properties(&p.uv, world.uv_properties.len(), " uv ", Self::uv)?;
+            if let Some(polygon) = &p.polygon {
+                self.text(" polygon")?;
+                self.vectors(polygon)?;
+            }
+            self.text(")\n")?;
+        }
+        self.text(")\n")
+    }
+    fn patch(&mut self, p: &Patch9, computed: bool) -> Result<()> {
+        if p.computed.is_some() != computed {
+            return Err(err(self.out.len(), ErrorKind::InconsistentComputedData));
+        }
+        if p.anchors.len() != product(p.anchors_u as usize, p.anchors_v as usize, self.out.len())? {
+            return Err(err(self.out.len(), ErrorKind::InvalidPatchLength));
+        }
+        if let Some(data) = &p.computed {
+            let n = grid(
+                p.anchors_u,
+                p.anchors_v,
+                p.quads_u,
+                p.quads_v,
+                self.out.len(),
+            )?;
+            if data.points.len() != n || data.normals.len() != n {
+                return Err(err(self.out.len(), ErrorKind::InvalidPatchLength));
+            }
+        }
+        self.text("patch9(\n")?;
+        for (i, n) in [p.anchors_u, p.anchors_v, p.quads_u, p.quads_v]
+            .iter()
+            .enumerate()
+        {
+            if i != 0 {
+                self.text(" ")?;
+            }
+            self.integer(*n)?;
+        }
+        self.text("\nanchors")?;
+        self.vectors(&p.anchors)?;
+        if let Some(data) = &p.computed {
+            self.text("\npoints")?;
+            self.vectors(&data.points)?;
+            self.text("\nnormals")?;
+            self.vectors(&data.normals)?;
+        }
+        self.text("\n)\n")
+    }
+}
+/// Canonical, BOM-prefixed UTF-8, LF, shortest round-tripping f32 decimals.
+/// Structural validation finishes before output is returned. No optimization.
+pub fn encode(world: &World, limits: &Limits) -> Result<Vec<u8>> {
+    let mut e = Encoder {
+        out: Vec::new(),
+        limits,
+        budget: Budget::default(),
+    };
+    e.bytes(b"\xef\xbb\xbfworld(\ncomputedFeatures ")?;
+    e.text(if world.computed { "true\n" } else { "false\n" })?;
+    e.names(&world.string_properties, "stringProperties")?;
+    e.names(&world.uv_properties, "uvProperties")?;
+    e.items(world.brushes.len())?;
+    for brush in &world.brushes {
+        e.brush(brush, world)?;
+    }
+    e.items(world.patches.len())?;
+    for patch in &world.patches {
+        e.patch(patch, world.computed)?;
+    }
+    e.text(")\n")?;
+    Ok(e.out)
+}

crates/mb3-txt/tests/converter.rs

@@ -0,0 +1,166 @@
+//! Hydrated E02 fixtures are mandatory; missing files never skip validation.
+use mb3_dat::{Document, Limits, Version};
+use std::{fs, path::PathBuf};
+fn root() -> PathBuf {
+    std::env::var_os("NANOBRUSH_CONVERTER_FIXTURES")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| {
+            PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../assets/analysis/converter/probes")
+        })
+}
+fn file(build: &str, case: &str, name: &str) -> Vec<u8> {
+    let p = root().join(build).join(case).join(name);
+    fs::read(&p).unwrap_or_else(|e| panic!("hydrate E02 assets; {}: {e}", p.display()))
+}
+#[test]
+fn all_58_dat_fixtures_through_txt_preserve_exact_dat_bytes() {
+    let mut n = 0;
+    for build in ["2015-10-03", "2016-03-10-c"] {
+        for entry in fs::read_dir(root().join(build)).expect("hydrate E02 fixtures") {
+            let path = entry.unwrap().path().join("output.mb3dat");
+            if !path.exists() {
+                continue;
+            }
+            let original = fs::read(&path).unwrap();
+            let d = mb3_dat::decode(&original, &Limits::default()).unwrap();
+            let text = mb3_txt::encode(&d.world, &Limits::default()).unwrap();
+            let world = mb3_txt::decode(&text, &Limits::default()).unwrap();
+            assert_eq!(world, d.world, "{}", path.display());
+            assert_eq!(
+                mb3_dat::encode(
+                    &Document {
+                        version: d.version,
+                        world
+                    },
+                    &Limits::default()
+                )
+                .unwrap(),
+                original,
+                "{}",
+                path.display()
+            );
+            n += 1;
+        }
+    }
+    assert_eq!(n, 58);
+}
+#[test]
+fn seven_converter_txt_outputs_canonicalize_stably() {
+    let mut n = 0;
+    for build in ["2015-10-03", "2016-03-10-c"] {
+        for entry in fs::read_dir(root().join(build)).unwrap() {
+            let path = entry.unwrap().path().join("output.mb3txt");
+            if !path.exists() {
+                continue;
+            }
+            let source = fs::read(&path).unwrap();
+            let world = mb3_txt::decode(&source, &Limits::default()).unwrap();
+            let canonical = mb3_txt::encode(&world, &Limits::default()).unwrap();
+            assert_eq!(
+                mb3_txt::decode(&canonical, &Limits::default()).unwrap(),
+                world
+            );
+            assert_eq!(
+                mb3_txt::encode(
+                    &mb3_txt::decode(&canonical, &Limits::default()).unwrap(),
+                    &Limits::default()
+                )
+                .unwrap(),
+                canonical
+            );
+            n += 1;
+        }
+    }
+    assert_eq!(n, 7);
+}
+#[test]
+fn sixteen_txt_to_dat_fixture_pairs_match_without_legacy_losses() {
+    let mut n = 0;
+    for (build, version) in [
+        ("2015-10-03", Version::V201501280),
+        ("2016-03-10-c", Version::V201512200),
+    ] {
+        let mut cases = vec![
+            "empty-false",
+            "empty-true",
+            "plane-to-dat",
+            "computed-plane",
+            "patch-false",
+            "patch-true",
+            "overwrite-dat",
+        ];
+        if build.starts_with("2016") {
+            cases.extend(["properties-255", "properties-256"]);
+        }
+        for case in cases {
+            let world =
+                mb3_txt::decode(&file(build, case, "input.mb3txt"), &Limits::default()).unwrap();
+            assert_eq!(
+                mb3_dat::encode(&Document { version, world }, &Limits::default()).unwrap(),
+                file(build, case, "output.mb3dat"),
+                "{build}/{case}"
+            );
+            n += 1;
+        }
+    }
+    assert_eq!(n, 16);
+}
+#[test]
+fn rejects_nine_invalid_or_silently_lossy_txt_inputs() {
+    let mut n = 0;
+    for build in ["2015-10-03", "2016-03-10-c"] {
+        let mut cases = vec![
+            "computed-missing-polygon",
+            "false-ignores-polygon",
+            "bad-syntax",
+        ];
+        if build.starts_with("2016") {
+            cases.extend(["duplicate-name", "duplicate-slot", "bad-slot"]);
+        }
+        for case in cases {
+            assert!(
+                mb3_txt::decode(&file(build, case, "input.mb3txt"), &Limits::default()).is_err(),
+                "{build}/{case}"
+            );
+            n += 1;
+        }
+    }
+    assert_eq!(n, 9);
+}
+#[test]
+fn explicit_encoding_and_optimization_differences() {
+    let b = "2016-03-10-c";
+    let world = mb3_txt::decode(
+        &file(b, "properties-to-dat", "input.mb3txt"),
+        &Limits::default(),
+    )
+    .unwrap();
+    assert_eq!(world.string_properties, ["unused", "rare", "common"]);
+    let reference = mb3_dat::decode(
+        &file(b, "properties-to-dat", "output.mb3dat"),
+        &Limits::default(),
+    )
+    .unwrap();
+    assert_eq!(reference.world.string_properties, ["common", "rare"]);
+    assert_eq!(
+        world.brushes[0].planes[0].strings[0].value,
+        reference.world.brushes[0].planes[0].strings[1].value
+    );
+    for case in ["utf8-bom-ascii-loss", "utf8-no-bom-mojibake"] {
+        let world = mb3_txt::decode(&file(b, case, "input.mb3txt"), &Limits::default()).unwrap();
+        assert_eq!(world.string_properties, ["é"]);
+        assert!(
+            mb3_dat::encode(
+                &Document {
+                    version: Version::V201512200,
+                    world: world.clone()
+                },
+                &Limits::default()
+            )
+            .is_err()
+        );
+        let text = mb3_txt::encode(&world, &Limits::default()).unwrap();
+        assert!(text.starts_with(b"\xef\xbb\xbf"));
+        assert_eq!(mb3_txt::decode(&text, &Limits::default()).unwrap(), world);
+    }
+}

crates/nanobrush-cli/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "nanobrush-cli"
+version = "0.1.0"
+description = "Headless MB3 TXT/DAT inspection, validation and conversion"
+edition.workspace = true
+rust-version.workspace = true
+publish = false
+
+[[bin]]
+name = "nanobrush"
+path = "src/main.rs"
+
+[dependencies]
+mb3-dat = { path = "../mb3-dat" }
+mb3-txt = { path = "../mb3-txt" }
+
+[lints]
+workspace = true

crates/nanobrush-cli/src/lib.rs

@@ -0,0 +1,363 @@
+//! Headless CLI; source-preserving conversion with atomic destination publication.
+use mb3_dat::{Document, Limits, Version, World};
+use std::ffi::OsString;
+use std::fmt;
+use std::fs::{self, File, OpenOptions};
+use std::io::{self, BufRead, BufReader, Write};
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+const HELP: &str = "nanobrush inspect INPUT [--from auto|txt|dat] [LIMITS]\nnanobrush validate INPUT [--from auto|txt|dat] [LIMITS]\nnanobrush convert INPUT OUTPUT --to txt|dat-201501280|dat-201512200 [--from auto|txt|dat] [--force] [LIMITS]\nLIMITS: --max-bytes N --max-items N --max-string-bytes N --max-owned-bytes N\nUse -- before positional paths beginning with a dash. TXT input is UTF-8; output has a BOM.\nExit: 0 success/help, 1 invalid data or I/O failure, 2 usage error.\n";
+#[derive(Debug)]
+pub struct Error {
+    pub usage: bool,
+    message: String,
+}
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.message)
+    }
+}
+impl std::error::Error for Error {}
+impl From<io::Error> for Error {
+    fn from(e: io::Error) -> Self {
+        fail(e.to_string())
+    }
+}
+fn fail(message: impl Into<String>) -> Error {
+    Error {
+        usage: false,
+        message: message.into(),
+    }
+}
+fn usage(message: impl Into<String>) -> Error {
+    Error {
+        usage: true,
+        message: message.into(),
+    }
+}
+type Result<T> = std::result::Result<T, Error>;
+#[derive(Clone, Copy)]
+enum InputFormat {
+    Auto,
+    Txt,
+    Dat,
+}
+#[derive(Clone, Copy)]
+enum To {
+    Txt,
+    Dat(Version),
+}
+struct Options {
+    command: String,
+    paths: Vec<PathBuf>,
+    from: InputFormat,
+    to: Option<To>,
+    force: bool,
+    limits: Limits,
+}
+fn parse(args: impl IntoIterator<Item = OsString>) -> Result<Option<Options>> {
+    let mut args = args.into_iter();
+    let command = args.next().ok_or_else(|| usage(HELP))?;
+    if command == "--help" || command == "-h" {
+        return Ok(None);
+    }
+    let command = command
+        .into_string()
+        .map_err(|_| usage("command must be UTF-8"))?;
+    if !matches!(command.as_str(), "inspect" | "validate" | "convert") {
+        return Err(usage("expected inspect, validate or convert; use --help"));
+    }
+    let mut options = Options {
+        command,
+        paths: Vec::new(),
+        from: InputFormat::Auto,
+        to: None,
+        force: false,
+        limits: Limits::default(),
+    };
+    let mut positional = false;
+    let mut seen = std::collections::HashSet::new();
+    while let Some(arg) = args.next() {
+        if !positional && arg == "--" {
+            positional = true;
+            continue;
+        }
+        if !positional && (arg == "--help" || arg == "-h") {
+            return Ok(None);
+        }
+        if !positional && arg.as_encoded_bytes().starts_with(b"-") {
+            let flag = arg.to_str().ok_or_else(|| usage("option must be UTF-8"))?;
+            if !seen.insert(flag.to_owned()) {
+                return Err(usage(format!("duplicate option {flag}")));
+            }
+            if flag == "--force" {
+                options.force = true;
+                continue;
+            }
+            if !matches!(
+                flag,
+                "--from"
+                    | "--to"
+                    | "--max-bytes"
+                    | "--max-items"
+                    | "--max-string-bytes"
+                    | "--max-owned-bytes"
+            ) {
+                return Err(usage(format!("unknown option {flag}")));
+            }
+            let value = args
+                .next()
+                .ok_or_else(|| usage(format!("missing value for {flag}")))?;
+            let value = value
+                .to_str()
+                .ok_or_else(|| usage("option value must be UTF-8"))?;
+            match flag {
+                "--from" => {
+                    options.from = match value {
+                        "auto" => InputFormat::Auto,
+                        "txt" => InputFormat::Txt,
+                        "dat" => InputFormat::Dat,
+                        _ => return Err(usage("--from requires auto, txt or dat")),
+                    }
+                }
+                "--to" => {
+                    options.to = Some(match value {
+                        "txt" => To::Txt,
+                        "dat-201501280" => To::Dat(Version::V201501280),
+                        "dat-201512200" => To::Dat(Version::V201512200),
+                        _ => {
+                            return Err(usage("--to requires txt, dat-201501280 or dat-201512200"));
+                        }
+                    })
+                }
+                _ => {
+                    if value.is_empty() || !value.bytes().all(|b| b.is_ascii_digit()) {
+                        return Err(usage("limits must be nonnegative decimal integers"));
+                    }
+                    let n = value
+                        .parse::<usize>()
+                        .map_err(|_| usage("limit outside platform usize range"))?;
+                    match flag {
+                        "--max-bytes" => options.limits.max_bytes = n,
+                        "--max-items" => options.limits.max_items = n,
+                        "--max-string-bytes" => options.limits.max_string_bytes = n,
+                        _ => options.limits.max_owned_bytes = n,
+                    }
+                }
+            }
+        } else {
+            options.paths.push(arg.into());
+        }
+    }
+    if options.command == "convert" {
+        if options.paths.len() != 2 || options.to.is_none() {
+            return Err(usage("convert requires INPUT OUTPUT --to FORMAT"));
+        }
+    } else if options.paths.len() != 1 || options.to.is_some() || options.force {
+        return Err(usage(
+            "inspect/validate require one INPUT and no --to/--force",
+        ));
+    }
+    Ok(Some(options))
+}
+struct Input {
+    world: World,
+    version: Option<Version>,
+}
+fn load(path: &Path, from: InputFormat, limits: &Limits) -> Result<Input> {
+    let mut file =
+        BufReader::new(File::open(path).map_err(|e| fail(format!("{}: {e}", path.display())))?);
+    let dat = match from {
+        InputFormat::Dat => true,
+        InputFormat::Txt => false,
+        InputFormat::Auto => file.fill_buf()?.starts_with(b"Mb3World"),
+    };
+    if dat {
+        let d =
+            mb3_dat::read(file, limits).map_err(|e| fail(format!("{}: {e}", path.display())))?;
+        Ok(Input {
+            world: d.world,
+            version: Some(d.version),
+        })
+    } else {
+        let world =
+            mb3_txt::read(file, limits).map_err(|e| fail(format!("{}: {e}", path.display())))?;
+        Ok(Input {
+            world,
+            version: None,
+        })
+    }
+}
+static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+struct Temp(PathBuf);
+impl Drop for Temp {
+    fn drop(&mut self) {
+        let _ = fs::remove_file(&self.0);
+    }
+}
+fn same_file(a: &fs::Metadata, b: &fs::Metadata) -> bool {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::MetadataExt;
+        a.dev() == b.dev() && a.ino() == b.ino()
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = (a, b);
+        false
+    }
+}
+fn save(input: &Path, output: &Path, bytes: &[u8], force: bool) -> Result<()> {
+    let parent = output
+        .parent()
+        .filter(|p| !p.as_os_str().is_empty())
+        .unwrap_or(Path::new("."));
+    let parent = fs::canonicalize(parent)?;
+    let name = output
+        .file_name()
+        .ok_or_else(|| fail("output requires a filename"))?;
+    let output = parent.join(name);
+    let input_meta = fs::metadata(input)?;
+    match fs::symlink_metadata(&output) {
+        Ok(meta) => {
+            if !meta.is_file() || meta.file_type().is_symlink() {
+                return Err(fail(
+                    "output must be a regular file, not a symlink or directory",
+                ));
+            }
+            if same_file(&input_meta, &meta)
+                || fs::canonicalize(input)? == fs::canonicalize(&output)?
+            {
+                return Err(fail(
+                    "input and output must be different files (including hard links)",
+                ));
+            }
+            if !force {
+                return Err(fail("output exists; use --force to replace it"));
+            }
+        }
+        Err(e) if e.kind() == io::ErrorKind::NotFound => (),
+        Err(e) => return Err(e.into()),
+    }
+    let mut created = None;
+    for _ in 0..100 {
+        let path = parent.join(format!(
+            ".nanobrush-{}-{}.tmp",
+            std::process::id(),
+            NEXT_TEMP.fetch_add(1, Ordering::Relaxed)
+        ));
+        let mut options = OpenOptions::new();
+        options.create_new(true).write(true);
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::OpenOptionsExt;
+            options.mode(0o600);
+        }
+        match options.open(&path) {
+            Ok(file) => {
+                created = Some((Temp(path), file));
+                break;
+            }
+            Err(e) if e.kind() == io::ErrorKind::AlreadyExists => (),
+            Err(e) => return Err(e.into()),
+        }
+    }
+    let (temp, mut file) =
+        created.ok_or_else(|| fail("cannot allocate a unique output temporary file"))?;
+    file.write_all(bytes)?;
+    file.sync_all()?;
+    drop(file);
+    publish(temp, &output, force)
+}
+fn publish(temp: Temp, output: &Path, force: bool) -> Result<()> {
+    if force {
+        fs::rename(&temp.0, output)?;
+    } else {
+        fs::hard_link(&temp.0, output)?;
+    }
+    Ok(())
+}
+/// Execute without exiting the process. Errors distinguish usage (exit 2) from
+/// data/I/O (exit 1). Arguments exclude the executable's name.
+pub fn run(args: impl IntoIterator<Item = OsString>, stdout: &mut dyn Write) -> Result<()> {
+    let Some(o) = parse(args)? else {
+        stdout.write_all(HELP.as_bytes())?;
+        return Ok(());
+    };
+    let input = load(&o.paths[0], o.from, &o.limits)?;
+    match o.command.as_str() {
+        "inspect" => {
+            let w = &input.world;
+            let planes: usize = w.brushes.iter().map(|b| b.planes.len()).sum();
+            let polygons: usize = w
+                .brushes
+                .iter()
+                .flat_map(|b| &b.planes)
+                .map(|p| p.polygon.as_ref().map_or(0, Vec::len))
+                .sum();
+            let anchors: usize = w.patches.iter().map(|p| p.anchors.len()).sum();
+            let points: usize = w
+                .patches
+                .iter()
+                .map(|p| p.computed.as_ref().map_or(0, |c| c.points.len()))
+                .sum();
+            let normals: usize = w
+                .patches
+                .iter()
+                .map(|p| p.computed.as_ref().map_or(0, |c| c.normals.len()))
+                .sum();
+            let version = input
+                .version
+                .map_or("null".into(), |v| (v as u32).to_string());
+            writeln!(
+                stdout,
+                "{{\"format\":\"{}\",\"dat_version\":{},\"computed\":{},\"brushes\":{},\"planes\":{},\"patches\":{},\"string_properties\":{},\"uv_properties\":{},\"polygon_vertices\":{},\"anchors\":{},\"points\":{},\"normals\":{}}}",
+                if input.version.is_some() {
+                    "mb3dat"
+                } else {
+                    "mb3txt"
+                },
+                version,
+                w.computed,
+                w.brushes.len(),
+                planes,
+                w.patches.len(),
+                w.string_properties.len(),
+                w.uv_properties.len(),
+                polygons,
+                anchors,
+                points,
+                normals
+            )?;
+        }
+        "validate" => writeln!(
+            stdout,
+            "valid: {}",
+            if input.version.is_some() {
+                "mb3dat"
+            } else {
+                "mb3txt"
+            }
+        )?,
+        _ => {
+            let bytes = match o.to.ok_or_else(|| usage("missing --to"))? {
+                To::Txt => {
+                    mb3_txt::encode(&input.world, &o.limits).map_err(|e| fail(e.to_string()))?
+                }
+                To::Dat(version) => mb3_dat::encode(
+                    &Document {
+                        version,
+                        world: input.world,
+                    },
+                    &o.limits,
+                )
+                .map_err(|e| fail(e.to_string()))?,
+            };
+            save(&o.paths[0], &o.paths[1], &bytes, o.force)?;
+        }
+    }
+    Ok(())
+}
+#[cfg(test)]
+mod tests;

crates/nanobrush-cli/src/main.rs

@@ -0,0 +1,9 @@
+fn main() -> std::process::ExitCode {
+    match nanobrush_cli::run(std::env::args_os().skip(1), &mut std::io::stdout().lock()) {
+        Ok(()) => std::process::ExitCode::SUCCESS,
+        Err(e) => {
+            eprintln!("{e}");
+            std::process::ExitCode::from(if e.usage { 2 } else { 1 })
+        }
+    }
+}

crates/nanobrush-cli/src/tests.rs

@@ -0,0 +1,198 @@
+use super::*;
+struct Dir(PathBuf);
+impl Dir {
+    fn new() -> Self {
+        for _ in 0..100 {
+            let p = std::env::temp_dir().join(format!(
+                "nanobrush-cli-test-{}-{}",
+                std::process::id(),
+                NEXT_TEMP.fetch_add(1, Ordering::Relaxed)
+            ));
+            match fs::create_dir(&p) {
+                Ok(()) => return Self(p),
+                Err(e) if e.kind() == io::ErrorKind::AlreadyExists => (),
+                Err(e) => panic!("{e}"),
+            }
+        }
+        panic!("temp dir collision")
+    }
+    fn file(&self, name: &str, bytes: &[u8]) -> PathBuf {
+        let p = self.0.join(name);
+        fs::write(&p, bytes).unwrap();
+        p
+    }
+}
+impl Drop for Dir {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.0);
+    }
+}
+fn call(args: &[&std::ffi::OsStr]) -> Result<Vec<u8>> {
+    let mut out = Vec::new();
+    run(args.iter().map(|s| s.to_os_string()), &mut out)?;
+    Ok(out)
+}
+const EMPTY: &[u8] = b"world(computedFeatures false)";
+#[test]
+fn inspect_validate_and_both_versions() {
+    let d = Dir::new();
+    let input = d.file("é space.txt", EMPTY);
+    let summary = call(&["inspect".as_ref(), input.as_os_str()]).unwrap();
+    assert!(
+        String::from_utf8(summary)
+            .unwrap()
+            .contains("\"dat_version\":null")
+    );
+    for format in ["dat-201501280", "dat-201512200"] {
+        let target = d.0.join(format);
+        call(&[
+            "convert".as_ref(),
+            input.as_os_str(),
+            target.as_os_str(),
+            "--to".as_ref(),
+            format.as_ref(),
+        ])
+        .unwrap();
+        assert!(mb3_dat::decode(&fs::read(&target).unwrap(), &Limits::default()).is_ok());
+        call(&["validate".as_ref(), target.as_os_str()]).unwrap();
+        let txt = d.0.join(format!("{format}.txt"));
+        call(&[
+            "convert".as_ref(),
+            target.as_os_str(),
+            txt.as_os_str(),
+            "--to".as_ref(),
+            "txt".as_ref(),
+        ])
+        .unwrap();
+        assert_eq!(
+            mb3_txt::decode(&fs::read(txt).unwrap(), &Limits::default()).unwrap(),
+            World::default()
+        );
+    }
+}
+#[test]
+fn usage_and_explicit_limits() {
+    for args in [
+        vec![],
+        vec!["x"],
+        vec!["inspect"],
+        vec!["convert", "in", "out"],
+        vec!["inspect", "in", "--force"],
+        vec!["inspect", "in", "--max-items", "-1"],
+        vec!["inspect", "in", "--from", "txt", "--from", "dat"],
+    ] {
+        let args: Vec<_> = args.iter().map(std::ffi::OsStr::new).collect();
+        assert!(call(&args).unwrap_err().usage);
+    }
+    assert!(!call(&["--help".as_ref()]).unwrap().is_empty());
+    let d = Dir::new();
+    let p = d.file("in", EMPTY);
+    assert!(
+        !call(&[
+            "validate".as_ref(),
+            p.as_os_str(),
+            "--max-bytes".as_ref(),
+            "1".as_ref()
+        ])
+        .unwrap_err()
+        .usage
+    );
+    assert!(
+        call(&[
+            "validate".as_ref(),
+            p.as_os_str(),
+            "--from".as_ref(),
+            "dat".as_ref()
+        ])
+        .is_err()
+    );
+}
+#[test]
+fn no_clobber_force_and_same_file_protection() {
+    let d = Dir::new();
+    let input = d.file("in", EMPTY);
+    let output = d.file("out", b"ORIGINAL");
+    assert!(save(&input, &output, b"NEW", false).is_err());
+    assert_eq!(fs::read(&output).unwrap(), b"ORIGINAL");
+    save(&input, &output, b"NEW", true).unwrap();
+    assert_eq!(fs::read(&output).unwrap(), b"NEW");
+    assert!(save(&input, &input, b"BAD", true).is_err());
+    let link = d.0.join("hardlink");
+    fs::hard_link(&input, &link).unwrap();
+    assert!(save(&input, &link, b"BAD", true).is_err());
+    assert_eq!(fs::read(input).unwrap(), EMPTY);
+    assert_eq!(fs::read_dir(&d.0).unwrap().count(), 3);
+}
+#[test]
+fn failed_validation_creates_no_output_or_temporary() {
+    let d = Dir::new();
+    let input = d.file(
+        "in",
+        b"world(computedFeatures false stringProperties[\"p\"])",
+    );
+    let output = d.0.join("out");
+    assert!(
+        call(&[
+            "convert".as_ref(),
+            input.as_os_str(),
+            output.as_os_str(),
+            "--to".as_ref(),
+            "dat-201501280".as_ref()
+        ])
+        .is_err()
+    );
+    assert!(!output.exists());
+    assert_eq!(fs::read_dir(&d.0).unwrap().count(), 1);
+}
+#[cfg(unix)]
+#[test]
+fn symlink_destinations_rejected() {
+    let d = Dir::new();
+    let input = d.file("in", EMPTY);
+    let target = d.file("target", b"ORIGINAL");
+    let link = d.0.join("link");
+    std::os::unix::fs::symlink(&target, &link).unwrap();
+    assert!(save(&input, &link, b"BAD", true).is_err());
+    assert_eq!(fs::read(target).unwrap(), b"ORIGINAL");
+}
+#[test]
+fn failed_publication_cleans_temporary_and_preserves_existing() {
+    let d = Dir::new();
+    let input = d.file("in", EMPTY);
+    let output = d.0.join("out");
+    fs::create_dir(&output).unwrap();
+    assert!(save(&input, &output, b"NEW", false).is_err());
+    assert_eq!(fs::read_dir(&d.0).unwrap().count(), 2);
+}
+
+#[test]
+fn publication_race_is_no_clobber_and_owned_temp_is_cleaned() {
+    let d = Dir::new();
+    let output = d.file("winner", b"EXISTING");
+    let path = d.file("staged", b"REPLACEMENT");
+    assert!(publish(Temp(path.clone()), &output, false).is_err());
+    assert!(!path.exists());
+    assert_eq!(fs::read(output).unwrap(), b"EXISTING");
+}
+#[test]
+fn invalid_conversion_with_force_keeps_existing_destination() {
+    let d = Dir::new();
+    let input = d.file(
+        "unicode.txt",
+        "world(computedFeatures false stringProperties[\"é\"])".as_bytes(),
+    );
+    let output = d.file("out.dat", b"KEEP");
+    assert!(
+        call(&[
+            "convert".as_ref(),
+            input.as_os_str(),
+            output.as_os_str(),
+            "--to".as_ref(),
+            "dat-201512200".as_ref(),
+            "--force".as_ref()
+        ])
+        .is_err()
+    );
+    assert_eq!(fs::read(output).unwrap(), b"KEEP");
+    assert_eq!(fs::read_dir(&d.0).unwrap().count(), 2);
+}

crates/nanobrush-cli/tests/fixtures.rs

@@ -0,0 +1,102 @@
+use std::{fs, path::PathBuf, process::Command};
+struct Dir(PathBuf);
+impl Dir {
+    fn new() -> Self {
+        let p = std::env::temp_dir().join(format!("nanobrush-cli-fixture-{}", std::process::id()));
+        fs::create_dir(&p).expect("unique process temp directory");
+        Self(p)
+    }
+}
+impl Drop for Dir {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.0);
+    }
+}
+fn root() -> PathBuf {
+    std::env::var_os("NANOBRUSH_CONVERTER_FIXTURES")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| {
+            PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../assets/analysis/converter/probes")
+        })
+}
+#[test]
+fn process_cli_inspects_validates_and_roundtrips_all_dat_outputs() {
+    let d = Dir::new();
+    let mut n = 0;
+    for build in ["2015-10-03", "2016-03-10-c"] {
+        for case in fs::read_dir(root().join(build)).expect("hydrate E02 assets") {
+            let input = case.unwrap().path().join("output.mb3dat");
+            if !input.exists() {
+                continue;
+            }
+            let txt = d.0.join(format!("{n}.txt"));
+            let dat = d.0.join(format!("{n}.dat"));
+            let result = Command::new(env!("CARGO_BIN_EXE_nanobrush"))
+                .arg("inspect")
+                .arg(&input)
+                .output()
+                .unwrap();
+            assert!(result.status.success(), "{:?}", result.stderr);
+            assert!(
+                String::from_utf8(result.stdout)
+                    .unwrap()
+                    .contains("\"format\":\"mb3dat\"")
+            );
+            let result = Command::new(env!("CARGO_BIN_EXE_nanobrush"))
+                .arg("convert")
+                .arg(&input)
+                .arg(&txt)
+                .args(["--to", "txt"])
+                .output()
+                .unwrap();
+            assert!(result.status.success(), "{:?}", result.stderr);
+            let result = Command::new(env!("CARGO_BIN_EXE_nanobrush"))
+                .arg("validate")
+                .arg(&txt)
+                .output()
+                .unwrap();
+            assert!(result.status.success(), "{:?}", result.stderr);
+            let result = Command::new(env!("CARGO_BIN_EXE_nanobrush"))
+                .arg("convert")
+                .arg(&txt)
+                .arg(&dat)
+                .args([
+                    "--to",
+                    if build.starts_with("2015") {
+                        "dat-201501280"
+                    } else {
+                        "dat-201512200"
+                    },
+                ])
+                .output()
+                .unwrap();
+            assert!(result.status.success(), "{:?}", result.stderr);
+            assert_eq!(fs::read(&input).unwrap(), fs::read(dat).unwrap());
+            n += 1;
+        }
+    }
+    assert_eq!(n, 58);
+}
+#[test]
+fn process_exit_codes_help_usage_and_bad_data() {
+    for (args, code) in [(vec!["--help"], 0), (vec![], 2), (vec!["unknown"], 2)] {
+        let r = Command::new(env!("CARGO_BIN_EXE_nanobrush"))
+            .args(args)
+            .output()
+            .unwrap();
+        assert_eq!(r.status.code(), Some(code));
+    }
+    let path = root().join("2016-03-10-c/bad-syntax/input.mb3txt");
+    let r = Command::new(env!("CARGO_BIN_EXE_nanobrush"))
+        .arg("validate")
+        .arg(path)
+        .output()
+        .unwrap();
+    assert_eq!(r.status.code(), Some(1));
+    assert!(r.stdout.is_empty());
+    assert!(
+        String::from_utf8(r.stderr)
+            .unwrap()
+            .contains("MB3 TXT at byte")
+    );
+}

docs/CLI.md

@@ -0,0 +1,56 @@
+# Native inspection, validation and conversion — F31
+
+The `nanobrush` executable is built from `crates/nanobrush-cli`, backed by the strict [TXT](RUST_TXT.md) and [DAT](RUST_DAT.md) libraries. It supports TXT and DAT versions 201501280/201512200. MAP/VMF/OBJ, geometry evaluation, user-interface replay and the editor application remain future work.
+
+Run from the repository:
+
+```sh
+nix run .#nanobrush -- --help
+nix run .#nanobrush -- inspect assets/analysis/converter/probes/2016-03-10-c/properties-to-dat/output.mb3dat
+nix run .#nanobrush -- validate path/to/world.mb3txt
+nix run .#nanobrush -- convert input.mb3txt output.mb3dat --to dat-201512200
+nix run .#nanobrush -- convert input.mb3dat output.mb3txt --to txt
+nix run .#nanobrush -- convert input.mb3txt old.mb3dat --to dat-201501280
+```
+
+Inside `nix develop`, `cargo run -p nanobrush-cli -- ...` uses the same commands. `cargo build -p nanobrush-cli --release --locked --offline` produces `target/release/nanobrush`; `nix build .#nanobrush --no-link` builds an asset-free native package. No original executable is invoked by these commands.
+
+## Interface
+
+```text
+nanobrush inspect INPUT [--from auto|txt|dat] [LIMITS]
+nanobrush validate INPUT [--from auto|txt|dat] [LIMITS]
+nanobrush convert INPUT OUTPUT --to txt|dat-201501280|dat-201512200
+    [--from auto|txt|dat] [--force] [LIMITS]
+```
+
+`inspect` strictly parses the complete document and prints a single JSON summary: source format, DAT version (null for versionless TXT), computed flag, brush/plane/patch counts, name-table sizes, contour vertices, anchors, points and normals. It does not dump string contents or every coordinate. `validate` uses the same parser and prints `valid: mb3txt` or `valid: mb3dat`; “valid” means structural codec validity, not a convex/usable editor world.
+
+`--from auto` checks the exact `Mb3World` magic; otherwise it attempts TXT. Suffixes do not dispatch formats. `--from dat` forces DAT header/version validation and `--from txt` forces the TXT parser. DAT output always requires its exact version token; there is no ambiguous `--to dat`. Format tokens are case-sensitive. Options may appear before/after positional paths; `--` ends option processing for paths beginning with a dash. Paths use OS strings, including spaces and Unicode; options/format tokens must be UTF-8. Unknown or repeated options fail.
+
+Exit codes are **0** for success/help, **1** for invalid documents or I/O/conversion failures, and **2** for usage errors. Diagnostics go to stderr; inspect/validate/help results go to stdout; successful conversion is quiet. This deliberately differs from the legacy converter's exit/log conventions. There is no log file to become stale. Broken stdout writes also return an I/O failure.
+
+Optional limits are nonnegative decimal platform `usize` values:
+
+```text
+--max-bytes N          # default 67108864, complete input/output
+--max-string-bytes N   # default 1048576, per decoded string
+--max-items N          # default 1000000, aggregate elements
+--max-owned-bytes N    # default 134217728, codec ownership/scratch accounting
+```
+
+The same limits apply to input parsing and output encoding; verbose TXT output can exceed the byte cap even if its DAT source fit. Auto detection uses a small buffered prefix; byte limits constrain codec buffers/file size, not blocking-I/O duration or process RSS. See codec documents for precise memory accounting. Lowering limits can intentionally reject otherwise structurally valid files. No automatic property optimization, dropped arrays, Unicode replacement, texture conversion or geometry synthesis takes place.
+
+## Publication and source protection
+
+Conversion parses and fully encodes before opening any destination temporary. Existing outputs are refused by default. `--force` authorizes replacement of a separate regular file; **same-file paths and hard links to the input are always rejected on macOS/Linux**, and output symlinks/directories are rejected. The input path is not written by conversion. Tests use disposable destinations and never choose reference-corpus paths as outputs.
+
+After validation, the CLI creates an exclusively owned temporary in the destination's existing parent directory, writes all bytes, syncs the file and closes it. New Unix files are private (mode 0600); replacement also takes that mode rather than inheriting old permissions. Default publication uses a same-directory hard link, atomically failing if the destination appeared concurrently. `--force` uses same-directory rename for atomic replacement. Temporary cleanup is best effort through an ownership guard, including error paths. Staged names are bounded to 100 exclusive-create attempts; no preexisting temporary is deleted.
+
+A filesystem without same-directory hard-link support returns an error for no-clobber publication rather than falling back to a partial visible output. File synchronization plus publication provides atomic visibility; directory metadata is not separately synced, so full power-loss durability is not claimed. The workflow assumes the caller's parent directory is trusted against hostile concurrent directory/symlink replacement. It is not an openat-based sandbox. Filesystem interruption/disk-failure matrices remain future work.
+
+Incompatible exports fail before publication: for example, Unicode TXT→ASCII DAT, property-bearing data→old DAT, DAT duplicate names→TXT, non-finite floats and inconsistent computed arrays. There is no silent drop or replacement option. Existing output bytes remain untouched on parser/encoder failure even with `--force`.
+
+## Tests
+
+Eight asset-free unit tests cover options, limits, inspection, both DAT directions, Unicode paths, overwrite/same-file/hard-link/symlink guards, validation before any output, preservation of existing destinations after incompatible conversion, exclusive publication races and temporary cleanup. Two process integration tests check documented exit streams/codes and invoke the real binary for inspect, DAT→TXT, validate and TXT→DAT against **all 58 DAT outputs** (232 successful commands), verifying exact final DAT bytes. Fixture tests fail when assets are missing. See [E04](experiments/txt-cli-2026-10-21.md).

docs/FINDINGS.md

@@ -157,3 +157,7 @@ The [plugin map](PLUGINS.md) accounts for 17 top-level plugins, five experimenta
 ## F29 — Native DAT serialization and compatibility profile
 
 The [Rust DAT codec](RUST_DAT.md) reads and writes both recovered layouts with checked counts/products, finite f32 and strict ASCII policies, bounded allocation/streaming and explicit rejection of ambiguous or incomplete data. It preserves property table order and absent-versus-empty values, refuses silent property loss on downgrade, and repairs the old signed-16 count range by choosing four bytes. All 58 captured DAT outputs round-trip exactly; intentional departures from legacy corruption, normalization and permissive parsing are documented separately from remaining editor/platform interoperability work.
+
+## F30/F31 — TXT serialization and native CLI
+
+The [TXT codec](RUST_TXT.md) implements the latest grammar and old property-free subset with bounded UTF-8 parsing, canonical BOM output, finite round-trip decimals and consistent computed arrays. The [CLI](CLI.md) inspects/validates and converts TXT plus both DAT versions, refusing silent loss and publishing validated outputs with explicit no-clobber/force behavior. [E04](experiments/txt-cli-2026-10-21.md) covers 58 exact DAT→TXT→DAT round trips through the real process, seven TXT outputs, 16 direct TXT→DAT pairs and nine invalid/lossy source rejections.

docs/FORMATS.md

@@ -80,3 +80,7 @@ Keymaps bind comma-separated key sequences to named or numeric commands; leading
 `brushes.shader` and `patch9s.shader` have `@vertex330` and `@fragment330` sections and a std140 matrix block; `grid.shader` has the same stage names and many grid/camera/snap uniforms. Host binding, compilation defines and complete matrix conventions remain unknown.
 
 `brushes.shader:92–106` uses face IDs 0/1/2/3 to distinguish unselected/main/set-1/set-2 visualization, including screen-space stripe patterns for auxiliary sets. `patch9s.shader:35–41` calculates a lighting value but writes the normal-color expression instead; translating the unused lighting expression as the visible shader would be incorrect. `brushes.shader:71–76` has a `WA_ATI` expression variant. Preserve observable output contracts separately from obsolete driver workarounds.
+
+## Native implementation extension — F30/F31
+
+The [strict TXT profile](RUST_TXT.md) and [native CLI](CLI.md) implement the recovered TXT and DAT structures with explicit compatibility differences and guarded publication. Source grammars and legacy converter behavior above remain historical evidence; native formatting, Unicode handling, computed consistency and loss refusal follow the documented F30/F31 profile. E04 adds fixture/process tests without claiming native-editor conformance.

docs/README.md

@@ -2,7 +2,7 @@
 
 Planning baseline: 2026-10-21. Project name: **Nanobrush**; reference software: **Microbrush 3 / Iteration X / Akula**.
 
-The intended result is a complete native Rust and Bevy reconstruction for macOS and Linux, with Solari lighting on supported hardware. The initial plan is complete, and source and managed-converter reverse engineering are underway. Repository setup and permanent extraction are now implemented; see [setup validation](SETUP.md). A converter oracle and research DAT inspector are implemented; safe Rust DAT readers/writers are implemented; other native codecs and the application remain future work.
+The intended result is a complete native Rust and Bevy reconstruction for macOS and Linux, with Solari lighting on supported hardware. The initial plan is complete, and source and managed-converter reverse engineering are underway. Repository setup and permanent extraction are now implemented; see [setup validation](SETUP.md). A converter oracle and research DAT inspector are implemented; safe Rust DAT/TXT readers/writers and a native inspection/conversion CLI are implemented; the other codecs and editor application remain future work.
 
 | Document | Purpose |
 | --- | --- |
@@ -20,6 +20,8 @@ The executed converter investigation adds [MB3 DAT layouts](MB3_DAT.md), [conver
 
 The first native format implementation is [the Rust DAT codec](RUST_DAT.md), covering both recovered versions with 58 exact converter-output round trips and an explicit strict compatibility profile; reproduction and limits are in [E03](experiments/rust-dat-2026-10-21.md).
 
+The [TXT codec](RUST_TXT.md) and [native CLI](CLI.md) now add UTF-8 serialization, inspection/validation, explicit DAT version conversion and guarded atomic publication. See [E04](experiments/txt-cli-2026-10-21.md) for the fixture matrix and compatibility policy.
+
 The asset boundary and extraction pipeline are established. Continue with the open P0 decisions and P3–P9 investigation tasks in `TODO.md`, using the source maps to design focused runtime experiments. Run the rendering capability spike early, independently of most editor research. Implement the rewrite in small end-to-end slices after the corresponding behavior is specified.
 
 ## Status vocabulary

docs/RUST_DAT.md

@@ -81,4 +81,4 @@ Validation:
 - **24** synthetic unit tests cover headers, every proper prefix of rich documents, binary ordering/duplicates, limits, string policies, computed consistency, all compact count boundaries through 65,536 (planes, names/UV slots, contours and patch dimensions), arithmetic overflow, finite extremes/non-finites, short/interrupted I/O, partial I/O errors, validation before writing, reserved bits and normalization of valid nonminimal widths. A deterministic 5,000-mutation test checks rejection or stable canonical round trips under tight limits; this is a smoke test, not coverage-guided fuzzing.
 - One compiled API doctest exercises an empty latest world.
 
-The `checks.<system>.rust` Nix derivation runs formatting, Clippy, 24 unit tests and the doctest from an asset-free source fileset. Full integration tests run separately against hydrated, verified captures. The setup derivation still runs the 52 Python regressions and code-tree storage checks. Only macOS ARM64 execution is validated in this stage; Linux/Intel execution, native editor interoperability, real user documents, long-running fuzzing, hostile-stream timeouts, atomic saves and the remaining text/MAP/VMF/OBJ codecs stay open. The declared Rust minimum is 1.85; the measured pinned toolchain is 1.99.0, not a separate minimum-version validation.
+The DAT crate’s 24 unit tests and one doctest run inside the asset-free `checks.<system>.rust` workspace check, which now includes TXT/CLI tests (44 unit tests and two doctests in E04). Formatting and Clippy cover all targets. Full integration tests run separately against hydrated, verified captures. The setup derivation still runs the 52 Python regressions and code-tree storage checks. Only macOS ARM64 execution is validated in this stage; Linux/Intel execution, native editor interoperability, real user documents, long-running fuzzing, hostile-stream timeouts, full crash-durability workflows and the remaining MAP/VMF/OBJ codecs stay open. TXT serialization and the headless CLI are now implemented in [F30](RUST_TXT.md)/[F31](CLI.md). The declared Rust minimum is 1.85; the measured pinned toolchain is 1.99.0, not a separate minimum-version validation.

docs/RUST_TXT.md

@@ -0,0 +1,55 @@
+# Rust MB3 TXT codec — F30
+
+`crates/mb3-txt` implements the supplied latest TXT grammar and the older property-free subset, using the existing `mb3_dat::World` model. TXT has no format-version header; the reader does not guess a historical release. The [CLI](CLI.md) converts TXT to either explicit DAT version. The only Cargo dependency is the local DAT model/codec crate; no third-party runtime packages, original converter, graphics stack or .NET runtime are required.
+
+## Public API
+
+```rust
+use mb3_dat::{Limits, World};
+let world = World::default();
+let bytes = mb3_txt::encode(&world, &Limits::default())?;
+assert_eq!(mb3_txt::decode(&bytes, &Limits::default())?, world);
+# Ok::<(), mb3_txt::Error>(())
+```
+
+`decode` / `encode` work on bytes; `read` / `write` support standard Rust I/O, short operations and `Interrupted`. Input must be UTF-8, with an optional leading BOM. Output is canonical **UTF-8 with a BOM**, LF line endings and shortest round-tripping finite f32 decimals. Invariant number formatting preserves finite f32 values, signed zero and subnormals. Comments, whitespace, original decimal spelling and brush/patch interleaving are not retained: the model stores brushes and patches separately, and the writer emits brushes first. Names, their original table order, unused names, property indices, empty versus absent values, and all explicit geometry arrays are retained.
+
+The parser accepts line/block comments, exact case-sensitive keywords, signed decimal integers, decimal-point/exponent floats, ordinary strings and the six supplied escape forms (`\r`, `\n`, `\t`, `\'`, `\"`, `\\`). Single quotes inside strings must be escaped, as in the supplied grammar. Strings may contain Unicode directly; general `\u`, hex and unknown escapes are rejected. Non-nested block comments terminate at the first closing delimiter. Line comments may end at EOF. Unknown fields, trailing objects/text, malformed punctuation and duplicate property names/slots are errors. Sparse slots can arrive out of index order and are sorted after parsing; writer input requires unique increasing indices.
+
+Plane tuples are P0/U/V, and UV tuples are axis/scale/shift pairs; the shared model names these fields to avoid confusing them with DAT's ten-float wire order. Dimension/slot integers must be nonnegative i32 values. Numeric tokens are capped at 128 bytes; integer tokens with leading zeroes are rejected rather than imitating possible token splitting by the historical lexer. Finite floats can have leading zeroes before a decimal point. No expression language, recursive nesting of brushes/worlds, general parser AST, geometry calculation or property optimization is introduced.
+
+Computed features are a consistency contract: each plane must have a polygon iff the world flag is true, and each patch must have both points/normals iff true. Anchor lengths must equal the dimensions' product; point and normal lengths must equal the recovered grid formula. Missing arrays and optional computed arrays under a false flag are rejected, instead of being synthesized, ignored or serialized incoherently. This validates structure, not convexity, geometric degeneracy, normal lengths, patch smoothness or editor usability. Zero/even dimensions remain representable with matching arrays.
+
+## Resource and error policy
+
+The API shares `mb3_dat::Limits`: 64 MiB input/output, 1 MiB per decoded UTF-8 string, 1,000,000 aggregate logical elements and 128 MiB requested decoder-owned storage by default. Limits are caller policy. Element counts cover names, parent records, sparse entries and vector-array elements. Geometric vector/string capacity growth and string payloads are charged before fallible reservations. Name uniqueness uses a fallibly allocated, budgeted index scratch array and sorting; duplicate slots sort once rather than repeatedly scanning earlier entries.
+
+Storage accounting includes decoder capacity and name-validation scratch requests, excluding the caller's input, allocator overhead and transient reallocations. `read` owns a separate bounded input buffer. Writer output has its own byte limit; writer-owned name-validation scratch uses the owned-storage limit, while the caller already owns the model. These are explicit accounting limits, not a precise RSS limit. There is no recursive input traversal. All numeric sums/products needed for array sizes are checked. String scanning never loops at EOF.
+
+`Error` carries a byte offset and typed `ErrorKind`, including syntax, UTF-8, escape, number, limits, allocation, property, computed-data and I/O errors. Byte positions include an input BOM. `write` validates and buffers before writing; it does not flush or make file writes atomic. Later I/O failure can leave a prefix; use the CLI's publication workflow or implement the equivalent at the caller.
+
+## Compatibility differences
+
+| Area | Recovered converter | Native TXT codec |
+| --- | --- | --- |
+| Encoding | Guesses Latin-1 without an initial UTF-8 marker; its BOM-less UTF-8 output can drift on reread | Strict UTF-8 input; BOM output protects Unicode when handed to the latest converter's documented detection path |
+| ASCII DAT conversion | Replaces non-ASCII with `?` | TXT retains Unicode; conversion to DAT fails explicitly, preserving source/destination |
+| Property tables | Latest CLI drops unused names and reorders by usage | Retains table order/unused names and index meaning |
+| Duplicate names | DAT can contain duplicate names, TXT loader rejects them | TXT reader/writer rejects them; DAT→TXT can therefore fail on an otherwise valid DAT document |
+| Computed flag | False can discard optional arrays; true can crash if arrays omitted | Requires arrays to agree with flag; never silently drops supplied data |
+| Patch lengths | TXT constructors can retain inconsistent arrays and emit invalid DAT | Checks exact array lengths with checked products |
+| Numbers | Invariant f32 parsing; runtime-dependent default printing, no explicit finite policy | Finite f32 only, shortest round-tripping output, 128-byte token limit, explicit integer bounds |
+| Historical syntax | 2015 grammar lacks names/strings/comments | Reader is the latest superset; property-free output omits tables and comments so it fits the old syntax |
+| Formatting | Historical layout/newlines/decimal output | Stable canonical layout and BOM; semantic TXT comparison, not byte-identical text |
+
+Native Unicode output follows the recovered grammar/encoding contract; a broad new Mono/Windows output-consumption campaign was not performed in this stage. The E02 Unicode inputs demonstrate the legacy encoding difference. There is no lossy conversion switch: callers must explicitly transform unsupported data before a DAT downgrade or Unicode-to-ASCII export.
+
+## Fixture validation (E04)
+
+- All **58 DAT output fixtures** decode, serialize to TXT, reparse and encode back to the same DAT version with **exact original bytes**. This includes UV/property ordering, computed brush/patch data, old/new hierarchy differences and compact widths.
+- All **seven converter TXT outputs** parse and stabilize under native canonicalization; text bytes intentionally differ.
+- **16 TXT-input/DAT-output pairs** match exact converter DAT bytes where the input did not undergo property optimization or character loss.
+- **Nine** invalid or silently lossy TXT source fixtures are rejected, including duplicate names/slots, bad indices, missing computed arrays, syntax errors and ignored polygons.
+- The property-optimization fixture retains `[unused, rare, common]`, while the original CLI emitted `[common, rare]`; Unicode source fixtures retain `é`, while DAT conversion refuses replacement and the historical BOM-less path drifted.
+
+Twelve unit tests cover lexer errors, comments, exponent syntax, escapes/UTF-8, finite extremes, signed zero, proper-prefix truncations, all resource policies, array consistency, streaming I/O, 3,000 bounded deterministic mutations and rejection of recursive-looking syntax. Five integration tests require hydrated E02 fixtures. Coverage-guided fuzzing, large real TXT files, explicit legacy Latin-1 recoding, native-editor interoperability and cross-platform execution remain open. See [E04](experiments/txt-cli-2026-10-21.md) for reproduction.

docs/TECHNICAL_DIRECTION.md

@@ -1,6 +1,6 @@
 # Proposed technical direction
 
-Storage, environment, hydration, and extraction are implemented; see [SETUP.md](SETUP.md). The dependency-free `mb3-dat` crate now implements the first native format slice ([compatibility profile](RUST_DAT.md)); the broader Rust/rendering/conversion boundaries below remain proposed and must be validated through the [TODO phases](TODO.md).
+Storage, environment, hydration, and extraction are implemented; see [SETUP.md](SETUP.md). The `mb3-dat` and `mb3-txt` crates plus `nanobrush-cli` now implement native TXT/DAT format handling ([compatibility profile](RUST_DAT.md)); the broader Rust/rendering/conversion boundaries below remain proposed and must be validated through the [TODO phases](TODO.md).
 
 ## Storage and repository boundaries
 
@@ -15,7 +15,7 @@ nanobrush/                         # remote hf: git@hf.co:nmarshall/nanobrush
   scripts/                        # setup, storage, hydration, extraction, checks
   tests/                          # ordinary Git test source
   docs/                           # ordinary Git authored findings/specifications
-  crates/mb3-dat/                 # implemented native DAT library and tests
+  crates/                         # native DAT/TXT libraries and nanobrush CLI
   assets/references/              # every file is Xet-backed, including small text
     archives/                     # unchanged ZIPs
     provenance/collection/        # original reports/manifest/checksum files
@@ -35,7 +35,7 @@ Build outputs and disposable runtime copies remain ignored. Keep immutable refer
 
 ## Environment shape
 
-Use `flake-parts` and `github:nmrshll/my-nix`, following the current local exports `flakeModuleGroups.essentials` and `flakeModules.rust`. Keep nixpkgs and flake-parts follows consistent. Inspect module evaluation before introducing Rust package builds into an otherwise docs/tooling-only repository.
+Use `flake-parts` and `github:nmrshll/my-nix`, following the current local exports `flakeModuleGroups.essentials` and `flakeModules.rust`. Keep nixpkgs and flake-parts follows consistent. Rust checks and the CLI package use the same pinned toolchain and explicit asset-free source fileset.
 
 Pin remote inputs in `flake.lock`. An optional developer `.envrc` helper may watch local `my-nix` / tools checkouts and pass overrides without rewriting the shared lock; the committed flake remains usable without those checkouts. Separate platform-specific graphics libraries from portable archive/source tooling.
 
@@ -43,7 +43,7 @@ Provide a lightweight preservation/research shell first. Add the Rust workspace,
 
 ## Planned commands and responsibilities
 
-Setup/storage/hydration/reference commands and a converter-only Mono oracle are implemented. The first Rust DAT library is tested through Cargo; a production conversion CLI remains future work. Conversion, oracle, replay, and packaging commands remain proposed interfaces.
+Setup/storage/hydration/reference commands and a converter-only Mono oracle are implemented. The native CLI supports inspect/validate/convert for TXT and both DAT versions, with a Nix package; other formats and editor/replay interfaces remain future work. The remaining asset-conversion, general oracle/replay and GUI-packaging interfaces below remain proposed.
 
 | Command | Inputs | Output and acceptance contract |
 | --- | --- | --- |

docs/TODO.md

@@ -1,6 +1,6 @@
 # Exhaustive work list
 
-Baseline: 2026-10-21. The setup and extraction implementation is complete; checked items are verified in [SETUP.md](SETUP.md). The single-repository layout supersedes the initial separate-dataset proposal. Findings F01–F29 are in [FINDINGS.md](FINDINGS.md). The [investigation method](REVERSE_ENGINEERING.md) defines evidence requirements; [technical direction](TECHNICAL_DIRECTION.md) describes proposed boundaries.
+Baseline: 2026-10-21. The setup and extraction implementation is complete; checked items are verified in [SETUP.md](SETUP.md). The single-repository layout supersedes the initial separate-dataset proposal. Findings F01–F31 are in [FINDINGS.md](FINDINGS.md). The [investigation method](REVERSE_ENGINEERING.md) defines evidence requirements; [technical direction](TECHNICAL_DIRECTION.md) describes proposed boundaries.
 
 Each task ID is stable. Split tasks into child IDs as evidence grows. Record dependencies, output documents/code, validation evidence, and remaining limitations when checking a task off. New discoveries extend this list. P0–P2 establish preservation; P3–P9 establish behavioral contracts; P10–P16 implement and prove the rewrite. P10's GPU spike should happen early alongside source research, before renderer architecture is locked.
 
@@ -130,8 +130,8 @@ Each task ID is stable. Split tasks into child IDs as evidence grows. Record dep
 
 **Depends on:** P3 oracle where available, P5 document model. **Exit:** standalone format specifications, declared compatibility subsets, fixture corpus, and native codecs.
 
-- [ ] P6.01 Specify common encoding, BOM/newline/comment/escape rules, number parsing/printing, path behavior, extension/type dispatch, size limits, and diagnostics. E02 establishes Latin-1/UTF-8 selection, ASCII DAT loss, invariant floats and CLI/log behavior; broad numeric/lexical/platform limits remain open.
-- [ ] P6.02 Specify MB3 TXT grammar and semantics: computed features, named property tables, plane triples, string/UV slots, optional polygons, patches, unknown fields, and missing/default values. E02 specifies property normalization, P0/U/V mapping and computed-list assumptions; exhaustive lexical/numeric/malformed-list cases remain open.
+- [ ] P6.01 Specify common encoding, BOM/newline/comment/escape rules, number parsing/printing, path behavior, extension/type dispatch, size limits, and diagnostics. E02 establishes Latin-1/UTF-8 selection, ASCII DAT loss, invariant floats and CLI/log behavior; F30/F31 now define native TXT/DAT number/encoding limits and diagnostics; other legacy formats and platform measurements remain open.
+- [x] P6.02 Specify the adopted MB3 TXT grammar/semantics: computed flags/arrays, named tables, P0/U/V, string/UV slots, patches, unknown fields and missing values. F30/E04 implements a strict UTF-8 profile and documents differences from legacy guessing, optimization and ignored arrays; broader historical/platform measurements remain in P6.20.
 - [x] P6.03 Determine converter MB3 DAT magic/version/endian/width/string representation, record hierarchy, counts/references, optional computed data, truncation behavior, and recovered version differences. [MB3_DAT.md](MB3_DAT.md), E02; native editor validation and hostile-file coverage continue in P6.19/P6.20.
 - [ ] P6.04 Specify supported HL1 MAP dialect, plane/UV conventions, material/entity handling, coordinate mapping, and input that parses but loses information.
 - [ ] P6.05 Specify supported HL2 VMF subset, nested blocks/IDs, solids/sides, axes, entities, displacement/extra fields, and reference drop behavior; distinguish grammar acceptance from semantic preservation.
@@ -144,7 +144,7 @@ Each task ID is stable. Split tasks into child IDs as evidence grows. Record dep
 - [ ] P6.12 Measure converter failure cases: empty/missing files, invalid syntax/types, malformed geometry, permission failures, long/non-ASCII paths, output overwrite, and interrupted operation.
 - [ ] P6.13 Define a loss-report schema and compatibility profile; preserve originals and unknown data where feasible, and never silently overwrite a source file after lossy conversion.
 - [ ] P6.14 Choose/version the canonical native format, schema migrations, stable IDs, precision, unknown-field policy, and atomic save strategy. Avoid serializing transient Bevy entities as the only durable model.
-- [ ] P6.15 Implement safe Rust parsers/writers and native `inspect/validate/convert` CLI; fuzz parsers, bound allocation/recursion, and test all supported round trips. Both DAT codecs and focused fixture/boundary tests are implemented in P6.21; other codecs, the CLI and coverage-guided fuzzing remain open.
+- [ ] P6.15 Implement safe Rust parsers/writers and native `inspect/validate/convert` CLI; fuzz parsers, bound allocation/recursion, and test all supported round trips. Both DAT codecs are implemented in P6.21; TXT and the native inspect/validate/convert CLI are implemented in P6.22. Remaining codecs and coverage-guided fuzzing stay open.
 - [ ] P6.16 Verify output interoperability with independent consumers where available, alongside reference-compatible results; separate intentional improvements from differences that indicate bugs.
 
 - [x] P6.17 Document the initial grammar/writer format map and source discrepancies, keeping MB3 DAT, IXModel and plugin artifacts distinct (F15–F20).
@@ -155,6 +155,8 @@ Each task ID is stable. Split tasks into child IDs as evidence grows. Record dep
 
 - [x] P6.21 Implement dependency-free safe Rust DAT readers/writers for both versions, bounded streaming I/O and allocations, explicit compatibility policy, checked computed arrays and non-lossy version selection. All 58 E02 DAT outputs round-trip byte-for-byte; 24 unit tests, five integration tests and one doctest validate boundaries and rejection cases ([RUST_DAT.md](RUST_DAT.md), E03/F29).
 
+- [x] P6.22 Implement bounded Rust TXT readers/writers and native `nanobrush inspect/validate/convert` for TXT and both DAT versions, with explicit Unicode/loss policies, structural validation, guarded atomic publication and Nix packaging. All 58 DAT outputs survive CLI DAT→TXT→DAT exactly; seven TXT outputs and 16 direct TXT→DAT pairs are covered; nine invalid/lossy inputs are rejected ([RUST_TXT.md](RUST_TXT.md), [CLI.md](CLI.md), E04/F30/F31).
+
 ## P7 — Input, cameras, grids, views, and editing workflows
 
 **Depends on:** P4 dispatch and P5 geometry. **Exit:** complete interaction/state-machine specifications and reproducible replays.
@@ -314,4 +316,4 @@ Each task ID is stable. Split tasks into child IDs as evidence grows. Record dep
 | M6 Full reconstruction | All required P12/P13 modules and workflows pass parity and GPU checks |
 | M7 Distributable release | P14–P16 regeneration, packaging, documentation, clean-machine acceptance |
 
-Next work after E02: validate the Rust DAT codecs against native-editor output, extend fuzzing/platform coverage and implement the remaining codecs (P6.19/P6.20/P6.15); establish the editor/compiler runtime oracle (P3.05–P3.10), derive consumer/dynamic config and localization keys (P3.03), extend format semantics and loss reports (P6), and continue P2.11 resource/semantic version analysis. The synthetic P10 rendering spike remains independent. Linux extraction/runtime validation remains open in P2.12. Treat M2 and M3 as separate gates; source investigation can proceed while GPU work is unresolved.
+Next work after E02: validate the Rust DAT codecs against native-editor output, extend fuzzing/platform coverage and implement the remaining MAP/VMF/OBJ/IXModel codecs (P6.19/P6.20/P6.15); establish the editor/compiler runtime oracle (P3.05–P3.10), derive consumer/dynamic config and localization keys (P3.03), extend format semantics and loss reports (P6), and continue P2.11 resource/semantic version analysis. The synthetic P10 rendering spike remains independent. Linux extraction/runtime validation remains open in P2.12. Treat M2 and M3 as separate gates; source investigation can proceed while GPU work is unresolved.

docs/experiments/txt-cli-2026-10-21.md

@@ -0,0 +1,33 @@
+# E04 — TXT codec and native conversion CLI
+
+Date: 2026-10-21. Implements F30/F31: bounded TXT serialization and a native inspect/validate/convert workflow. Source anchors are the two supplied TXT grammars and E02 converter behavior, plus the shared F29 DAT model. No original binary was executed or modified by this stage; E02's existing Xet fixtures were reused.
+
+## Reproduction
+
+In the pinned Nix development environment (Rust/Cargo 1.99.0, macOS ARM64):
+
+```sh
+analyze-converter check
+cargo fmt --all --check
+cargo clippy --workspace --all-targets --locked --offline -- -D warnings
+cargo test --workspace --locked --offline
+cargo test --workspace --release --locked --offline
+nix build .#checks.aarch64-darwin.rust .#checks.aarch64-darwin.setup .#nanobrush --no-link
+nix run .#nanobrush -- --help
+```
+
+Full integration tests require the hydrated `assets/analysis/converter/probes` tree. `NANOBRUSH_CONVERTER_FIXTURES` can select an explicitly supplied alternative. E02's SHA-256-indexed report remains the identity anchor; `analyze-converter check` verifies input/output hashes and original converter identities. No golden fixture payload was moved into normal Git or embedded into a source file. Synthetic tests construct their own small grammar examples and boundary inputs.
+
+## Evidence and acceptance
+
+- 58 original DAT outputs survive native DAT→TXT→DAT with exact byte equality, both through libraries and through the real CLI process. Every successful CLI conversion also validates its text output; inspect JSON summaries identify the source format.
+- All seven supplied converter TXT outputs parse and stabilize under native formatting. Sixteen non-lossy TXT→DAT fixture pairs reproduce exact reference output. Nine invalid or silently lossy TXT inputs are rejected.
+- UTF-8 input preserves Unicode rather than reproducing Latin-1 guessing; TXT output includes a BOM. ASCII DAT export refuses character loss. Properties retain unused names and original index meaning, and down-conversion refuses to discard properties.
+- Parser limits include UTF-8 string bytes, total logical elements, requested ownership/scratch and complete input/output bytes. Numbers are bounded to 128 token bytes and finite f32; integer fields are nonnegative i32. Arrays must agree with computed flags and dimensions. There is no recursive parse tree. Three thousand deterministic TXT mutations join the prior 5,000 DAT mutation smoke cases; neither is coverage-guided fuzzing.
+- The CLI validates/encodes before destination staging, refuses accidental replacement, rejects source aliases/output symlinks, and atomically publishes through hard-link/no-clobber or explicit-force rename. A publication test exercises an existing destination after staging and verifies that existing bytes survive and the owned temp is removed.
+
+The workspace has 44 unit tests (24 DAT, 12 TXT, eight CLI), 12 integration tests (five DAT, five TXT, two CLI) and two doctests: **58 Rust tests**. Code-only Nix tests intentionally run the 44 unit tests/two doctests and compile/lint integration targets without opening assets; full fixture tests run separately. The unchanged Python suite has 52 regressions. Final observed results are recorded in [validation](../validation.md).
+
+## Limits
+
+This establishes codec and CLI behavior for the supplied fixture domain and authored adversarial cases, not native editor interoperability, historical byte-identical TXT printing or every possible filesystem failure. The native codec's encoding, strict computed consistency, number limits, preserved properties and canonical layout differ intentionally from the legacy converters; see [F30](../RUST_TXT.md) and [F31](../CLI.md). MAP/VMF/OBJ, native document schema, general loss reports, coverage-guided fuzzing, legacy Latin-1 recoding, independent consumer checks, native-editor tests and Linux/Intel execution remain open. The Nix package contains the native CLI only; no Bevy/Solari/editor feature is claimed by this stage.

docs/parity.md

@@ -41,3 +41,7 @@ Keep the broad parent TODO tasks open until their promised behavioral evidence e
 ## Rust DAT implementation (F29)
 
 `mb3-dat` implements both converter DAT layouts. The five Rust integration tests cover all 58 captured DAT outputs with exact bytes, selected semantic fields, captured malformed-input rejections and version migration. Twenty-four unit tests and one doctest add boundary/resource/I/O checks and 5,000 deterministic mutations. See [the compatibility matrix](RUST_DAT.md) for deliberate strictness and the old signed-16 writer repair. Native-editor conformance, real-document coverage, independent consumer testing and remaining codecs stay open.
+
+## TXT and CLI implementation (E04)
+
+The native TXT codec and CLI cover all 58 E02 DAT outputs through exact DAT→TXT→DAT reconstruction, seven text outputs through canonical semantic round trips, 16 direct TXT-input/DAT-output pairs and nine rejected malformed/lossy text inputs. Original formatting, guessed encodings, ignored arrays and property optimization are explicit differences in F30. CLI no-clobber/force publication, alias/symlink guards, validation before I/O and exit streams are tested separately in F31. Legacy external formats, editor behavior and other-platform execution remain open.

docs/risks.md

@@ -20,3 +20,5 @@ Opened 2026-10-21. Owner: Nanobrush reference research. This register tracks con
 | R14 | Legacy DAT short-read reuse and unbounded string EOF loop (F28) | Corruption, hangs/allocation growth on malformed data | Strict bounded Rust DAT parser implemented (F29); extend fuzzing/editor validation in P6.19/P6.20 |
 | R15 | DAT ASCII loss, BOM-less UTF-8 drift, property normalization and silent MAP/Q3/OBJ losses (F26/F27) | Successful conversions can alter meaningful content | Explicit encoding and loss reports, P6.01/P6.13 |
 | R16 | Rust DAT policy deliberately rejects ambiguous/unknown data and avoids lossy table normalization (F29) | Some converter-accepted files need explicit diagnosis/migration | Preserve originals; validate native-editor/real documents, P6.19/P6.20 |
+| R17 | Native TXT uses strict UTF-8/BOM output, retained table indices and computed-array consistency (F30) | Latin-1 inputs or permissive/lossy historical cases need explicit recoding/diagnosis | Broader real-file/legacy interoperability and fuzzing, P6.20 |
+| R18 | CLI publication uses hard-link/rename in a trusted parent; directory metadata not separately synced (F31) | Filesystem support, hostile directory races and power-loss durability differ by environment | Filesystem/platform failure matrix, P6.12/P15 |

docs/validation.md

@@ -25,3 +25,9 @@ E02 final checks: all 52 tests passed on the host and in the Apple Silicon code-
 The [Rust compatibility profile](RUST_DAT.md) and [experiment](experiments/rust-dat-2026-10-21.md) document the implementation and its limits. Debug and release each pass 24 unit tests, five integration tests and one doctest. All 58 captured converter DAT outputs round-trip exactly; 11 captured malformed/ambiguous inputs are rejected; cross-version autodetection and property-free migration are covered. Boundary tests include 65,535/65,536 counts/indices and 5,000 bounded deterministic mutations. Formatting and Clippy with warnings denied pass.
 
 Both Apple Silicon Nix derivations built successfully: the asset-free Rust check runs 24 unit tests/one doctest and lint/format checks; the setup check retains all 52 passing Python tests. Full fixture tests ran separately against the SHA-256-verified E02 corpus. Source/asset storage boundaries are preserved; no fixture payloads moved into ordinary Git. Native-editor interoperability, other-platform execution and coverage-guided fuzzing remain open.
+
+## E04 TXT and native CLI — 2026-10-21
+
+[TXT compatibility](RUST_TXT.md), [CLI workflow](CLI.md) and [E04](experiments/txt-cli-2026-10-21.md) record the implementation. Full debug and release suites each pass **58 Rust tests**: 44 unit tests, 12 fixture/process integration tests and two doctests. All 58 DAT outputs survive exact DAT→TXT→DAT reconstruction through the real executable, seven converter TXT outputs canonicalize stably, 16 direct TXT→DAT pairs match and nine invalid/lossy TXT source fixtures are rejected. The TXT suite adds 3,000 bounded mutations and streaming/array/encoding limits; CLI tests cover publication races, aliases, symlinks, no-clobber and preserving existing destinations on encoder failure.
+
+Formatting/Clippy pass. Both Apple Silicon Nix checks and the asset-free `nanobrush` package build pass; the Rust check runs 44 unit tests/two doctests, while setup retains all 52 Python regressions. The packaged executable’s help and JSON inspection of the property fixture ran successfully. Converter fixture identity/semantic checks and all 1,082 hydrated asset hashes pass; original captures are unchanged and tests/code remain ordinary Git. Other-platform execution, native-editor interoperability, crash-durability/failure matrices and coverage-guided fuzzing remain open.

flake.nix

@@ -152,9 +152,28 @@
                   cargo test --workspace --doc --locked --offline
                   touch $out
                 '';
+            cliPackage =
+              pkgs.runCommand "nanobrush-cli-0.1.0"
+                {
+                  nativeBuildInputs = [
+                    config.rust.toolchain
+                    pkgs.stdenv.cc
+                  ];
+                  meta.mainProgram = "nanobrush";
+                }
+                ''
+                  cp -R ${codeSource}/. .
+                  chmod -R u+w .
+                  export CARGO_HOME="$TMPDIR/nanobrush-cargo"
+                  cargo build -p nanobrush-cli --release --locked --offline
+                  mkdir -p "$out/bin"
+                  cp target/release/nanobrush "$out/bin/nanobrush"
+                '';
           in
           {
-            packages = scripts;
+            packages = scripts // {
+              nanobrush = cliPackage;
+            };
             rust.buildInputs = runtimeDeps;
             rust.nativeBuildInputs = [ pkgs.pkg-config ];
             rust.toolchain = pkgs.rust-bin.stable.latest.default.override {