Complete imaging and meshing integration gate (#44)

docs/imaging-meshing.md

@@ -0,0 +1,67 @@
+# Imaging and meshing integration
+
+Milestone 06 owns the native implementations in `libremetaverse-imaging`,
+`libremetaverse-imaging-skia`, and `libremetaverse-prim-mesher`. The core
+imaging and meshing crates contain no CLR bridge, subprocess adapter, foreign
+RPC, or generated failure-only shim. The rendering crates consume the checked
+mesh data but remain a separate milestone: this boundary does not hide or
+reclassify their future `MeshFoundry` and `SimpleRenderer` work.
+
+## Feature boundary
+
+| Surface | Default build | Opt-in build | Native dependency |
+| --- | --- | --- | --- |
+| Managed images and TGA | enabled | n/a | none |
+| JPEG 2000 | disabled | `libremetaverse-imaging/jpeg2000` | OpenJPEG 2.5.x |
+| BMP/GIF/ICO/JPEG/PNG/WBMP/WebP | disabled | `libremetaverse-imaging-skia/skia` | Skia |
+| Prim and sculpt meshing, OBJ ingestion | enabled | n/a | none |
+
+OpenJPEG is excluded from the default workspace and is reachable only through
+the optional dependency. Skia is an optional, target-specific dependency;
+Linux and Windows use the Vulkan-capable binary configuration while macOS uses
+the corresponding non-Vulkan binary configuration. Dedicated workflows build
+both optional features on Linux, macOS, and Windows. The default
+`imaging-meshing` workflow proves that no native codec is needed for the owned
+Rust and translated compatibility tests.
+
+## Bounds and rendering contract
+
+Decoded images are limited to 4,096 by 4,096 pixels and encoded inputs to 64
+MiB. Channel sizes, resize products, codec buffers, sculpt-map dimensions,
+profile/path sizes, mesh vertex counts, face indices, viewer groups, and OBJ
+indices use checked arithmetic before allocation or indexing. Malformed input
+returns a typed error.
+
+The rendering-facing integration tests verify that PrimMesh and SculptMesh
+produce finite positions, normals, and UVs; aligned face and viewer-face data;
+preserved prim-face grouping; in-range indices; and the 16-bit index range used
+by the pinned MeshFoundry reference at every supported sculpt topology and LOD.
+
+## Reproducible gates
+
+Run the fixed ownership and feature audit with:
+
+```console
+python3 tools/check_milestone_06.py
+```
+
+The audit rejects owned Rust stubs, feature leakage, missing platform jobs,
+missing performance targets, or drift in the 48 reviewed ManagedImage,
+Coord/Quat, and PrimMesh compatibility cases. The cross-platform workflow also
+runs each reviewed group explicitly, native crate tests, workspace test
+compilation, Clippy with warnings denied, rustdoc with warnings denied, and
+benchmark compilation.
+
+The focused performance baselines are executable Rust programs rather than
+wall-clock assertions, so slower shared runners do not weaken or destabilize
+correctness tests:
+
+```console
+cargo bench -p libremetaverse-imaging --bench image_pipeline
+cargo bench -p libremetaverse-prim-mesher --bench meshing
+```
+
+The image baseline clones, bilinearly resizes, and exports a 2,048-square RGBA
+image. The meshing baseline builds and indexes a high-detail cut, hollow,
+twisted circular extrusion. Both report elapsed time and allocation counts so
+regressions can be compared using the same inputs.