59 lines
3.2 KiB
Markdown
59 lines
3.2 KiB
Markdown
# 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).
|