PartialJoin trait abstracting fallible merge operations

PartialJoin<V>::try_join returns JoinResult<V>, either Ok(v), where v
the least upper bound, or a Err(Conflict<V>) where the conflict contains
values that could not be joined.

Conflict<V> is a multiset with set-equality semantics (order-independent).
It implements JoinMut to merge conflict sets (union of distinct values).

JoinResult<V> itself implements Join:

  (Ok(a), Ok(b))   => a.try_join(b)      (delegate to PartialJoin on V)
  (Ok(v), Err(c))  => Err(c ∪ {v})       (absorb into conflict)
  (Err(c), Ok(v))  => Err(c ∪ {v})       (absorb into conflict)
  (Err(a), Err(b)) => Err(a ∪ b)         (join conflict sets)

Containers or product types that wrap their fields in JoinResult<V> can
implement Join recursively to compute the field-by-field merge without
early exit.

assert_partial_join_laws! is a crate-internal macro (gated behind
prop-tests feature, scoped via #[macro_use]). Given clean-value and
result strategies, it generates try_join law tests, JoinResult law tests
(via assert_join_laws!), and a wrap roundtrip test.

## Rationale for Conflict as flat, order preserving & order insensitive

Conflicts represent a formal completion of the partial semilattice `V :
PartialJoin`. If `a` and `b` are conflicts, commutativity requires that
`a.join(b) == b.join(a)`, and idempotence requires that `a.join(a) ==
a`. This is somewhat at odds with keeping track of where each
conflicting value originated from.

The main purpose of preserving the order is to allow provenance to be
tracked.

If `a` and `b` are both conflict free, and `let c = a.join(b)`, then
`c.conflicted_field.len() == 2` and the first value is from `a` whereas
the second is from `b`, which makes reporting this as an error with
clear diagnostics easier, without requiring the provenance be tracked by
some kind of surrogate ID.

This does not generalize to n > 2, because if
`a.join(b).join(c).some_conflicted_field.len() == 2`, the values could
originate from `(a, b)`, `(b, c)`, or `(a, c)`.

This compromise keeps the interface and implementation simple, allows
provenance to be tracked as long as it's done one pair of values at a
time in a straightforward way, but imposes no additional burdens on
users that do not care about provenance (for instance if computing
something like `vs.reduce(|a, b| a.join(b))`)

### Alternatives considered

Several alternative approaches were tried, of which the compromise of
making `Conflict` just a thin wrapper around Vec seemed the best.

#### HashSet or BTreeSet based

This alternative is very close to what is implemented. The differences
are that with a Vec, the order is preserved, the implementation of
equality and `join` has quadratic complexity. We expect `n` to be very
small so this shouldn't make a difference in practice.

Using a lookup based set requires `V : Hash` or `V : Ord` which the
current `Conflict` does not require (unfortunately adding it later would
be semver breaking, as would be changing the return value from `iter()`
or the associated `IntoIter` type of the `IntoIterator` impl).

#### Recursive data type

The following definition could in principle shadow the `join` structure:

```rs
enum Conflict<V> {
    Value(V),
    Pair([Box<Conflict>; 2])
}
```

In this case, if `a.join(b).join(c.join(d))` has 4 conflicting values,
they would take the form `Pair([ Pair([ Value(x), Value(y) ]), Pair([
Value(z), Value(w) ]) ])`, which is arguably more informative.
Unfortunately this is still imprecise because if `a.join(b).join(c)` has
a binary conflict `Pair([ Value(x), Value(y) ])`, it's still ambiguous
in the same way.

In order for this approach to be workable it has to shadow the syntax
tree of the join operation for the Ok branch too, in which case this
entire abstraction kind of only computing the transpose, going from e.g.
a list of structs with values, to a struct of lists of values, but not
reducing any of the complexity unless there are no conflicts anywhere.

The purpose of these abstractions is to take the problem of merging two
or more compound values into the a series of simpler problems, merging
two or more elements of a simpler type. Tracking provenance with perfect
fidelity means that if there is any conflict the structure is not
simplified at all.

#### n-ary join

The final option considered was defining join not as a binary operation
but n-ary. This is no different than 

### Associated error type or generics

The above alternatives imply a "one size fits all" approach. However,
PartialJoin could have an Error type, where `JoinResult<V> = Result<V,
<V as PartialJoin>::Error>`.

Ostensibly this would allow some choice, but with associated types the
choice is fixed per implementation of the trait and so would not afford
users the choice of whether to opt out of provenance tracking for
simpler errors or opt in and deal with the added complexity.

Making the error type fully generic would make that possible with even
more complexity and syntactic overhead. However, no generality would be
gained for this additional complexity.

Thinking of Conflict<V> as just "deferred arguments for a join" (i.e. a
formal product), any arbitrary merge operation can be expressed by just
taking those arguments.

More formally, Conflict<V> is the free semilattice (sets under union)
over V. Since every semilattice is a quotient of the free semilattice,
so there is no operation that can be expressed by setting Error to some
type that merges V's according to some rules (e.g. taking the max of
integers) that can't be expressed by simply processing the conflict
after the fact.

