docs/TODO.md

# 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–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.

## P0 — Scope, provenance, and permissions

**Depends on:** supplied collection. **Exit:** documented scope and permitted investigation/distribution paths; unresolved permission-dependent activities identified precisely.

- [x] P0.01 Adopt `nanobrush` as project/HF code repository name and latest MB3 as behavioral baseline; retain all earlier versions as evidence.
- [x] P0.02 Confirm HF namespace and storage layout: `nmarshall/nanobrush`; the user selected one repository, ordinary Git source/tests, and Xet-filtered assets/references (SETUP.md).
- [ ] P0.03 Record the planned CPU, GPU, OS, display-system, and renderer support matrix; distinguish guaranteed from exploratory targets.
- [ ] P0.04 Compare every bundled license/readme/credit file across versions and record hashes and applicable resource scope.
- [ ] P0.05 Resolve permissions or applicable basis for executable investigation, reference reuse, generated reference outputs, and archive/extracted-content HF hosting, separately. Preserve the evidence of resolution.
- [ ] P0.06 Resolve the absent font license notice and actual font origin; plan a newly licensed replacement if necessary.
- [ ] P0.07 Choose the rewrite's source license and attribution policy without applying it to preserved reference content.
- [ ] P0.08 Define the compatibility surface for bundled plugins, third-party IXPL source, compiled plugins, and experimental tools; carry all undecided surfaces as open tasks.
- [x] P0.09 Open a risk/decision register for unavailable MB2, missing source, unavailable oracle, resource gaps, and GPU restrictions; give each risk an owner and a next experiment.
- [ ] P0.10 Record supported reference behaviors versus intentionally improved behavior, including lossy imports and historical bugs, in a parity matrix.

## P1 — Git, Hugging Face, direnv, and Nix

**Depends on:** P0 naming/storage decisions. **Exit:** a fresh clone enters the pinned environment and passes storage checks; ordinary code blobs and Xet payloads are correctly separated in one history.

- [x] P1.01 Initialize the ordinary-Git code repository; inspect any newly existing history/remotes before changing them.
- [x] P1.02 Create/configure the HF code repository named `nanobrush` and add its remote, using `hf` as the proposed alias like `glade`; verify fetch and push URLs and authentication without printing credentials.
- [x] P1.03 Use the user-selected single-repository layout (matching urban-terror-rs): root attributes route `assets/**` and every `references/` directory through Xet/LFS. No separate dataset is needed.
- [x] P1.04 Write a code `.gitignore` for build outputs, caches, extraction temporaries/locks, credentials, editor noise, and `.DS_Store`; assets are deliberately tracked as pointers.
- [x] P1.05 Implement a code clean filter and repository-local installer like `glade`, rejecting reference/payload directories, binary/asset content, oversized files, and asset pointer blobs in code Git.
- [x] P1.06 Install code pre-commit/pre-push checks that inspect staged objects and every newly reachable commit; cover deleted-later binaries, force-add, symlinks, nested repos, unmerged entries, and attribute changes.
- [x] P1.07 Install root `.gitattributes` so every asset/reference payload, including TXT/CFG/IXPL/shader files, uses LFS and binary-safe attributes; source and tests use the ordinary-code filter.
- [x] P1.08 Configure Git LFS and Git Xet locally in the same checkout; verify required filters, transfer registration, and actual pointer blobs. Preserve LFS pre-push when adding history guards.
- [x] P1.09 Implement `assets-check` and `assets-fetch` for the single checkout, including setup checks, hydration, pointer/hash verification, and clear modified/missing-payload errors.
- [x] P1.10 Pin asset identities through LFS SHA-256 pointers in the same Git revision as code; the previous separate-repository assets.lock.json proposal is superseded.
- [x] P1.11 Write `.envrc` using `use flake`; support optional watched local `my-nix` and `my-nix/tools` overrides from the recent nix-rust template without putting personal absolute paths into the committed flake.
- [x] P1.12 Create `flake.nix` using flake-parts and current `my-nix` essentials/Rust modules; follow nixpkgs/fp inputs and commit `flake.lock`.
- [ ] P1.13 Declare Darwin/Linux aarch64/x86_64 evaluation targets; separately prove which dev shells/packages actually work. Avoid unconditional platform-only dependencies.
- [x] P1.14 Include Git/LFS/Xet, Python, archive tools, ripgrep, jq, checksum tools, Nix formatter, shellcheck, and Rust toolchain/check tools. Add Pillow/font tooling and PE/CLR/GPU inspection tools only as their phases require them.
- [x] P1.15 Include appropriate Linux window/input/Vulkan libraries and macOS SDK requirements; keep Wine/Windows oracle tooling separate from native application dependencies.
- [x] P1.16 Provide Nix commands for environment/storage checks, hydration, extraction/verification/indexing, and setup tests. Future Cargo/replay/package commands remain in P10–P16.
- [x] P1.17 Exclude assets/caches from Nix build/check filesets and prove code checks work without hydrated assets. Git-backed flake imports can still include hydrated files; use skip-smudge for code-only CI.
- [x] P1.18 Test routing in disposable repos: arbitrary-extension binary, text/reference assets, pointer placement, missing setup/driver, history violations, attribute overrides, symlinks, and ordinary code/test preservation.
- [x] P1.19 Verify a small permitted payload upload/download through Xet and hash-check it in an empty cache; do not treat configured filters alone as upload proof.
- [x] P1.20 Document first-clone bootstrap, local setup, direnv trust, authentication, offline reference operation, and the single-repository code/pointer workflow.

