Complete editor operator invariants
CI / Format, lint, test, build (push) Waiting to run

This commit is contained in:
Rbanh committed 2026-07-12 23:53:46 -04:00
1 parent 9a67a25a15
commit 1ab3886028
24 files changed
+1836 -311

No files matched your search

+1
View File
@@ -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)
+10 -7
View File
@@ -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.
+3 -1
View File
@@ -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
+22 -18
View File
@@ -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.
+1
View File
@@ -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) |