docs(sync): define a loss-aware Syncthing conflict-retention policy

[psimaker]

Classification

P1 investigation and safety-decision issue. Raise to P0 only after reproducing loss of unique bytes in a supported user scenario.

Proven starting facts

• New regular folders set MaxConflicts: 10 at go/bridge/folders.go:66-76.
• Accepted pending folders set MaxConflicts: 10 at go/bridge/pendingfolders.go:174-184.
• Generic Syncthing retention removes conflicts above its limit in go/_syncthing_patched/lib/model/folder_sendrecv.go:1839-1875.
• Conflict-on-existing-conflict handling is at go/_syncthing_patched/lib/model/folder_sendrecv.go:1839-1845.
• No .obsidian exception exists in that generic upstream path.
• The separate 2.0.2 .obsidian issue is limited to VaultSync's own AutoResolveStateConflicts mechanism.

These facts prove a retention path, not yet a supported production scenario that loses unique bytes.

Questions and required test matrix

Investigate without choosing a solution in advance:

• MaxConflicts: 10 for newly created and already persisted folders.
• More than ten conflicts of the same file with unique sentinel bytes.
• Conflict on an existing conflict copy.
• Whether any once-unique conflict version becomes unrecoverable.
• MaxConflicts: -1 behavior.
• Disk-full, bounded storage, and unbounded-growth consequences.
• Quarantine or versioning alternatives.
• Existing folder configuration and upgrade behavior.
• Upstream issue/fix versus local policy/patch.
• Honest UI and documentation claims.

User and safety impact

Conflict retention trades recoverability against disk growth. The current repository does not contain a tested, documented policy proving where unique bytes may be discarded or how storage exhaustion is bounded.

Acceptance criteria

• Reproduce each matrix case against the pinned/current supported Syncthing version.
• Record byte identities before and after retention.
• Model finite disk and disk-full behavior.
• Separate upstream semantics, local patches, app configuration, and test-fixture effects.
• Document behavior of existing persisted folders.
• Produce a reviewed safety decision before implementation.
• State UI/documentation guarantees narrowly and truthfully.
• Do not raise to P0 without the required supported-scenario reproduction.

Minimal regression tests

Isolated real-Syncthing tests with >10 unique conflict sentinels, conflict-on-conflict, MaxConflicts -1, existing config reload, restart, bounded disk/disk-full injection where practical, and exact survivor/deletion inventory.

Out of scope

Any 2.0.2 code change, immediate MaxConflicts modification, folder_sendrecv.go patch, unapproved Syncthing upgrade, general Bridge redesign, and predetermined quarantine/versioning solution.

Verification

Pinned upstream/version/patch inventory; focused tests; full race output if used; disk model; upstream source/issue comparison; reviewed Decision Record before implementation.

Dependencies

• Related to, but does not block, the scoped 2.0.2 issue disabling VaultSync's explicit .obsidian resolver.
• Gates 3.0 safety claims.
• Any implementation requires smaller separately approved child issue(s).

[psimaker]

2.0.2 Candidate eb83ade reproduces loss of one unique conflict sentinel at MaxConflicts=10. After the
boundary divergence, an unchanged same-home restart produced two stable identical inventories with 11 of 12 prior
sentinel versions; identity and config remained stable and no crash occurred. Treating this as release-blocking
pending a separately approved loss-aware policy and RED/fix plan.