Blacksite/docs/editor/collaborative-file-safety.md

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.