## P2 — Preservation and extraction scripts

**Depends on:** P1 boundary; local preservation can precede remote publication. **Exit:** originals are preserved and all versions extract deterministically without execution.

- [x] P2.01 Move/copy original ZIPs to `assets/references/archives/` with original filenames; compare every source and destination hash before removing an old location.
- [x] P2.02 Preserve supplied historical `references/` texts/indexes, README, recovery report, manifest, and SHA256SUMS under a provenance subtree; create a project-authored index in code Git.
- [x] P2.03 Update manifest path references and checksum verification commands for the new layout while preserving the original manifest/checksum files verbatim as evidence.
- [x] P2.04 Implement a manifest-driven `unpack-references` script with list/dry-run, version selection, verify-only, extraction, and inventory/report modes; default output `assets/references/extracted/<version>/`.
- [x] P2.05 Verify original size/SHA256 and all member CRCs before accepting output; fail clearly on missing files or unresolved pointer stubs.
- [x] P2.06 Reject traversal/absolute/drive/UNC paths, unsafe links, duplicate destinations, case-fold collisions, reserved names, file-directory collisions, and decompression resource-limit violations.
- [x] P2.07 Extract each build in isolation through a temporary directory and atomic completion marker; never run EXE/BAT/IXPL/plugins during unpacking or mix versions.
- [x] P2.08 Preserve raw bytes and filenames; record timestamps/attributes separately when host filesystems cannot preserve them; document newline/encoding observations without silently normalizing originals.
- [x] P2.09 Make extraction idempotent; detect modified destinations, stale outputs, truncated runs, disk-space errors, and concurrent invocations. Never overwrite user work through an implicit force mode.
- [x] P2.10 Write machine-readable inventories containing archive identity, path, size, SHA256, ZIP CRC/attributes, classification, version, provenance, and extraction tool version.
- [ ] P2.11 Generate cross-version rename/copy/change candidates and a resource dependency graph; keep byte identity separate from semantic similarity. Initial hash/include/literal-resource graph is in E01; implicit/dynamic resource semantics and semantic version comparisons remain open.
- [ ] P2.12 Test adversarial archives and repeat extraction on macOS/Linux; compare output hashes and member sets to the inventories.
- [x] P2.13 Ignore disposable local runtime/build workspaces and extraction locks/temporaries; reserve separate asset paths for future derivatives, fixtures, and captures.
- [x] P2.14 Document complete regeneration from original archives and asset revision, including offline operation.

## P3 — Evidence system and runtime oracle

**Depends on:** P0 permissions for the chosen activities, P2 references. **Exit:** reproducible observation or explicitly bounded alternatives for every unavailable oracle.

