Add collaborative authored-file safety

This commit is contained in:
Rbanh committed 2026-07-12 11:27:57 -04:00
1 parent b4aa61e394
commit 5a82a9ee29
23 files changed
+2857 -89

No files matched your search

+3
View File
@@ -23,6 +23,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
| [navigation-authoring.md](navigation-authoring.md) | Bounds, source geometry, deterministic bake, viewport path preview, and runtime query workflow |
| [extensibility.md](extensibility.md) | Static authoring component lifecycle registration, stable IDs, composition, and generic history |
| [material-system.md](material-system.md) | Shared Material/Material Instance assets, static/skinned renderer slots, Surface ABI, Solari scope, and migration |
| [collaborative-file-safety.md](collaborative-file-safety.md) | Exact authored-file revisions, Git/read-only status, conflict recovery, and optional ownership providers |
| [evaluations/material-renderer-foundation/](evaluations/material-renderer-foundation/) | Live screenshots and verification record for the renderer/material/component foundation |
| [evaluations/navigation-authoring/](evaluations/navigation-authoring/) | Live screenshots and verification record for navigation authoring and runtime parity |
@@ -43,6 +44,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
| `assets/` | Catalog, asset DB, static mesh artifacts, `thumbnails/`, `materials.rs`, prefab overrides v2 | this file (below), prefab-authoring.md, ADR 0017, ADR 0027 |
| `shared::prefab_overrides` | Versioned stable override schema and editor-independent runtime application | prefab-authoring.md, ADR 0027 |
| `project/` | Workspace, settings UI, user prefs, support diagnostics | roadmap Phase 1 |
| `project/collaboration.rs` | Guarded authored writes, asynchronous Git status, and optional ownership providers | collaborative-file-safety.md, ADR 0037 |
| `project/session.rs` | Versioned XDG session document, clean marker, and safe resume | session-recovery.md, ADR 0024 |
| `project/diagnostics_bundle.rs` | Privacy-bounded transactional support report export | session-recovery.md, ADR 0024 |
| `project/launcher.rs` | Strict project inspection, CLI activation, recent filtering, and sandbox scaffolding | project-launcher.md, ADR 0025 |
@@ -86,6 +88,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
components on load and component transactions, and does not prohibit compatible composition such
as renderer plus light. Component validation owns requirements and geometry-source conflicts.
- **Scene persistence and recovery** use transactional same-directory writes for authored scenes and bounded user-local recovery snapshots for dirty saved scenes. Recovery runs every 120 seconds by default, keeps five generations, never marks the scene clean, and appears as a status/File-menu restore or discard action when newer than the authored file. Restore leaves the original scene dirty until manually saved. See [ADR 0023](../adr/0023-transactional-scene-persistence-and-recovery.md).
- **Collaborative file safety** records exact content revisions for loaded scenes, prefab source operations, editable materials, and Project Settings, then rechecks them immediately before atomic publication. External changes, create races, read-only files, and optional ownership locks keep the existing bytes intact and open Reload/Compare Metadata/Save As/Cancel recovery. Git status is asynchronous, observational, and absent without noise outside a repository. See [collaborative-file-safety.md](collaborative-file-safety.md) and [ADR 0037](../adr/0037-collaborative-authored-file-safety.md).
- **Scene visualizers** expose actor root icons, colliders, lights, player spawns, gameplay markers, volumes, prefab/model anchors, Project Sun, and runtime player/camera markers without changing saved scene data. Spot lights show inner/outer cones and cameras show near/far frusta. Viewport options independently gate visualizer categories and include actor icon and transform-gizmo size sliders.
- **Clean game-view overlay** (`G`) hides editor chrome, grid, selection outlines, transform gizmos, actor root icons, visualizers, and selectable proxies without changing camera ownership; `Ctrl+G` toggles grid.
- **Viewport shading** (toolbar): **Lit** (default WYSIWYG), **Unlit** (base-color debug), **Colliders** (hide meshes, emphasize collider gizmos). The viewport combines active shading/render path in one bottom-right chip, draws a camera-relative X/Y/Z orientation widget, identifies the primary selection in a responsive top-right HUD, and previews asset placement with a pointer card, placement reticle, corner brackets, and highlighted drop boundary.
+12 -2
View File
@@ -29,6 +29,7 @@ Native-only dependencies (`rfd`, BRP HTTP) stay in `editor`. `settings`, `shared
| `ActorIconsPlugin` | Selectable actor root billboard icons |
| `EditorVisualizersPlugin` | Collider/light/spawn/prefab/runtime visualizers and selectable proxies |
| `SceneIoPlugin` | Level New/Open/Save, recent paths |
| `CollaborationPlugin` | Exact authored-file guards, asynchronous Git status, optional ownership providers |
| `OperatorPlugin` | Active operator lifecycle/status for commands and modal tools |
| `SettingsUiPlugin` | egui Project Settings panel |
| `EditorUiPlugin` | Dock, themed egui shell, viewport overlays, menus, status bar |
@@ -76,6 +77,15 @@ The bounded in-session scene I/O event log feeds the Diagnostics window so a lat
does not erase a save or recovery failure.
See [ADR 0023](../adr/0023-transactional-scene-persistence-and-recovery.md).
`project/collaboration.rs` wraps user-authored publication with BLAKE3 baselines and a second
revision/read-only check immediately before the same-directory rename. Scene tabs, prefab source
Apply/history, staged Material documents, and Project Settings use this shared boundary. Its worker
observes path-scoped Git porcelain and optional ownership providers without blocking the frame loop
or changing repository state; conflict recovery is explicit Reload, metadata comparison, Save As,
or Cancel. Generated artifacts remain under their subsystem-owned regeneration policy. See
[collaborative-file-safety.md](collaborative-file-safety.md) and
[ADR 0037](../adr/0037-collaborative-authored-file-safety.md).
`project/session.rs` owns the independent versioned restart document under the user state
directory. It snapshots allowlisted paths, panel visibility, dock/hierarchy metadata, and camera
bookmarks, writes a running marker at startup, and records clean `AppExit`. Abnormal sessions do
@@ -151,7 +161,7 @@ The egui layer lives under `crates/editor/src/ui/`:
| `diagnostics.rs` | Detailed stats (Window → Diagnostics, Asset Browser footer) |
| `layout.rs` | Dock layout RON persistence in `editor_prefs.ron` |
The Viewport fills the tab (no inline help text). Gizmo/grid/play controls sit on a near-black semi-transparent overlay, and `G` hides editor-only overlays for a clean game view. The fixed dark status strip prioritizes `SceneIo.status` feedback and also shows scene path/dirty state, mode, selection count, history, and the active operator. Long feedback is truncated responsively and available in a hover tooltip. Dock layout restores from `~/.config/bevy-fps/editor_prefs.ron` on startup; **View → Reset Layout** restores defaults.
The Viewport fills the tab (no inline help text). Gizmo/grid/play controls sit on a near-black semi-transparent overlay, and `G` hides editor-only overlays for a clean game view. The fixed dark status strip prioritizes `SceneIo.status` feedback and also shows scene path/dirty state, compact active-file collaboration status, mode, selection count, history, and the active operator. Long feedback is truncated responsively and available in a hover tooltip. Dock layout restores from `~/.config/bevy-fps/editor_prefs.ron` on startup; **View → Reset Layout** restores defaults.
**Follow-up (Phase 4b):** inspector search and richer per-asset previews.
@@ -247,7 +257,7 @@ PIE stop restores player simulation state only; authored `LevelObject` edits mad
| `viewport/` | Camera, selection, gizmos, render views, panel settings |
| `play/` | PIE session, editor mode, net editor profiles |
| `assets/` | Catalog, asset DB, static mesh artifacts, prefab overrides |
| `project/` | Project I/O and settings UI |
| `project/` | Project I/O, settings UI, authored-file safety, and observational collaboration status |
| `ext/` | Command palette, BRP, game panel adapters |
| `history/` | Undo commands + plugin |
| `ui/` | egui dock shell |
+58
View File
@@ -0,0 +1,58 @@
# Collaborative File Safety
Blacksite protects loaded user-authored documents with exact content revisions. This layer covers
scene and prefab documents, editable Material and Material Instance assets, and `assets/project.ron`.
Generated import artifacts, registries, thumbnails, navigation bakes, recovery snapshots, and package output keep
their subsystem-owned regeneration rules and never interrupt editing with authored-file conflicts.
## Status Surfaces
The bottom status strip shows a compact state for the active saved scene. The selected asset's
Details header shows the same state when the asset has an on-disk source. Hover either indicator for
the path, Git state, read-only state, ownership detail, and scanner diagnostics.
When Git is available, Blacksite distinguishes clean, modified, untracked, and conflicted files.
The path-scoped scanner uses only `rev-parse` and NUL-delimited `status --porcelain`; it never
stages, commits, resets, checks out, restores, or discards files. A missing Git executable or
project outside a repository is a normal quiet state.
## Save Conflicts
On load, the editor records a BLAKE3 revision and file metadata. Save verifies that revision before
preparing the atomic replacement and again immediately before rename. A changed, newly created, or
read-only target remains untouched and opens the collaborative-file dialog.
The dialog provides:
- **Reload**: discard the editor draft for that document and load the current disk revision.
- **Compare Metadata**: show expected/current revision, byte size, modified time, and permissions.
- **Save As**: preserve the editor draft at a separately chosen path, guarded against a create race.
- **Cancel**: keep the editor draft and make no filesystem change.
There is intentionally no force-overwrite action. Resolve or preserve the other revision first.
## Ownership Providers
Teams can register an implementation of `FileOwnershipProvider` with
`register_file_ownership_provider`. Providers receive the active project root and a bounded list of
currently tracked project-relative paths on the background scan worker. They return owner/lock
details per path.
A lock held by another user blocks authored publication and uses the same recovery dialog. Provider
errors appear only in indicator details; the exact filesystem revision guard continues to work. An
empty provider registry performs no calls and adds no UI.
## Recovery Notes
- Scene Reload explicitly replaces the active dirty document with disk content and clears its local
history. Use Save As first when both versions matter.
- Material Reload discards only the staged Details draft and reloads the asset on the next draw.
- Project Settings Reload strictly parses the current manifest, reapplies it live, and refreshes the
panel draft; invalid external RON stays blocked and visible.
- Prefab Apply conflicts keep instance overrides intact. Reload tears down stale hydration and
queues the current source for rehydration; retry Apply after reviewing Changed Base/conflict
state, or Save As to preserve the proposed source copy.
- Prefab source undo/redo stays blocked when the exact expected source revision is absent.
The architectural policy is recorded in
[ADR 0037](../adr/0037-collaborative-authored-file-safety.md).
+1 -1
View File
@@ -147,7 +147,7 @@ with implementation sequencing in
| Milestone | Exit condition | Status |
|-----------|----------------|--------|
| M6 Reliability, recovery, and project workflow | Transactional save/recovery, stable sessions, project launcher, hardened hierarchy/prefabs, multi-scene composition | Implementation complete; all six scoped issues are closed after prefab #43 passed workspace, headless, packaged-runtime, and live editor acceptance |
| M7 Content production and shipping | Build/package profiles, content release gate, animation, audio, navigation, collaborative safety | Active; #44-#48 are complete. Source-control safety #49 and final readiness gate #50 remain; packaged acceptance is deferred until requested by the project owner. |
| M7 Content production and shipping | Build/package profiles, content release gate, animation, audio, navigation, collaborative safety | Active; #44-#48 are complete. #49 implementation and source/headless acceptance are complete, with live visual acceptance pending; final readiness gate #50 remains. Packaged acceptance is deferred until requested by the project owner. |
Production readiness is not inferred from feature count. Gitea
[`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50)