Defines a three-way conflict model for collaborative records, preserving base, local intent, and current remote state while distinguishing mergeable fields from invariants that require a user decision.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Detect conflicts with an explicit base version. Auto-merge only fields whose merge policy is deterministic and invariant-safe; otherwise preserve both edits, show meaningful differences, and commit the user's resolution as a new version.
Scope
- Record versions, local drafts, remote changes, conflict identity, field merge policies, user choices, commit, retries, offline work, and audit.
- Structured collaborative records with optimistic concurrency.
- Single-record conflict resolution; real-time text CRDTs are alternatives.
Outside this block
- Silently applying last-write-wins to user-authored content.
- A generic line diff for every data type.
Contract
- A save carries record ID, base version, patch or local state, actor, and command identity.
- Conflict response includes the authorized base/local/current comparison needed for resolution and a current version token.
- Each field declares merge policy: independent, set union with identity, ordered list, derived, or manual.
- Auto-merge never violates cross-field invariants or resurrects a deleted/unauthorized object.
- Resolution choices are field-specific and preview the final record before commit.
- The resolved commit compares against the current version again and creates a new auditable version.
Implementation guidance
- Keep a bounded base snapshot or invertible patch for active drafts.
- Use domain renderers for dates, memberships, rich text, and deleted references.
- Assign stable identities to list items so reorder, edit, and delete are distinguishable.
- For offline clients, retain drafts until synchronization and report conflicts rather than discarding them.
Failure handling and safeguards
- If the record changes again during resolution, rebase the proposed resolution and surface new conflicts.
- If access to a conflicting field is revoked, conceal its value and require an authorized path.
- If base history expired, return a safe full-review workflow rather than guessing a merge.
Verification and operations
- Measure conflict rate, auto-merge rate, manual fields, abandonment, repeated conflicts, resolution time, and post-resolution undo/correction.
- Test concurrent edit/edit, edit/delete, list reorder, authorization change, and offline replay.
- Review high-conflict fields for boundary or interaction redesign.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.
References
- No external normative source is required; this package defines a project decision.