- [x] P3.01 Establish findings/specifications/experiments/decisions/parity/validation documents with stable IDs and the evidence schema in `REVERSE_ENGINEERING.md`.
- [ ] P3.02 Turn the member inventory into a coverage ledger, with a disposition and investigation owner for every file and discovered external dependency.
- [ ] P3.03 Index all plugins, includes, interrupts, commands, callbacks, configuration keys, settings, localization keys, shader uniforms, and file-format rules with source anchors. E01 covers source includes/Core/tool registrations, grammar rules, literal CFG declarations and shader uniforms; full consumer/dynamic keys and localization still need investigation.
- [ ] P3.04 Build a versioned include/call/resource graph; identify host-only operations and code shared between plugins.
- [ ] P3.05 Prepare a documented Windows x86-compatible VM oracle; investigate a separate Linux/Wine oracle if useful. Pin OS/toolchain/drivers/prefix details and snapshot clean state.
- [ ] P3.06 Inventory executable imports/resources/CLR metadata and runtime requirements using activities permitted under P0; distinguish native editor and managed tools. E02 completes converter CLR metadata/dependencies; editor and IXPL compiler remain open.
- [ ] P3.07 Reproduce first-run setup in a disposable copy, recording exact commands, cwd, generated files, stdout/stderr, exit codes, logs, and before/after hashes.
- [ ] P3.08 Explain GPU configure scripts and shader-cache cleanup; record default configuration for each oracle version.
- [ ] P3.09 Verify plugin/model builds and launch every version; record failures and their boundaries rather than asserting the latest cannot work from one machine.
- [ ] P3.10 Create an oracle runner for documented compiler/converter commands and controlled UI replay; collect deterministic IDs and scrub only explicitly nondeterministic metadata. The converter-only Mono runner is implemented in E02; compiler/UI oracle remains open.
- [ ] P3.11 Capture screenshots/video, interaction traces, filesystem diffs, timing, errors, and process/dependency logs as asset payloads with textual summaries in docs.
- [x] P3.12 Define oracle availability labels: reproduced, source-only, historical report, inferred, unavailable; keep unverified tasks open if startup cannot be restored.
- [ ] P3.13 Recover additional manuals/tutorials/videos/sample projects and trace their provenance; track MB2 binaries/C# converters as a separate optional recovery stream, without claiming MB3 is MB2.
- [ ] P3.14 If permitted binary work is needed, index relevant routines/managed methods, call graphs, data structures, serializers, and host API handlers; link every conclusion to offsets/tokens and the exact binary hash.
- [ ] P3.15 Reconcile source, runtime, older versions, and binary evidence; document contradictions and minimal counterexamples.

- [x] P3.16 Generate a verified static index across all five builds: file coverage/follow-ups, include candidates, qualified calls, constant/wrapper mappings, tool/resource expressions and reproducible report/index outputs (E01).

- [x] P3.17 Decompile/index both distinct managed converter binaries with binary hashes/RVAs, metadata tables and an isolated Mono runner; retain 101 controlled captures (E02, F24–F28).

## P4 — IXPL, host APIs, plugins, and auxiliary tools

**Depends on:** P3 indexing; oracle-dependent tasks use P3 runtime. **Exit:** every exposed host operation and bundled module has a behavior contract and rewrite disposition.

- [ ] P4.01 Specify IXPL lexical rules, numeric widths/overflow, strings/encodings, tuples/arrays/references, namespaces/includes, templates, control flow, callbacks, interrupt arguments, and error behavior from grammar/source and experiments.
- [ ] P4.02 Determine IXPL compilation modes, include-path resolution, generated artifact formats, validation/errors, and compiler CLI behavior; distinguish program/model execution from plugin compilation.
- [ ] P4.03 Enumerate every Akula/Core-Grid/Core-QuakeWorld/Core-Mb3 interrupt: ID, signature, ownership/lifetime, global/current-view/current-world preconditions, outputs, error behavior, and callers.
- [ ] P4.04 Specify tool registration, key-down/up pairing, cleanup, modal capture, callback reentrancy, plugin load/unload, startup/finalization, and view lifecycle ordering.
- [ ] P4.05 Specify task names/payload buffers/priorities, ordering ties, queue timing, nested dispatch, and invalid task handling.
- [ ] P4.06 Specify host filesystem/process/dialog/log/config/translation services and the capabilities bundled plugins actually use.
- [ ] P4.07 Document and replace all IXPL file/model, matrix/rectangle, geometry, list, text-config, string, help, and toolbar utilities; distinguish general utilities from required runtime behavior.
- [ ] P4.08 Write a module-by-module port map for camera, grid, layout designer, log, main menu, editing tools, plugin management/menu, render modes, notes, projections, raycast, priorities, view events/layouts, window controls, and world controller.
- [ ] P4.09 Specify and port all experimental modules: bevel, both blank templates' extension examples, Lego generation, and patch test; classify their known limitations.
- [ ] P4.10 Decide and document third-party extensibility/legacy compatibility; prototype the hardest required construct before promising source or bytecode compatibility.
- [ ] P4.11 If IXPL execution is required, separately plan parser/type checker/runtime or translation, host capability boundaries, diagnostics, resource limits, migration tools, and conformance tests; do not load arbitrary legacy plugins into the Rust host by default.
- [ ] P4.12 Account for all three auxiliary executable roles and all 17 BAT files with native command replacements or a documented reference-only disposition.

