Nanobrush planning documents
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. 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 |
|---|---|
| Setup | Current one-repository Git/Xet setup, commands, and validation |
| Goals | Scope, compatibility promises, success criteria, and decisions still needed |
| Findings | Evidence from the archives and nearby repositories; known gaps and uncertainties |
| Inventory | Every regular archive member across all five versions, sizes, and content identities |
| TODO list | Ordered, dependency-aware checklist from environment setup to release |
| Investigation method | How to investigate, record evidence, and prove behavioral equivalence |
| Technical direction | Proposed repository boundaries, asset pipeline, Rust modules, and rendering strategy |
The first source investigation is documented in formats, host APIs, plugins, and dependencies. Complete latest-source endpoint/tool lists are in API_INDEX.md and PLUGIN_INDEX.md. See the coverage ledger, risks, validation, and E01 experiment for evidence and limits.
The executed converter investigation adds MB3 DAT layouts, conversion behavior, and E02: 101 probes across both distinct binaries and 52 code-only tests.
The first native format implementation is the Rust DAT codec, covering both recovered versions with 58 exact converter-output round trips and an explicit strict compatibility profile; reproduction and limits are in E03.
The TXT codec and native CLI now add UTF-8 serialization, inspection/validation, explicit DAT version conversion and guarded atomic publication. See E04 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
- Observed: directly inspected archive bytes, supplied text, or local repository configuration.
- Reported: a statement in supplied historical material or an upstream report, not reproduced here.
- Proposed: an implementation or organization choice for future work.
- Unknown: requires additional evidence; never silently assume compatibility.
Repository storage/environment and reference extraction are implemented; consult the checked tasks and SETUP.md for actual validation. Unchecked TODO items remain future work. A checkbox requires the linked evidence and acceptance condition, not merely code being written.
Planning validation
The original planning backlog contained 197 tasks across 17 phases; source-research subtasks have since been added in TODO.md. The inventory covers all 560 regular-member occurrences (132 distinct paths) and every explicit directory entry across the five ZIPs. Original archive SHA-256 values and CRCs passed; document links, code fences, task IDs, and inventory coverage were checked. Application behavior and GPU support remain untested; repository setup validation is recorded in SETUP.md.
Maintaining this plan
Give each new finding an ID, source version/hash, confidence, and reproducible observation. Link it to a specification, a TODO item, and a validation case. Store original and generated payloads under Xet-filtered assets/ or references/ paths; keep original investigation prose, manifests, scripts, specifications, and Rust source in code Git. Update this index when splitting a large specification into its own document.