# 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).

Live editor acceptance, including external-change detection, metadata comparison, cancel/reload
invariants, and source-control status, is recorded in the
[collaborative file-safety evaluation](evaluations/collaborative-file-safety/).