- [x] P4.13 Resolve and document the source-declared Core interrupt ranges and all latest wrappers, with version comparisons and explicit ABI/context limits (F21).
- [x] P4.14 Map every top-level/experimental plugin and nine named task clients, including registrations, message shapes and source-level lifecycle risks (F23).

## P5 — World representation and geometry kernel

**Depends on:** P4 API contracts; feeds P7 tools and P6 formats. **Exit:** geometry specification plus analytic/reference fixtures and numerical policies.

- [ ] P5.01 Establish coordinate system, units, handedness, plane basis/orientation, matrix layout/order, transforms, projection/depth conventions, and conversions to Bevy coordinates.
- [ ] P5.02 Determine native/serialized numeric precision, scale limits, epsilon policies, equality/coplanarity, infinities/NaNs, and negative/near-zero behavior per operation.
- [ ] P5.03 Specify brush construction from planes, half-space inclusion, plane intersections, contour construction/order, redundant planes, boundedness, convexity, and degenerate/invalid brushes.
- [ ] P5.04 Specify face polygons, triangulation, normals/tangents, edge sharing, AABBs, computed features, and cache invalidation; stable identity must survive remeshing.
- [ ] P5.05 Specify per-plane string/UV property tables, property removal/reindexing, defaults, and transforms including texture/UV locking behavior if present.
- [ ] P5.06 Specify ray intersections, hit ordering/ties, plane/brush/patch identity, hidden/backface treatment, obstruction tests, and spatial acceleration behavior.
- [ ] P5.07 Specify selection-set membership, transfers/merges, per-world ownership, deletion effects, hidden geometry, cached bounds, and auxiliary-set semantics.
- [ ] P5.08 Specify all transforms: move/copy, reflection, principal/alternate-basis rotations, scaling, plane-facing drags, singular transforms, and property preservation.
- [ ] P5.09 Specify clipping side/plane creation/order, split versus discard behavior, merge/convex hull semantics, intersection, and invalid operation outcomes; investigate any further discovered boolean operations separately.
- [ ] P5.10 Specify Patch9 basis/evaluation, anchor indexing, multi-tile continuity, tessellation resolution, normals, winding, selection, transforms, rendering, and converter support/loss.
- [ ] P5.11 Specify undo snapshot/delta boundaries, redo invalidation, limits, grouping, failed/no-op edits, visibility/selection changes, and persistence interactions.
- [ ] P5.12 Measure spatial balancing/render cache settings, render intervals/distances, and which affect observable results versus performance alone.
- [ ] P5.13 Build analytic cases: boxes, wedges, slivers, coplanar/parallel planes, huge/tiny coordinates, reflected solids, tangent rays, patch seams, invalid brushes, and overlapping selections.
- [ ] P5.14 Implement and validate a headless Rust geometry kernel with property/metamorphic tests, differential fixtures, deterministic topology, and bounded failure behavior.

## P6 — File formats and converters

**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; 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.
- [ ] P6.06 Specify supported Q3 MAP dialect, brush definitions, shader names, patches, detail/content flags, entities, and reference drop behavior.
- [ ] P6.07 Specify Wavefront OBJ export vertices/normals/UVs/indexing/groups/material policy, triangulation, brush versus patch output, and coordinate conventions; importing OBJ is a separate optional extension.
- [ ] P6.08 Specify IXModel header, version/opcodes, string tables, graph references, mesh attributes/indices, draw modes, transforms, and malformed input using writer source and generated samples.
- [ ] P6.09 Specify plugin artifact layout only to the level needed by the adopted legacy compatibility decision; identify code versus runtime data and unsupported versions.
- [ ] P6.10 Specify config/key-config/text-markup grammars, duplicate-key semantics, defaults, includes, and settings persistence; separate user preferences from document content.
- [ ] P6.11 Build one-feature-at-a-time fixtures and a cross-version conversion matrix for every supported direction; record output/log/exit code and semantic equivalence.
- [ ] 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 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).

