From 931f561e7ff1489f897e22ebb3cc7545fcfef702 Mon Sep 17 00:00:00 2001 From: Rbanh Date: Mon, 13 Jul 2026 14:08:25 -0400 Subject: [PATCH] Document FBX dependency acceptance --- docs/README.md | 2 + docs/editor/README.md | 1 + docs/editor/evaluations/README.md | 14 ++-- .../README.md | 71 +++++++++++++++++++ .../production-readiness/README.md | 9 +-- 5 files changed, 87 insertions(+), 10 deletions(-) create mode 100644 docs/editor/evaluations/fbx-external-texture-dependencies/README.md diff --git a/docs/README.md b/docs/README.md index 3e15c25..6d94d55 100644 --- a/docs/README.md +++ b/docs/README.md @@ -100,6 +100,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi | [editor/evaluations/guarded-shutdown-savepoints/](editor/evaluations/guarded-shutdown-savepoints/) | Source and native acceptance evidence for guarded editor exit and per-document clean checkpoints | | [editor/evaluations/scoped-ui-actions/](editor/evaluations/scoped-ui-actions/) | Exact-implementation source and native acceptance evidence for actions invoked during scoped egui rendering | | [editor/evaluations/deterministic-asset-fingerprints/](editor/evaluations/deterministic-asset-fingerprints/) | Source, fresh-checkout, hash-stability, and native acceptance evidence for imported-source fingerprints | +| [editor/evaluations/fbx-external-texture-dependencies/](editor/evaluations/fbx-external-texture-dependencies/) | Source, validation, and native acceptance evidence for sandboxed FBX texture dependencies and override states | | [editor/evaluations/production-readiness/](editor/evaluations/production-readiness/) | Current versioned production gate, evidence matrix, candidate commands, soak protocol, and independent sign-off requirements | ## Working plans (not canonical long-term) @@ -126,6 +127,7 @@ Detailed milestone and feature plans live in [`.cursor/plans/`](../.cursor/plans | `operator_invariants_completion_*.plan.md` | Production operator dispatch, interruption, rollback, cleanup, and undo/redo acceptance | | `editor_sample_regression_pack_*.plan.md` | Five-area sample manifest, editor catalog, deterministic validation, and native regression acceptance | | `guarded_shutdown_savepoints_*.plan.md` | Native close coordination, asynchronous Save All, and canonical history clean points | +| `fbx_external_texture_dependencies_*.plan.md` | Sandboxed FBX sidecar discovery, import transactions, validation, loader behavior, and Asset Browser states | ## Crate responsibilities (quick reference) diff --git a/docs/editor/README.md b/docs/editor/README.md index 6c2983b..afea590 100644 --- a/docs/editor/README.md +++ b/docs/editor/README.md @@ -45,6 +45,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a | [evaluations/guarded-shutdown-savepoints/](evaluations/guarded-shutdown-savepoints/) | Source and native acceptance evidence for guarded editor exit and per-document clean checkpoints | | [evaluations/scoped-ui-actions/](evaluations/scoped-ui-actions/) | Exact-implementation source and native acceptance evidence for actions invoked during scoped egui rendering | | [evaluations/deterministic-asset-fingerprints/](evaluations/deterministic-asset-fingerprints/) | Source, fresh-checkout, hash-stability, and native acceptance evidence for imported-source fingerprints | +| [evaluations/fbx-external-texture-dependencies/](evaluations/fbx-external-texture-dependencies/) | Source, validation, and native acceptance evidence for sandboxed FBX sidecar dependencies and override states | | [evaluations/production-readiness/](evaluations/production-readiness/) | Current #50 release-candidate matrix and required clean-checkout, soak, performance, limitation, and independent-signoff evidence | ## Subsystems (code → doc) diff --git a/docs/editor/evaluations/README.md b/docs/editor/evaluations/README.md index 930a8c0..c1d508d 100644 --- a/docs/editor/evaluations/README.md +++ b/docs/editor/evaluations/README.md @@ -1,15 +1,17 @@ # Editor Evaluation Evidence -Each subdirectory keeps the canonical, versioned acceptance record for an editor feature. Screenshots -remain in the repository beside that record and are intentionally stored through Git LFS. +Each subdirectory keeps the canonical, versioned acceptance record for an editor feature. Record +visual evidence with its attachment ID, dimensions, and checksum. A repository image copy is +optional; the committed Markdown record, not a raw image URL, is the source of truth. ## Publishing To Gitea Do not embed a repository `/raw/branch/...` or `/raw/commit/...` PNG URL in an issue or pull-request comment. Gitea can serve the LFS pointer document at that URL, which renders as text instead of an image. Upload the PNG to the relevant issue as a native attachment and use the returned -`/attachments/` URL for the Markdown image. Keep the repository evaluation link next to the -attachment so the evidence remains traceable to its committed source. +`/attachments/` URL for the Markdown image. Keep the committed evaluation link next to the +attachment so the evidence remains traceable to its tested source and exact commit. -Native attachments are presentation copies. The committed evaluation directory remains the source of -truth and should retain the original image and verification notes. +Native attachments are the presentation copies used by issues and pull requests. Do not commit a +duplicate image solely to publish it; retain verification notes and attachment metadata in the +evaluation record. diff --git a/docs/editor/evaluations/fbx-external-texture-dependencies/README.md b/docs/editor/evaluations/fbx-external-texture-dependencies/README.md new file mode 100644 index 0000000..a2f3759 --- /dev/null +++ b/docs/editor/evaluations/fbx-external-texture-dependencies/README.md @@ -0,0 +1,71 @@ +# FBX External Texture Dependency Evaluation + +**Date:** 2026-07-13 + +**Issue:** [Gitea #58](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/58) + +**Implementation commit:** `3e30c61c71fc942c33635aae3d922b70401fe7c7` + +**Release-candidate commit:** Not nominated + +**Source validation:** **Pass** + +**Native acceptance:** **Pass** + +This record covers path-safe FBX texture discovery, transactional bundle import, labeled runtime +images, static-mesh dependency publication, read-only project validation, and stable Asset Browser +states. The permanent contract is owned by +[ADR 0044](../../../adr/0044-sandboxed-fbx-external-texture-dependencies.md). + +## Automated Verification + +| Command or suite | Result | Evidence | +|------------------|--------|----------| +| `cargo fmt --all -- --check` | Pass | Formatting completed without changes. | +| `git diff --check` | Pass | No whitespace errors. | +| `cargo clippy --workspace --all-targets -- -D warnings` | Pass | Every workspace target completed with warnings denied. | +| `cargo test --workspace --all-targets` | Pass | All workspace targets passed. Editor reported 309 passing tests; scene reported 103 passing tests and one ignored manual migration test. | +| FBX dependency/import regressions | Pass | Six focused tests cover the committed chair, sibling `textures/`, `.fbm/`, missing bundles, parent traversal, and destination symlink containment. Thumbnail regressions cover terminal missing-texture state and first-render pipeline warmup. | +| `cargo validate-levels --project .` | Pass | 84 dependencies, six known nonblocking findings, zero blocking errors. The chair contributes one informational Authoring Override finding. | +| `cargo validate-samples --project .` | Pass | Five samples, 89 dependencies, the same six nonblocking findings, zero blocking errors. | +| Controlled Source Materials validation | Pass | Changing only the chair registry and static-manifest policies on top of `3e30c61` produced one `import.external_texture_missing` blocker for all three paths, then restoration returned to zero blockers. | +| Packaged acceptance | Deferred | Explicitly deferred by project-owner direction; no packaged result is claimed. | + +## Native Acceptance + +The exact debug binary built from `3e30c61` was launched as +`target/debug/editor --project .` under native Hyprland Wayland. + +| Workflow | Result | Evidence | +|----------|--------|----------| +| First model-folder visit | Pass | The painted-chair model rendered on the first visit without manual thumbnail regeneration; the first offscreen PBR capture remained active through render-pipeline warmup. | +| Deliberately normalized chair | Pass | Selecting the committed Authoring Override chair showed one `3 missing \| override` dependency state and all three paths. Its mesh preview rendered neutrally, while source-material and missing-texture subassets settled to terminal warning icons instead of indefinite spinners. | +| Runtime log | Pass | The exact committed run emitted no stdout/stderr output, including no `bevy_asset`, `bevy_ufbx`, or path-not-found errors, and exited with code 0. | +| Checkout stability | Pass | Native startup, model browsing, thumbnail generation, and exit left `git status --short` empty. | +| Controlled broken fixture | Pass | On top of `3e30c61`, only the two chair `material_policy` fields were changed to `SourceMaterials`. The editor showed `Source Materials`, one red `3 missing` state, and terminal warning subassets. No asset/FBX/path error appeared; only two unrelated egui multi-pass layout warnings occurred at startup. | +| Fixture restoration | Pass | The two policy fields were restored to Authoring Override, `git status --short` returned empty, and `validate-levels` returned to zero blockers. | + +## Native Evidence + +![Authoring Override chair with a first-pass mesh thumbnail, terminal subasset warnings, and one visible dependency state](https://git.spacetrainclubhouse.com/attachments/a66b1844-2d17-4975-ba6e-1c0e00a02709) + +- Gitea attachment asset 43: `blacksite-issue58-chair-normalized-3e30c61.png`, 1426x3384 + RGB PNG, 1,802,863 bytes. +- SHA-256: `e492082f7eb3314bed6c97d424bc2281b125849552997f12931013a8e50630f2`. + +![Controlled Source Materials fixture with three missing dependencies and terminal warning subassets](https://git.spacetrainclubhouse.com/attachments/a64cd69b-0fe7-4dc8-9f24-a333e018a682) + +- Gitea attachment asset 44: `blacksite-issue58-chair-broken-source-materials-3e30c61.png`, + 1426x3384 RGB PNG, 2,042,528 bytes. +- SHA-256: `759297276287a05bf678ea72e26159d5cb4613d917db447a1cbc1efa562fc831`. + +Both images are ordinary Gitea issue attachments. This record does not use repository raw or Git +LFS pointer URLs. A direct header check returned HTTP 200, `Content-Type: image/png`, inline content +disposition, and the recorded byte length for each attachment. + +## Release Use + +The #58 source and native feature-level acceptance record is complete. A future production +candidate must rerun representative sibling-folder and `.fbm` imports, the deliberate override +case, and the broken Source Materials case from the exact nominated commit. This record does not +nominate a candidate or establish production readiness. diff --git a/docs/editor/evaluations/production-readiness/README.md b/docs/editor/evaluations/production-readiness/README.md index 57b05e1..dac63fa 100644 --- a/docs/editor/evaluations/production-readiness/README.md +++ b/docs/editor/evaluations/production-readiness/README.md @@ -1,6 +1,6 @@ # Production-Readiness Acceptance Matrix -**Matrix version:** 0.6 +**Matrix version:** 0.7 **Last audit:** 2026-07-13 @@ -30,14 +30,14 @@ another commit, a dirty worktree, or an older package do not transfer to the can | ID | Requirement | State | Current evidence and gap | |----|-------------|-------|--------------------------| -| G1 | Project create/open/resume, scene authoring, autosave/recovery, hierarchy, prefab, and asset integrity pass | Partial | Project/recovery/session/multi-scene/prefab implementations are documented in [project launcher](../../project-launcher.md), [session recovery](../../session-recovery.md), [multi-scene composition](../../multi-scene-composition.md), and [prefab authoring](../../prefab-authoring.md). Collaborative file safety `#49`, non-blocking native dialogs `#52`, guarded shutdown/savepoints `#55`, scoped UI action safety `#57`, and deterministic asset fingerprints `#56` have feature-level source/native acceptance. #56 additionally passed a fresh LFS checkout, both validators, mtime-only drift, and artifact hash stability at `cbd380a`. Candidate-specific end-to-end reruns remain. | +| G1 | Project create/open/resume, scene authoring, autosave/recovery, hierarchy, prefab, and asset integrity pass | Partial | Project/recovery/session/multi-scene/prefab implementations are documented in [project launcher](../../project-launcher.md), [session recovery](../../session-recovery.md), [multi-scene composition](../../multi-scene-composition.md), and [prefab authoring](../../prefab-authoring.md). Collaborative file safety `#49`, non-blocking native dialogs `#52`, guarded shutdown/savepoints `#55`, scoped UI action safety `#57`, deterministic asset fingerprints `#56`, and [external FBX dependencies](../fbx-external-texture-dependencies/) `#58` have feature-level source/native acceptance. #56 additionally passed a fresh LFS checkout, both validators, mtime-only drift, and artifact hash stability at `cbd380a`; #58 passed both override and blocking dependency states at `3e30c61`. Candidate-specific end-to-end reruns remain. | | G2 | Brush, material, terrain, physics placement, animation, audio, navigation, PIE, and build/package samples pass | Partial | The [five-area sample pack](../sample-regression-pack/) passed source and native acceptance on exact implementation commit `d52cc2e`, including Brush, Material, Terrain, Physics Placement, and Rendering. No release candidate is nominated, brush acceptance `#37` remains open, and combined animation/audio/navigation/PIE/build evidence is incomplete. Packaged testing is owner-deferred. | | G3 | Undo/redo/cancel invariants and helper cleanup cover every production mutation path | Partial | Source implementation and focused evidence are complete in [operator regression testing](../../operator-regression-testing.md) and the [operator-invariants evaluation](../operator-invariants/); Gitea `#33` closed at `c55f347`. A clean, exact-candidate rerun is still required for `Pass`. | | G4 | Representative project completes an eight-hour soak without unbounded memory/target growth or unrecoverable failure | Missing | No candidate soak log, resource timeline, failure ledger, or target-growth measurement exists. | | G5 | Cold start, scene open/save, asset refresh, common manipulation, and package-build budgets are documented and measured | Missing | Gitea `#34` is open; no ratified budgets or candidate measurement record exists. | -| G6 | Headless content validation and CI are green from a clean checkout | Missing | [CI configuration](../../../../.github/workflows/ci.yml) hydrates LFS, runs both project/sample content gates, and asserts a pristine checkout. The [#56 feature run](../deterministic-asset-fingerprints/) passed native startup and both validators from a fresh LFS-hydrated worktree at `cbd380a`, but no release candidate is nominated and no candidate CI run is linked. The current Gitea server does not expose an Actions run endpoint for this repository. | +| G6 | Headless content validation and CI are green from a clean checkout | Missing | [CI configuration](../../../../.github/workflows/ci.yml) hydrates LFS, runs both project/sample content gates, and asserts a pristine checkout. The [#56 feature run](../deterministic-asset-fingerprints/) passed native startup and both validators from a fresh LFS-hydrated worktree at `cbd380a`; [#58](../fbx-external-texture-dependencies/) passed both validators and clean native startup at `3e30c61`. No release candidate is nominated and no candidate CI run is linked. The current Gitea server does not expose an Actions run endpoint for this repository. | | G7 | First-hour UX and recovery QA are signed off by someone other than the implementer | External | No independent sign-off exists. Gitea `#36` remains open; historical H1-H6 implementation-pass notes do not count. | -| G8 | Known limitations have severity/workaround and no P0 blocker remains | Partial | Sample-pack gap `#32`, guarded shutdown/savepoints `#55`, scoped UI action safety `#57`, and deterministic imported-asset fingerprints `#56` have complete feature-level acceptance; no known P0 implementation blocker remains. A consolidated candidate limitations ledger and exact-candidate rerun are still missing. Property-block application `#53` and external FBX dependency handling `#58` are P1; dynamic deformed Solari geometry `#54` is a documented P2 limitation with Forward/raster fallback. | +| G8 | Known limitations have severity/workaround and no P0 blocker remains | Partial | Sample-pack gap `#32`, guarded shutdown/savepoints `#55`, scoped UI action safety `#57`, deterministic imported-asset fingerprints `#56`, and external FBX dependency handling `#58` have complete feature-level acceptance; no known P0 implementation blocker remains. A consolidated candidate limitations ledger and exact-candidate rerun are still missing. Property-block application `#53` remains P1; dynamic deformed Solari geometry `#54` is a documented P2 limitation with Forward/raster fallback. | ## Deliverables @@ -72,6 +72,7 @@ another commit, a dirty worktree, or an older package do not transfer to the can | Guarded shutdown and clean savepoints | Implemented; `#55` source validation and all seven native workflows passed at source implementation `4b33f32` | Feature-level acceptance complete; not rerun as one candidate | | Scoped UI action safety | Implemented; `#57` source validation, six focused regressions, selection precedence, and native toolbar/Inspector/diagnostics workflows passed at `9e23ae7` | Feature-level acceptance complete; not rerun as one candidate | | Imported asset identity and generated artifacts | Implemented; `#56` uses shared BLAKE3 fingerprints, byte-preserving semantic publication, and normalized registry order | Fresh LFS checkout, native startup, mtime-only drift, validators, and artifact hashes passed at `cbd380a`; not rerun as one candidate | +| FBX external texture dependencies | Implemented; `#58` uses one sandboxed resolver, transactional bundle import, labeled loader images, authoritative manifests, and explicit Source Materials/Authoring Override semantics | Sibling/`.fbm`/missing/traversal/symlink tests, both validators, exact-implementation native chair QA, and a controlled broken fixture passed at `3e30c61`; not rerun as one candidate | ## Candidate Validation Commands