# Source-Control Status And Collaborative File Safety

> **Historical plan — not current implementation guidance.** Use the [documentation index](../../docs/README.md) for current behavior and architecture.

Working implementation plan for Gitea issue
[`#49`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/49).
This is the final M7 implementation slice before the production-readiness acceptance gate.

## Status

Implementation, focused source tests, full editor tests, strict editor clippy, and headless checks
are complete. Live debug-editor visual acceptance remains pending for a desktop-capable QA session.
Packaged/release acceptance is explicitly deferred until the project owner requests another
packaged pass.

## Outcome

External edits cannot be silently overwritten by the editor, common Git/read-only/ownership states
are visible without dominating the shell, and projects without Git or an ownership provider behave
normally.

## Implementation Sequence

1. Add exact file revisions, comparison metadata, guarded atomic replacement, and deterministic
   pre-rename race coverage.
2. Capture baselines for scene tabs, material/material-instance drafts, and Project Settings;
   protect prefab source Apply and exact-file undo/redo with the same guard.
3. Add a non-destructive asynchronous Git scanner and optional ownership-provider registry.
4. Add compact active-scene and selected-asset status plus a recovery modal with reload, compare
   metadata, save-as, and cancel.
5. Cover missing/present/read-only/external-change races, porcelain parsing, provider absence, and
   document-specific conflict recovery with focused source tests.
6. Run format, strict affected-crate clippy, source tests, headless validation, and live debug-editor
   QA. Do not run packaged tests until requested by the project owner.

## Acceptance Gates

- A loaded authored file changed by another process is never replaced by Save, Apply to source, or
  prefab source history.
- File creation is also conditional: a file that appears after a save-as baseline is captured is
  not overwritten.
- Conflict and read-only UI identifies the path and recovery choices without a force-overwrite
  escape hatch.
- Active-scene and selected-asset Git status remain compact and explain themselves on hover.
- Git absence, a non-repository project, and an empty provider registry are quiet normal states.
- Git commands are read-only and never alter index, worktree, commits, branches, or locks.
- Provider state can block an authored write without coupling core editor code to a vendor.
- Source tests simulate a writer changing the target immediately before rename and prove the old or
  external content survives.

## Deliberate Boundaries

- Generated registries, imports, thumbnails, navigation bakes, recovery snapshots, and packages are
  regenerative/system-owned and do not open authored-file recovery UI.
- V1 compares metadata rather than rendering a text diff; external diff-tool integration is future
  work.
- V1 observes ownership/locks. Acquiring, releasing, or stealing locks belongs in a provider-specific
  follow-up.
- Git status is project-local and advisory. The content revision guard remains authoritative even
  when Git is absent or stale.