- [x] P6.18 Establish a focused two-binary conversion matrix: DAT/TXT properties, computed brushes/patches, width transitions, three brush MAP/VMF round trips, Q3 patch losses, OBJ output and CLI/log/corruption probes; document F26–F28 and 101 captures (E02).
- [ ] P6.19 Validate recovered DAT structures against native-editor saves/loads and real documents. The bounded Rust readers/writers, E02 byte/semantic round trips and absent-versus-empty preservation are complete in P6.21; editor/real-document evidence remains open.
- [ ] P6.20 Extend converter/codec coverage: 65,535/65,536 plane/property boundaries, UV width transitions, malformed patch lengths/dimensions, overflow/negative counts, non-finite/extreme floats, embedded NUL/escape edges, duplicate DAT names, Unicode/long paths, log-write failure, interrupted/partial output, independent consumers and Windows/Linux comparison. Rust synthetic tests now cover 65,535/65,536 plane/property/UV widths, slot sentinels, malformed array consistency, overflow, finite extremes, non-finites and decoder rejection of duplicate slots/reserved bits. Remaining legacy measurements, embedded-NUL/escape edges, platform comparisons and coverage-guided fuzzing remain open. Fuzz bounded native codecs, not the legacy unbounded string reader.

- [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.

- [ ] P7.01 Extract every default binding and modifier from base/fly maps; document press/release, key repeat, contextual precedence, layout-dependent keys, and remapping.
- [ ] P7.02 Specify fly/cursor mode transitions, pointer lock/release, acceleration, wheel speed, reset, focus loss, cancellation, and keyboard cursor movement.
- [ ] P7.03 Specify camera position/orientation, local/global movement, perspective/orthographic projections, clipping, zoom/pan/orbit if found, presets, and ten projection memories.
- [ ] P7.04 Specify viewport hit routing, last-used view, world/view cloning and closing, multiworld independence, split resizing, layout presets, and view-count limits.
- [ ] P7.05 Specify rectangular and circular grid math, arbitrary origins/bases, bias, axis locks, angular/radial resolutions, planar offset, cursor ray-plane intersections, and perspective/orthographic interaction.
- [ ] P7.06 Specify rounding/ties, negative values, resolution/base changes, secondary snap ordering, disabled axes, centerlines, and ten grid memories; compare CPU cursor results to shader visuals.
- [ ] P7.07 Specify and replay box creation including click-drag/sticky continuation, zero extent, rightclick abort, and view changes mid-tool.
- [ ] P7.08 Specify and replay move/copy-move including zero-displacement confirmation, pivot, alternate action, modifiers, and undo grouping.
- [ ] P7.09 Specify and replay mirror, both 90-degree rotations, double/halve scaling, and their alternate grid-basis variants.
- [ ] P7.10 Specify and replay facing-plane drag, two-point clip, three-point clip, merge, and intersection, including preview behavior and degenerate inputs.
- [ ] P7.11 Specify and replay paint/select/deselect/invert/all, auxiliary-set operations, AABB/brush inside/touching tests, and overlap/tie behavior.
- [ ] P7.12 Specify and replay delete/hide/show, empty sets, undo/redo branching/limits, and selection changes around editing operations.
- [ ] P7.13 Specify new/open/save/save-as/save-copy/export, dirty state, current format/path, multiple open worlds, merge-into-current behavior, dialogs, and quit prompts if present.
- [ ] P7.14 Specify menu/toolbox focus, transient text input, modal dialogs, view switching, plugin errors, key-up during dialogs, and lost input cleanup.
- [ ] P7.15 Produce complete workflow scenarios: create/edit/save/reopen, import-edit-export, multiview editing, grid-aligned modeling, patches, and experimental generators.

## P8 — UI, text, configuration, and supporting modules

**Depends on:** P4/P7. **Exit:** behavior and asset map for every bundled UI/settings/string family.

- [ ] P8.01 Inventory every window/control, toolbar orientation, sizing/anchoring/drag/resize behavior, focus style, help affordance, and persistence key.
- [ ] P8.02 Specify main menu, editing/render/layout toolbars, plugin menu/manager, window controls, and their show/hide/toggle commands.
- [ ] P8.03 Specify grid/projection/camera panels, validation of typed values, reset/defaults, text import/export, preset storage, and error messages.
- [ ] P8.04 Specify GUI layout designer operations and exported data; implement an equivalent designer or explicitly agreed successor workflow.
- [ ] P8.05 Specify notes and log content/lifetime, filtering/scrolling/copy behavior if present, per-world/view/global ownership, and serialization.
- [ ] P8.06 Specify text markup, glyph atlas indexing/metrics, colors/styles/underlines, escaping, localization lookup/fallback, and font switching.
- [ ] P8.07 Resolve icon `56` suffix lookup and atlas metadata; document crops, filtering, alpha, spacing, and intended usage.
- [ ] P8.08 Resolve missing content-texture index behavior and distinguish placeholder/resource support from full texture editing.
- [ ] P8.09 Port versioned settings and legacy preference import with defaults, migration, validation, and recovery from malformed config.
- [ ] P8.10 Design reusable Rust UI components/styles for panels, controls, toolbars, editors, dialogs, logs, and help; keep interaction logic independent of visual widgets.
- [ ] P8.11 Verify macOS Command/Control conventions, Linux shortcuts, text composition, clipboard, DPI/multi-monitor scaling, pointer capture, and readable focus states while retaining a reference keymap option.

## P9 — Original renderer and asset specifications

**Depends on:** P3/P5/P8. **Exit:** documented visual semantics and complete conversion recipes.

- [ ] P9.01 Specify the shader container sections, vertex inputs, uniforms, matrices, blend/depth/cull behavior, and host-provided constants for all three shaders.
- [ ] P9.02 Specify six brush render modes, face/border widths/colors, normal-color mapping, see-through compositing, selection/hidden states, backface rules, and patch rendering.
- [ ] P9.03 Specify grid rendering, cursor model, line widths/antialiasing, depth/occlusion, LOD/fade, circular geometry, and agreement with snapping math.
- [ ] P9.04 Specify viewport composition, overlays, scissor regions, render ordering, resizing, near/far clipping, and shared-world view updates.
- [ ] P9.05 Catalogue all PNG/color-space/alpha/font/icon resources and generated models; choose reuse or independently authored replacement per item.
- [ ] P9.06 Document procedural cursor geometry from `grid cursor.ixpl`; implement native deterministic generation rather than invoking IXPL at application startup.
- [ ] P9.07 Define conversion recipes for text recoding, configuration/keymaps, localization/markup, atlas metadata, IXModel meshes, geometry fixtures, and GLSL behavior to WGSL.
- [ ] P9.08 Keep raw resources immutable; every derivative gets source hashes, tool/version/options, output hashes, color/coordinate/precision metadata, and license/disposition.
- [ ] P9.09 Build validators for image dimensions/alpha/glyph coverage, model bounds/topology, converted setting/command references, and expected output membership.
- [ ] P9.10 Capture baseline views and analytic render fixtures with named camera/grid/render state; establish tolerances and which visual differences are intentional.

## P10 — Rust/Bevy architecture and early Solari feasibility

**Depends on:** P1; use synthetic independently authored scenes so this spike need not await binary research. **Exit:** proven portable renderer and a measured Solari path on actual target hardware.

- [ ] P10.01 Pin a mutually compatible Rust/Bevy/Solari/wgpu set after testing; 0.20.0 is an inspected candidate, not a pre-approved dependency lock.
- [ ] P10.02 Create the Rust workspace with geometry/document/commands/formats/assets/editor/render/CLI separation proposed in `TECHNICAL_DIRECTION.md`.
- [ ] P10.03 Build an ordinary-rendered Bevy window on macOS Metal and Linux Vulkan, including resize, input, DPI, and a generated brush mesh.
- [ ] P10.04 Enumerate adapter features/limits/OS/driver and Solari requirements before enabling it; exercise unsupported hardware and clear fallback selection.
- [ ] P10.05 Run a minimal synthetic Solari scene on capable macOS hardware and Linux hardware; specifically account for M2 versus M3+ risks and binding-array limits.
- [ ] P10.06 Test non-NVIDIA operation and denoising; optional DLSS must not be a required dependency for macOS or the baseline Linux editor.
- [ ] P10.07 Test orthographic/perspective cameras, multiple simultaneous viewports, viewport resize/close, render-to-texture, HDR/tonemapping, antialiasing, and temporal state per view.
- [ ] P10.08 Test brush/patch mesh create/update/delete/undo, material changes, BLAS/TLAS updates, resource reclamation, ray-scene visibility, and temporal-history resets during editing.
- [ ] P10.09 Measure convergence/noise, ghosting, edit latency, frame time, memory, and adapter loss. Record unsupported combinations with a reproducible upstream/minimal case.
- [ ] P10.10 Adopt documented render policy: portable diagnostic/edit modes plus optional Solari lighting; if stricter Solari coverage is desired, resolve minimum hardware requirements explicitly.
- [ ] P10.11 Define deterministic document/command scheduling, background geometry jobs, stale-result cancellation, stable IDs, and conversion boundaries independent of Bevy entity IDs.
- [ ] P10.12 Write architecture decisions for UI library, file dialogs, plugin/extensibility model, schema, geometry library dependencies, and rendering fallback, with evidence from spikes.

## P11 — Native core and format implementation

**Depends on:** P5/P6 contracts and P10 architecture. **Exit:** useful headless editor with no original-runtime dependency.

- [ ] P11.01 Implement canonical worlds/brushes/planes/patches/properties/selection/visibility with stable IDs and explicit invariants.
- [ ] P11.02 Implement validated geometry operations, bounds/spatial index, picking, tessellation, UV transforms, and incremental render-mesh generation.
- [ ] P11.03 Implement command transactions, preview/commit/cancel, undo/redo, dirty state, deterministic replay, and failure rollback.
- [ ] P11.04 Implement native codecs/converter CLI and canonical document migrations; complete the P6 format matrix before claiming each format supported.
- [ ] P11.05 Implement grid/camera/projection state and math without UI dependencies; cover every identified snap/tie/basis rule.
- [ ] P11.06 Port utility/model-generation/config/translation services required by bundled modules; eliminate runtime EXE/BAT/.NET dependencies.
- [ ] P11.07 Complete geometry/format/command differential and property tests; run corpus tests without a GPU and report unresolved reference differences.

## P12 — End-to-end editor slices and remaining parity

**Depends on:** P7/P8 contracts and P11 core. **Exit:** all bundled editing and supporting modules are usable natively.

- [ ] P12.01 Deliver the first slice: launch → view/grid → create box → select/move → undo/redo → save → restart/reopen; prove on both OSes.
- [ ] P12.02 Add multiview/multiworld ownership, layout presets, cameras, projections, and grid/preset panels with correct focus/capture.
- [ ] P12.03 Implement every P7 tool state machine, contextual binding, alternate action, selection-set workflow, and cancel path; mark parity per command.
- [ ] P12.04 Implement all menus/toolbars/help, settings, notes/log, layout designer, plugin management/extensibility, and experimental tools from the module port map.
- [ ] P12.05 Integrate all import/export/save workflows, file loss reports, dirty-state/quit handling, atomic writes, and recovery behavior.
- [ ] P12.06 Add autosave/recovery as a documented improvement with tests that it cannot corrupt originals; distinguish it from observed reference behavior.
- [ ] P12.07 Verify user preferences, keymap migration, localization/font replacement, icon atlas behavior, and runtime asset lookup in packaged builds.
- [ ] P12.08 Replay all reference workflows and compare resulting canonical documents, tool state, visible state, logs, and selected render captures.

## P13 — Portable rendering and Solari integration

**Depends on:** P9/P10 and changing meshes from P11. **Exit:** diagnostic parity and responsive raytraced lighting within declared hardware support.

- [ ] P13.01 Port brush/patch/grid visual semantics to Bevy/WGSL; preserve picking/diagnostic behavior independently of lighting mode.
- [ ] P13.02 Implement all six reference render modes, selection/hover/cursor overlays, backface/see-through policies, line rendering, and per-view options.
- [ ] P13.03 Integrate Solari scene/material/light resources with document changes; exclude editor overlays and hidden geometry appropriately from lighting/picking.
- [ ] P13.04 Implement temporal invalidation, interactive-quality policy, accumulation/convergence indication, and clean transition between lighting and diagnostic modes.
- [ ] P13.05 Handle multiworld/multiview GPU budgets, missing features, shader failure, device loss, and fallback without losing the user's document.
- [ ] P13.06 Validate text/icon compositing, alpha/color management, DPI, viewport depth/clipping, geometry precision, and raster-versus-Solari surface agreement.
- [ ] P13.07 Profile representative large scenes and repeated editing sessions; optimize incremental geometry/acceleration updates, upload scheduling, and memory leaks using measured bottlenecks.

## P14 — Conversion pipeline and reproducibility

**Depends on:** P2/P6/P9 implementations. **Exit:** one documented regeneration path from pinned references to validated runtime assets.

- [ ] P14.01 Implement scripts/CLI commands listed in `TECHNICAL_DIRECTION.md`; Python orchestrates preservation/reporting and Rust owns canonical geometry/format semantics.
- [ ] P14.02 Provide raw-to-UTF-8 derivative recoding with detected/declared input encoding, preserved raw hashes, newline policy, and a reversible mapping report.
- [ ] P14.03 Implement geometry/model, icon/font/atlas, config/keymap/localization, and fixture converters with explicit recipes; author replacements when required.
- [ ] P14.04 Make builds incremental by content hash, with recipe/version invalidation, deterministic output order, atomic writes, dry-run, explicit overwrite, and cleanup limited to owned outputs.
- [ ] P14.05 Validate all derivatives and generate dependency/license manifests and missing-reference reports. Separate source recipes from binary/generated payloads.
- [ ] P14.06 Run regeneration twice and on both OSes; compare exact hashes where deterministic and canonical semantic outputs where platform tooling necessarily differs.
- [ ] P14.07 Push permitted asset pointers/payloads through Xet, verify recovery and pointer policy, and record the joint code/asset Git revision; no separate asset lockfile is used.
- [ ] P14.08 Package only required runtime assets and notices; prove the app does not need the preserved reference tree.

## P15 — Validation, CI, and performance gates

**Depends on:** gates grow with each slice. **Exit:** traceable tests for every promised behavior across declared platforms.

- [ ] P15.01 Add code-only CI for format/lint/compile/unit/property/fixture/docs/storage checks and Nix evaluation/build checks on supported systems.
- [ ] P15.02 Add pinned asset hydration and permitted corpus validation jobs separately; ordinary contributions must not require private archive credentials.
- [ ] P15.03 Add parser/geometry fuzzing, crash minimization, regression fixture ingestion, and bounded processing for malformed/untrusted documents.
- [ ] P15.04 Add deterministic input replay and semantic document comparison; do not rely on screenshot similarity to prove geometry or save correctness.
- [ ] P15.05 Run real GUI tests on macOS and Linux Wayland/X11 for focus, pointer capture, text/dialogs/clipboard, DPI, multiview, and quit/reopen.
- [ ] P15.06 Run named-hardware GPU tests for Metal/Vulkan, ordinary rendering/Solari, supported/unsupported adapters, and packaged applications; software/headless CI cannot establish these results.
- [ ] P15.07 Establish and enforce measured frame/edit/import/save/startup/memory budgets using small, large, degenerate, and patch-heavy scenes; record hardware and percentile methodology.
- [ ] P15.08 Test long sessions, repeated edits/undo/redo, concurrent background tasks, cancellations, disk-full/read-only paths, interrupted saves, missing assets, and GPU/device errors.
- [ ] P15.09 Audit dependency licenses, vulnerabilities, plugin/process capabilities, credentials, and release contents as concrete release checks.
- [ ] P15.10 Produce a final parity matrix linking every file/module/API/tool/config/format/render mode to findings, implementation, validation, and any unresolved deviation.

## P16 — Packaging, documentation, and release

**Depends on:** P15 acceptance and P0 redistribution decisions. **Exit:** independently installable native releases and complete findings/manuals.

- [ ] P16.01 Build macOS application bundles and Linux packages/archive layout with correct icons, runtime assets, native libraries, user-data/config/cache paths, and minimum OS metadata.
- [ ] P16.02 Test macOS signing/notarization/quarantine behavior for the chosen release channel; test Linux desktop integration, Wayland/X11 launch, and library/driver diagnostics.
- [ ] P16.03 Install on clean target machines and run full create/import/edit/save/export workflows, both renderer policies, offline startup, and upgrades/schema migrations.
- [ ] P16.04 Publish original architecture/format/API/algorithm findings with source identities, confidence, experiments, unresolved questions, and rights-aware reference links.
- [ ] P16.05 Write user manual/tutorials, complete shortcut/tool reference, grid/patch guides, supported-format/loss table, plugin migration guide, and troubleshooting/recovery instructions.
- [ ] P16.06 Write contributor/build/asset-regeneration/CI/release documentation and a versioned compatibility/performance/hardware matrix.
- [ ] P16.07 Assemble notices/SBOM/checksums, code and asset revisions, reproducibility records, known limitations, and tested release artifacts.
- [ ] P16.08 Reconcile every remaining checkbox against the definition of done; do not label the entire rewrite complete while required parity remains unresolved.

## Milestone order and proof

| Milestone | Required evidence |
| --- | --- |
| M0 Planning baseline | These documents plus integrity/member inspection; no implementation implied |
| M1 Reproducible preservation | P0–P2 decisions/setup, verified extraction, fresh code clone and asset recovery |
| M2 Feasible renderer | P10 hardware results and explicit platform/render support policy |
| M3 Behavioral specification | P3–P9 evidence/API/format/tool coverage, reference fixtures, unknowns register |
| M4 Headless core | P11 codecs/geometry/commands pass semantic tests and converters work natively |
| M5 Usable native slice | P12.01 works on macOS/Linux through save/restart/reopen |
| 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 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.