This commit is contained in:
1 parent
9a67a25a15
commit
1ab3886028
24 files changed
+1836
-311
No files matched your search
@@ -91,6 +91,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
|
||||
| [editor/evaluations/physics-placement/](editor/evaluations/physics-placement/) | Live screenshot and acceptance results for physics settling, cancel, commit, undo, and redo |
|
||||
| [editor/evaluations/collider-diagnostics/](editor/evaluations/collider-diagnostics/) | Live screenshot and acceptance results for collider overlays, diagnostics, shape history, and placement preflight |
|
||||
| [editor/evaluations/navigation-authoring/](editor/evaluations/navigation-authoring/) | Live screenshots and acceptance results for navigation authoring and runtime parity |
|
||||
| [editor/evaluations/operator-invariants/](editor/evaluations/operator-invariants/) | Source acceptance results for production operator lifecycle, rollback, cleanup, and undo/redo invariants |
|
||||
| [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)
|
||||
@@ -114,6 +115,7 @@ Detailed milestone and feature plans live in [`.cursor/plans/`](../.cursor/plans
|
||||
| `production_readiness_acceptance_*.plan.md` | Release-candidate evidence matrix, blocker sequence, clean-checkout checks, soak, budgets, and independent sign-off |
|
||||
| `material_library_and_targeted_drop_*.plan.md` | Dedicated Material Library, exact viewport slot/primitive/brush targeting, hover preview, cancel, and grouped history |
|
||||
| `terrain_material_layers_*.plan.md` | Terrain shared-material layers, normalized weights, blended hydration, and modal painting |
|
||||
| `operator_invariants_completion_*.plan.md` | Production operator dispatch, interruption, rollback, cleanup, and undo/redo acceptance |
|
||||
|
||||
## Crate responsibilities (quick reference)
|
||||
|
||||
|
||||
@@ -39,6 +39,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
|
||||
| [evaluations/physics-placement/](evaluations/physics-placement/) | Live screenshot and verification record for multi-prop settling, cancel, commit, undo, and redo |
|
||||
| [evaluations/collider-diagnostics/](evaluations/collider-diagnostics/) | Live screenshot and verification record for semantic collider overlays, health linking, shape switching, and placement reuse |
|
||||
| [evaluations/navigation-authoring/](evaluations/navigation-authoring/) | Live screenshots and verification record for navigation authoring and runtime parity |
|
||||
| [evaluations/operator-invariants/](evaluations/operator-invariants/) | Source acceptance record for production operator lifecycle, rollback, cleanup, and undo/redo invariants |
|
||||
| [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)
|
||||
|
||||
@@ -245,13 +245,16 @@ the Edit-to-Play boundary restore the complete runtime snapshot. See
|
||||
|
||||
Structural edits (spawn, delete, transform, rename) go through `EditorHistory` command objects in `history.rs`.
|
||||
User-facing actions route through the operator lifecycle in `operators.rs`: begin, preview,
|
||||
commit, cancel, disabled reason, and status text. The first bridge wraps command-palette and queued
|
||||
editor commands as immediate operators, while existing `EditorHistory` commands remain the undo
|
||||
payload. Asset placement, mesh-subasset placement, texture apply, and material apply actions now
|
||||
use immediate operators from `assets::operators`; texture/material changes across a selection use
|
||||
one `SetMaterialGroup` command. Draw Brush, brush CSG, clip, and element gizmo paths publish the
|
||||
same preview/commit/cancel phases. `operators/test_harness.rs` verifies authored deltas, dirty
|
||||
state, helper cleanup, undo grouping, and undo/redo restoration; see
|
||||
commit, cancel, disabled reason, stable ID, and status text. Registered commands return typed
|
||||
`OperatorAction::Commit` or `OperatorAction::ContinuePreview`, so immediate commands finish while
|
||||
Draw Brush and CSG retain modal Preview ownership; validation failures terminate instead of leaving
|
||||
stale status. Existing `EditorHistory` commands remain the undo payload. Group Selection is one
|
||||
atomic command that remaps its transient group identity on every redo without reparenting unrelated
|
||||
siblings. Lighting reset and Project Sun changes use one grouped light command. Asset placement,
|
||||
assignment, exact material drops, brush tools, terrain strokes, physics placement, and the real
|
||||
transform tracker all publish terminal lifecycle state. `operators/test_harness.rs` verifies semantic
|
||||
projections, dirty-state preservation, stable IDs, helper cleanup, undo grouping, repeated undo/redo,
|
||||
and automatic interruption rollback; see
|
||||
[operator-regression-testing.md](operator-regression-testing.md).
|
||||
|
||||
PIE stop restores player simulation state only; authored `LevelObject` edits made during PIE remain in the scene.
|
||||
|
||||
@@ -10,6 +10,7 @@ Living checklist for the production editor program ([ADR 0012](../adr/0012-zero-
|
||||
| Monolithic `hydrate_authoring_entities` | Done | `crates/shared/src/hydration/*` modules |
|
||||
| Optional / inferred `ActorKind` as long-term save path | Done | Schema v2 + migration; save validates |
|
||||
| Hydrated components in committed `.scn.ron` | CI | `scene::validate_scene_authoring_only` + `repo_editor_scene_has_no_hydrated_components` |
|
||||
| Production mutation without commit/cancel/failure/undo invariants | Done | Shared operator harness plus typed history projections cover palette, asset, brush, terrain, physics, grouping, lighting, material-drop, and transform paths; see [evaluation](evaluations/operator-invariants/) |
|
||||
| Dual FBX thumbnail ad-hoc path (parallel to unified pipeline) | Partial | Phase 5 `assets/thumbnails/` refactor |
|
||||
| `failed_keys` thumbnail cache without retry API | Partial | `asset_thumbnails.rs`; Phase 5 `ThumbnailState` |
|
||||
|
||||
@@ -21,7 +22,7 @@ Living checklist for the production editor program ([ADR 0012](../adr/0012-zero-
|
||||
| P1 | `ActorKind` required; `validate_actor` on save |
|
||||
| P2 | No runtime components in default inspector |
|
||||
| P3 | `HierarchySiblingIndex`; no undefined sibling order |
|
||||
| P6 | `ActorInspectorSection` registry; command palette commands; BRP authoring policy |
|
||||
| P6 | `ActorInspectorSection` registry; typed immediate/modal command dispatch; BRP authoring policy; production mutation invariants |
|
||||
| P7 | ADRs 0009–0012 indexed; CI `shared` + `scene` + `editor` checks |
|
||||
|
||||
## Manual verification (release)
|
||||
@@ -29,3 +30,4 @@ Living checklist for the production editor program ([ADR 0012](../adr/0012-zero-
|
||||
- [ ] R1–R6 rendering/inspector scenarios ([roadmap.md](roadmap.md))
|
||||
- [ ] Save/load roundtrip: hierarchy, lights, materials unchanged
|
||||
- [ ] PIE 60s stop: project lighting profile unchanged unless scene overrides edited
|
||||
- [ ] Rerun the [operator invariant matrix](operator-regression-testing.md) from the nominated release-candidate commit
|
||||
@@ -0,0 +1,45 @@
|
||||
# Operator Invariants Evaluation
|
||||
|
||||
Date: 2026-07-12
|
||||
|
||||
Gitea issue:
|
||||
[`#33`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/33)
|
||||
|
||||
This acceptance record covers the source-level production operator contract. It does not nominate a
|
||||
release candidate or replace the clean-checkout rerun required by production-readiness gate G3.
|
||||
|
||||
## Accepted Coverage
|
||||
|
||||
- Registered commands distinguish immediate completion from modal Preview ownership; validation
|
||||
failures terminate with their stable command ID.
|
||||
- Group Selection is one history transaction and preserves unrelated hierarchy rows through repeated
|
||||
undo/redo even though the transient group entity is respawned.
|
||||
- Reset Lighting and Project Sun changes are grouped, undoable light transactions.
|
||||
- Asset/sub-asset placement; material/texture/audio/animation assignment; and exact viewport material
|
||||
drops cover commit, block/failure, cancel where applicable, and semantic undo/redo projections.
|
||||
- Draw Brush, CSG, clip, and element-gizmo paths exercise production modal finalizers and helper
|
||||
cleanup.
|
||||
- Terrain sculpt/paint cover multi-dab commit, failure rollback, cancel, clean-view interruption, and
|
||||
resource cleanup.
|
||||
- Physics placement covers prerequisite block, exact cancel, real settle commit, multi-selection
|
||||
grouping, helper cleanup, undo, and redo.
|
||||
- The transform tracker covers continuous multi-target grouping and no-op release termination.
|
||||
|
||||
## Verification
|
||||
|
||||
The publication worktree passed:
|
||||
|
||||
- `cargo test -p editor --lib --no-fail-fast`: 245 passed, 0 failed.
|
||||
- `cargo clippy -p editor --lib --tests -- -D warnings`.
|
||||
- `cargo fmt --all -- --check`.
|
||||
- `cargo test --workspace --all-targets --no-fail-fast`.
|
||||
- `cargo clippy --workspace --all-targets -- -D warnings`.
|
||||
- `cargo validate-levels --project .`: 62 dependencies, 5 expected non-blocking findings, 0 blocking
|
||||
errors.
|
||||
|
||||
The Gitea closure comment records these results with the exact publication commit.
|
||||
|
||||
No screenshot is required for this ticket: the accepted surface is lifecycle, rollback, cleanup, and
|
||||
history behavior exercised through headless production entry points. Live command/status checks add
|
||||
confidence but are not substituted for semantic assertions. Packaged-runtime testing remains
|
||||
deferred by project-owner request.
|
||||
@@ -32,12 +32,12 @@ another commit, a dirty worktree, or an older package do not transfer to the can
|
||||
|----|-------------|-------|--------------------------|
|
||||
| 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` and non-blocking native dialogs `#52` passed live acceptance. Candidate-specific end-to-end reruns remain. |
|
||||
| G2 | Brush, material, terrain, physics placement, animation, audio, navigation, PIE, and build/package samples pass | Fail | Animation, audio, navigation, renderer/material foundation `#51`, Material Library, targeted material drops, terrain `#22`-`#24`, physics placement `#25`, and build foundations are implemented with source/live fixtures. Brush acceptance `#37` remains incomplete. Packaged testing is owner-deferred. |
|
||||
| G3 | Undo/redo/cancel invariants and helper cleanup cover every production mutation path | Partial | The reusable harness and current tool coverage are documented in [operator regression testing](../../operator-regression-testing.md). Terrain stroke and physics settle/cancel/undo fixtures now exist; Gitea `#33` remains open for full mutation-path coverage. |
|
||||
| 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` is ready to close. 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) exists and local source/headless checks have passed during feature work, but no clean-checkout candidate 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 | Fail | Limitations are distributed across feature docs rather than one candidate ledger. Open P0 work includes `#32` and `#33`; `#50` cannot close while a gate-relevant P0 remains. Renderer foundation `#51`, roadmap audit `#35`, Material Library `#16`, targeted drops `#18`, collaborative safety `#49`, and dialog responsiveness `#52` are closed. Property-block application `#53` is 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 | Fail | Limitations are distributed across feature docs rather than one candidate ledger. The remaining open P0 implementation blocker is `#32`; `#50` cannot close while it remains. Operator invariants `#33`, renderer foundation `#51`, roadmap audit `#35`, Material Library `#16`, targeted drops `#18`, collaborative safety `#49`, and dialog responsiveness `#52` are complete. Property-block application `#53` is P1; dynamic deformed Solari geometry `#54` is a documented P2 limitation with Forward/raster fallback. |
|
||||
|
||||
## Deliverables
|
||||
|
||||
|
||||
@@ -11,11 +11,13 @@ Every production operator test must cover the paths it exposes:
|
||||
|
||||
| Path | Required proof |
|
||||
|------|----------------|
|
||||
| Commit | Expected authored entity delta, exact undo-group delta, dirty state, committed phase |
|
||||
| Cancel or commit failure | No authored entity delta, no new history, prior dirty state, canceled phase |
|
||||
| Commit | Expected authored projection, exact undo-group delta, dirty state, stable operator ID, committed phase |
|
||||
| Zero-history commit | Authored projection and prior dirty state remain unchanged |
|
||||
| Cancel or commit failure | Exact authored projection restored, no new history, prior dirty state, stable operator ID, terminal canceled/blocked phase |
|
||||
| Blocked start | Commit closure never runs; authored state, history, and dirty state are unchanged |
|
||||
| Preview failure | Cancel finalizer runs, authored state is restored, and helpers are removed |
|
||||
| Preview helpers | No helper component remains after commit or cancel |
|
||||
| Undoable commit | `assert_undo_redo_round_trip` restores both initial and committed projections |
|
||||
| Undoable commit | `assert_undo_redo_round_trip` restores both initial and committed semantic projections |
|
||||
| Continuous edit | The entire interaction creates one history command, not one per frame or target |
|
||||
|
||||
The harness intentionally fails with the invariant name in the assertion message. Tests may add
|
||||
@@ -26,12 +28,12 @@ domain assertions, but should not replace these shared lifecycle checks.
|
||||
1. Build a minimal `World` with `ActiveOperator`, `EditorHistory`, and `SceneIo`. Add tool-specific
|
||||
selection/resources and `SelectedEntity` when history helpers update selection.
|
||||
2. Capture `OperatorInvariantHarness` immediately before starting the operation.
|
||||
3. Run the real operator entry point or the same production commit/cancel function used by its
|
||||
input system.
|
||||
3. Run the real dispatch path or production finalizer used by the input system. Do not duplicate its
|
||||
state transition in the test.
|
||||
4. Call `assert_committed`, `assert_canceled`, or `assert_blocked` with the expected authored and
|
||||
undo deltas.
|
||||
undo deltas, then `assert_status` with the stable operator ID and terminal phase.
|
||||
5. For helpers, call `assert_no_helpers::<ToolHelper>`. For undoable work, project the meaningful
|
||||
state through `assert_undo_redo_round_trip`.
|
||||
state through `assert_undo_redo_round_trip`; use `assert_projection_unchanged` for no-op paths.
|
||||
|
||||
Do not satisfy a lifecycle test by constructing an `EditorCommand` and checking only its label.
|
||||
The test must mutate a world and prove restoration.
|
||||
@@ -40,15 +42,17 @@ The test must mutate a world and prove restoration.
|
||||
|
||||
| Workflow | Coverage |
|
||||
|----------|----------|
|
||||
| Generic `EditorOperator` | Commit cleanup, commit failure rollback, blocked no-op |
|
||||
| Asset placement | Commit, dirty state, single undo, authored spawn round trip |
|
||||
| Sub-asset placement | Missing dependency commit failure leaves no side effects |
|
||||
| Texture/material assignment | Multi-actor grouped undo; missing material failure; empty-selection block |
|
||||
| Draw Brush | Full modal-state cancel; decomposed multi-brush grouped commit and round trip |
|
||||
| Brush CSG | Pending-preview cancel; merge commit/deletion grouped round trip |
|
||||
| Brush clip and element gizmo | Clip grouped geometry round trip; Escape rollback and helper cleanup |
|
||||
| Transform gizmo finalization | Multi-target continuous edit grouped into one undo command |
|
||||
| Generic `EditorOperator` | Commit cleanup, preview/commit failure rollback, blocked no-op, terminal ID/phase |
|
||||
| Palette and registered commands | Typed immediate commit versus modal preview ownership; failed CSG start terminates |
|
||||
| Selection and scene commands | Atomic Group Selection across repeated undo/redo; grouped Reset Lighting and Project Sun history |
|
||||
| Asset workflows | Asset/sub-asset placement; material/texture group assignment; audio/animation assignment and incompatible targets |
|
||||
| Viewport material drop | Exact renderer slot/primitive/brush-face preview, cancel, commit, cleanup, undo, and redo |
|
||||
| Draw Brush and CSG | Modal cancel; decomposed commit; CSG validation/read-only block, cancel, grouped commit, and deleted-brush restoration |
|
||||
| Brush clip and element gizmo | Production finalizers, geometry round trip, Escape rollback, and helper cleanup |
|
||||
| Terrain sculpt and paint | Multi-dab grouped commit, no-op release, commit failure rollback, cancel, clean-view interruption, and resource cleanup |
|
||||
| Physics placement | Prerequisite block, no-op commit, exact cancel, real settle commit, multi-selection grouping, helper cleanup, undo, and redo |
|
||||
| Transform gizmo finalization | Actual tracker finalizer, continuous multi-target grouping, no-op release, and missing-primary survivor rollback |
|
||||
|
||||
Terrain strokes and physics-settle sessions are roadmap tools, not current production operators.
|
||||
Their implementation tickets must add harness fixtures before those tools can pass their own exit
|
||||
gates; Gitea issue BS-JD-502 remains the umbrella until that coverage exists.
|
||||
The shared harness covers formal operators and multi-frame modal paths. Atomic inspector and history
|
||||
mutations that do not own `ActiveOperator` use focused typed history tests with equivalent semantic
|
||||
projection and undo/redo assertions.
|
||||
@@ -134,6 +134,7 @@ Phased work for the in-process editor (`crates/editor`). Status reflects the cur
|
||||
| `ActorInspectorSection` registry | Done | `ext/extensibility.rs` + `game_inspector.rs` |
|
||||
| Command registry | Done | Play, lighting reset, group, focus |
|
||||
| Command palette (Ctrl+P) | Done | Executes registered commands |
|
||||
| Typed operator dispatch and mutation invariants | Done | Immediate commands commit, modal commands retain Preview ownership, and production asset/brush/terrain/physics/history paths pass the shared lifecycle and undo contract ([testing guide](operator-regression-testing.md), [Gitea #33](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/33)) |
|
||||
| `EditorPlugin` trait | Done | `register_editor_plugin`; dogfood panel from `game::editor_ext` |
|
||||
| Undo: `SetActorKind`, add/remove component | Done | `SetActorKind` + `AddComponent` / `RemoveComponent` |
|
||||
| BRP authoring-only policy | Done | [brp.md](brp.md) |
|
||||
|
||||
Reference in new issue
Block a user