### Conclusion

For these reasons, making Conflict a thin wrapper around `Vec` seems
like the best compromise: has the same expressive power but results in a
simpler interface than all the alternatives, and makes provenance
tracking possible and even relatively straightforward without forcing it
on all users.

Author: nothingmuch

crates/concurrent-psbt/src/lattice/mod.rs

@@ -1,2 +1,4 @@
 #[macro_use]
 pub mod join;
+#[macro_use]
+pub mod partial;

crates/concurrent-psbt/src/lattice/partial.rs

@@ -0,0 +1,382 @@
+//! Some types have a natural merge operation but that isn't defined for all pairs of values.
+//! [`PartialJoin::try_join`] captures this.
+//!
+//! It returns [`JoinResult<V>`], an alias for `Result<V, Conflict<V>>`, where [`Conflict<V>`],
+//! collects all the distinct values that couldn't be merged.
+//!
+//! [`JoinResult<V>`] implements [`Join`], which is an infallible join operation (the free
+//! semilattice over `V`, more or less), in terms of [`Conflict<V>`]'s [`Join`] implementation.
+
+use crate::lattice::join::{Join, JoinMut};
+
+/// Fallible join for scalar value types where merge may produce a conflict.
+///
+/// Containers should not implement this, instead they should implement [`Join`] by wrapping
+/// contained values in [`JoinResult`].
+pub trait PartialJoin: Sized + PartialEq {
+    /// Attempt to join two values.
+    ///
+    /// Returns `Ok(lub)` where `lub` is the least upper bound if one exists, or `Err(Conflict)`
+    /// containing both values.
+    ///
+    /// Although `Conflict<V>` has set semantics (equality treats it as an unordered collection),
+    /// insertion order is preserved during iteration: when two `Ok` values are joined and produce
+    /// a binary conflict, the first value is the left operand and the second is the right.
+    ///
+    /// Provenance is only reliable when both operands were `Ok` before the join. When an existing
+    /// `Conflict` is joined with another value, new entries are appended, so a multi-way fold does
+    /// not preserve per-operand attribution.
+    fn try_join(self, other: Self) -> JoinResult<Self>;
+
+    /// Lift a value into the result domain as `Ok(self)`.
+    fn wrap(self) -> JoinResult<Self> {
+        Ok(self)
+    }
+}
+
+/// Result of a fallible join: `Ok(v)` where `v` is the least upper bound if one exists,
+/// `Err(Conflict)` otherwise.
+///
+/// `JoinResult<V>` implements [`Join`].
+pub type JoinResult<V> = Result<V, Conflict<V>>;
+
+impl<V> Join for JoinResult<V>
+where
+    V: PartialJoin,
+{
+    fn join(self, other: Self) -> Self {
+        match (self, other) {
+            (Ok(a), Ok(b)) => a.try_join(b),
+            (Err(a), Err(b)) => Err(a.join(b)),
+            (Err(a), Ok(b)) => Err(a.join(Conflict::singleton(b))),
+            (Ok(a), Err(b)) => Err(Conflict::singleton(a).join(b)),
+        }
+    }
+}
+
+/// A set of conflicting values, produced when a join for those values does not exist.
+///
+/// When two participants set the same field to different values, neither can be chosen without
+/// losing information. `Conflict` preserves the set of distinct conflicting values allowing the
+/// caller to inspect or resolve the disagreement.
+///
+/// The inner values are [`PartialJoin`] with equality based on [`PartialEq`]. Duplicate values
+/// are omitted.
+#[derive(Debug, Clone)]
+pub struct Conflict<V: PartialJoin>(Vec<V>);
+
+impl<V: PartialJoin> Conflict<V> {
+    /// Wrap a single value into a conflict.
+    fn singleton(v: V) -> Self {
+        Self(vec![v])
+    }
+
+    /// Build from an iterator, deduplicating values.
+    #[allow(dead_code)] // production caller: tspwkqxz (values.rs IdempotentValue::try_join)
+    pub(crate) fn from_values(iter: impl IntoIterator<Item = V>) -> Self {
+        let mut vals = Vec::new();
+        for v in iter {
+            if !vals.contains(&v) {
+                vals.push(v);
+            }
+        }
+        Self(vals)
+    }
+
+    /// Iterates over references to the conflicted values.
+    fn iter(&self) -> std::slice::Iter<'_, V> {
+        self.0.iter()
+    }
+
+    /// Number of distinct conflicting values.
+    pub fn len(&self) -> usize {
+        self.0.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
+}
+
+impl<V: PartialJoin> JoinMut for Conflict<V> {
+    fn join_mut(&mut self, other: Self) {
+        for value in other.0 {
+            if !self.0.contains(&value) {
+                self.0.push(value)
+            }
+        }
+    }
+}
+
+/// Set equality: same elements, regardless of order.
+///
+/// $O(n^2)$ but $n$ is tiny in practice (typically 2).
+impl<V: PartialJoin> PartialEq for Conflict<V> {
+    fn eq(&self, other: &Self) -> bool {
+        self.0.len() == other.0.len() && self.iter().all(|v| other.0.contains(v))
+    }
+}
+
+impl<V: PartialJoin + Eq> Eq for Conflict<V> {}
+
+impl<V: PartialJoin> IntoIterator for Conflict<V> {
+    type Item = V;
+    type IntoIter = std::vec::IntoIter<V>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.0.into_iter()
+    }
+}
+
+impl<'a, V: PartialJoin> IntoIterator for &'a Conflict<V> {
+    type Item = &'a V;
+    type IntoIter = std::slice::Iter<'a, V>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.iter()
+    }
+}
+
+/// Proptest macros for verifying `PartialJoin` laws and the `JoinResult` completion. Available
+/// when `prop-tests` feature is enabled.
+///
+/// # `assert_partial_join_laws!($arb_clean, $arb_result)`
+///
+/// Generates:
+/// - `try_join` laws on clean values: idempotent, commutative, associative (via wrap/join)
+/// - `JoinResult` laws on pre-built Ok/Err values: idempotent, commutative, associative
+/// - `wrap_roundtrip`: wrapping a clean value always produces `Ok`
+///
+/// The `$arb_clean` strategy produces clean (pre-join) values.
+/// The `$arb_result` strategy produces `JoinResult` values (both Ok and Err).
+#[cfg(feature = "prop-tests")]
+#[allow(unused_macros)] // used by downstream commits (collection modules, domain types)
+macro_rules! assert_partial_join_laws {
+    ($arb_clean:expr, $arb_result:expr) => {
+        proptest! {
+            #[test]
+            fn try_join_idempotent(a in $arb_clean) {
+                prop_assert_eq!(a.clone().try_join(a.clone()), Ok(a));
+            }
+
+            #[test]
+            fn try_join_commutative(a in $arb_clean, b in $arb_clean) {
+                prop_assert_eq!(a.clone().try_join(b.clone()), b.try_join(a));
+            }
+
+            #[test]
+            fn try_join_associative(a in $arb_clean, b in $arb_clean, c in $arb_clean) {
+                prop_assert_eq!(
+                    a.clone().try_join(b.clone()).join(c.clone().wrap()),
+                    a.wrap().join(b.try_join(c)),
+                );
+            }
+
+            #[test]
+            fn wrap_roundtrip(a in $arb_clean) {
+                let wrapped = a.clone().wrap();
+                prop_assert!(wrapped.is_ok());
+                prop_assert_eq!(wrapped.expect("should be Ok"), a);
+            }
+        }
+
+        mod join_result {
+            use super::*;
+            assert_join_laws!($arb_result);
+        }
+    };
+}
+
+#[cfg(all(test, any(feature = "unit-tests", feature = "prop-tests")))]
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod tests {
+    use super::*;
+
+    #[derive(Debug, Clone, Copy, PartialEq)]
+    struct Foo(u8);
+
+    impl PartialJoin for Foo {
+        fn try_join(self, other: Self) -> JoinResult<Self> {
+            if self == other {
+                Ok(self)
+            } else {
+                Err(Conflict::from_values([self, other]))
+            }
+        }
+    }
+
+    #[cfg(feature = "unit-tests")]
+    mod unit {
+        use super::*;
+
+        #[test]
+        fn result_ok_ok_different_produces_conflict() {
+            assert_eq!(
+                Foo(0).wrap().join(Foo(1).wrap()),
+                Err(Conflict(vec![Foo(0), Foo(1)])),
+            );
+        }
+
+        #[test]
+        fn result_err_ok_absorbs() {
+            let err: JoinResult<Foo> = Err(Conflict(vec![Foo(0), Foo(1)]));
+            assert_eq!(
+                err.join(Ok(Foo(2))),
+                Err(Conflict(vec![Foo(0), Foo(1), Foo(2)]))
+            );
+        }
+
+        #[test]
+        fn result_ok_err_absorbs() {
+            let err: JoinResult<Foo> = Err(Conflict(vec![Foo(0), Foo(1)]));
+            assert_eq!(
+                Ok(Foo(2)).join(err),
+                Err(Conflict(vec![Foo(2), Foo(0), Foo(1)]))
+            );
+        }
+
+        #[test]
+        fn result_err_err_merges_conflicts() {
+            let a: JoinResult<Foo> = Err(Conflict(vec![Foo(0), Foo(1)]));
+            let b: JoinResult<Foo> = Err(Conflict(vec![Foo(1), Foo(2)]));
+            assert_eq!(a.join(b), Err(Conflict(vec![Foo(0), Foo(1), Foo(2)])));
+        }
+
+        #[test]
+        fn different_conflicts_are_not_equal() {
+            let a = Conflict::from_values([Foo(0), Foo(1)]);
+            let b = Conflict::from_values([Foo(0), Foo(2)]);
+            assert_ne!(a, b);
+        }
+
+        #[test]
+        fn different_length_conflicts_are_not_equal() {
+            let a = Conflict::from_values([Foo(0), Foo(1)]);
+            let b = Conflict::from_values([Foo(0), Foo(1), Foo(2)]);
+            assert_ne!(a, b);
+        }
+
+        #[test]
+        fn conflict_from_equal_pair_deduplicates() {
+            let c = Conflict::from_values([Foo(0), Foo(0)]);
+            assert_eq!(c.len(), 1);
+        }
+
+        #[test]
+        fn len_distinct_values() {
+            let c = Conflict::from_values([Foo(0), Foo(1)]);
+            assert_eq!(c.len(), 2);
+        }
+
+        #[test]
+        fn is_empty() {
+            assert!(Conflict::<Foo>::from_values([]).is_empty());
+            assert!(!Conflict::from_values([Foo(0)]).is_empty());
+        }
+
+        #[test]
+        fn into_iter_yields_elements() {
+            let c = Conflict::from_values([Foo(0), Foo(1)]);
+            let v: Vec<_> = c.into_iter().collect();
+            assert_eq!(v, vec![Foo(0), Foo(1)]);
+        }
+
+        #[test]
+        fn borrowed_iteration() {
+            let c = Conflict::from_values([Foo(0), Foo(1)]);
+            let v: Vec<_> = (&c).into_iter().collect();
+            assert_eq!(v, vec![&Foo(0), &Foo(1)]);
+        }
+
+        #[test]
+        fn conflict_preserves_order() {
+            let x = Conflict::from_values([Foo(0)]);
+            let y = Conflict::from_values([Foo(1)]);
+
+            let xy = x.clone().join(y.clone());
+            let yx = y.clone().join(x.clone());
+
+            assert_eq!(xy, yx);
+            assert_ne!(xy.iter().collect::<Vec<_>>(), yx.iter().collect::<Vec<_>>());
+            assert_ne!(
+                xy.into_iter().collect::<Vec<_>>(),
+                yx.into_iter().collect::<Vec<_>>()
+            );
+        }
+    }
+
+    // Small domain (4 values): high collision rate exercises the
+    // equal-value (Ok) path while still covering the conflict (Err) path.
+    #[cfg(feature = "prop-tests")]
+    mod prop {
+        use super::*;
+        use proptest::prelude::*;
+
+        pub fn arb_foo() -> impl Strategy<Value = Foo> {
+            (0u8..4).prop_map(Foo)
+        }
+
+        /// Generate a JoinResult<Foo> which is either Ok(v) or Err(Conflict) with 1–5 values.
+        /// Exercises all arms of JoinResult::join.
+        pub fn arb_join_result() -> impl Strategy<Value = JoinResult<Foo>> {
+            prop_oneof![
+                arb_foo().prop_map(Ok),
+                proptest::collection::vec(arb_foo(), 1..=5)
+                    .prop_map(|v| Err(Conflict::from_values(v))),
+            ]
+        }
+
+        assert_partial_join_laws!(arb_foo(), arb_join_result());
+
+        proptest! {
+            #[test]
+            fn conflict_into_iter_roundtrips(a in arb_foo(), b in arb_foo()) {
+                let c = Conflict::from_values([a, b]);
+                let vals = c.clone().into_iter();
+                let rebuilt = Conflict::from_values(vals);
+                prop_assert_eq!(c, rebuilt);
+            }
+
+            #[test]
+            fn borrowed_iter_matches_owned(a in arb_foo(), b in arb_foo()) {
+                let c = Conflict::from_values([a, b]);
+                let owned: Vec<_> = c.clone().into_iter().collect();
+                let borrowed: Vec<_> = (&c).into_iter().copied().collect();
+                prop_assert_eq!(owned, borrowed);
+            }
+
+            #[test]
+            fn len_matches_iter_count(a in arb_foo(), b in arb_foo(), c in arb_foo()) {
+                let conflict = Conflict::from_values([a, b, c]);
+                prop_assert_eq!(conflict.len(), conflict.into_iter().count());
+            }
+
+            #[test]
+            fn non_empty_after_construction(a in arb_foo()) {
+                let c = Conflict::from_values([a]);
+                prop_assert!(!c.is_empty());
+            }
+
+            #[test]
+            fn empty_from_empty(a in arb_foo()) {
+                let _ = a; // use the parameter to satisfy proptest
+                let c = Conflict::<Foo>::from_values([]);
+                prop_assert!(c.is_empty());
+                prop_assert_eq!(c.len(), 0);
+            }
+
+            #[test]
+            fn conflict_different_lengths_not_equal(
+                a in arb_foo(),
+                b in arb_foo(),
+                c in arb_foo(),
+            ) {
+                let short = Conflict::from_values([a, b]);
+                let long = Conflict::from_values([a, b, c]);
+                if short.len() != long.len() {
+                    prop_assert_ne!(short, long);
+                }
+            }
+        }
+    }
+}

crates/concurrent-psbt/src/lib.rs

@@ -6,3 +6,4 @@
 mod lattice;
 
 pub use lattice::join::{Join, JoinMut};
+pub use lattice::partial::{Conflict, JoinResult, PartialJoin};