lorebase-core 0.3.1__tar.gz → 0.4.0__tar.gz

{lorebase_core-0.3.1 → lorebase_core-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lorebase-core
-Version: 0.3.1
+Version: 0.4.0
 Summary: Lorebase core: pure domain logic and versioning engine
 Project-URL: Homepage, https://github.com/aantenore/lorebase
 Project-URL: Documentation, https://aantenore.github.io/lorebase/

{lorebase_core-0.3.1 → lorebase_core-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lorebase-core"
-version = "0.3.1"
+version = "0.4.0"
 description = "Lorebase core: pure domain logic and versioning engine"
 requires-python = ">=3.12"
 readme = "README.md"

lorebase_core-0.4.0/src/lorebase_core/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{lorebase_core-0.3.1 → lorebase_core-0.4.0}/src/lorebase_core/merge/__init__.py

@@ -7,10 +7,12 @@ from lorebase_core.merge.conflicts import (
     AutoResolution,
     Conflict,
     ConflictKind,
+    ConflictProvenance,
     Resolution,
     ResolutionChoice,
     ResolutionError,
     Side,
+    SideProvenance,
     UnresolvedConflictsError,
     conflict_fingerprint,
 )
@@ -59,6 +61,7 @@ __all__ = [
     "ChangeStamp",
     "Conflict",
     "ConflictKind",
+    "ConflictProvenance",
     "InMemoryObjectStore",
     "IndexViewFactory",
     "LineageLoader",
@@ -77,6 +80,7 @@ __all__ = [
     "ResolutionError",
     "SchemaLoader",
     "Side",
+    "SideProvenance",
     "TextGranularity",
     "TreeIndexView",
     "UnresolvedConflictsError",

{lorebase_core-0.3.1 → lorebase_core-0.4.0}/src/lorebase_core/merge/conflicts.py

@@ -24,10 +24,12 @@ __all__ = [
     "AutoResolution",
     "Conflict",
     "ConflictKind",
+    "ConflictProvenance",
     "Resolution",
     "ResolutionChoice",
     "ResolutionError",
     "Side",
+    "SideProvenance",
     "UnresolvedConflictsError",
     "conflict_fingerprint",
 ]
@@ -169,6 +171,32 @@ class _Frozen(BaseModel):
     model_config = ConfigDict(frozen=True, extra="forbid")
 
 
+class SideProvenance(_Frozen):
+    """Who or what last changed the Attribute of a Conflict on one side, and when.
+
+    ``provenance_id`` names the provenance entry of that change and ``at`` its time (ISO 8601,
+    timezone aware). ``actor`` wrote the entry; ``origin`` is its origin type (``source_sync``,
+    ``operation``, ``extraction``, ...); ``source`` is the Source id of a Source sync and
+    ``principal`` the principal of an Operation. ``labels`` are the origin labels an
+    ``authority`` ranking matches, sorted.
+    """
+
+    provenance_id: str
+    at: str
+    actor: str | None = None
+    origin: str | None = None
+    source: str | None = None
+    principal: str | None = None
+    labels: tuple[str, ...] = ()
+
+
+class ConflictProvenance(_Frozen):
+    """The provenance of the two competing sides; a side whose Lineage is unknown is ``None``."""
+
+    ours: SideProvenance | None = None
+    theirs: SideProvenance | None = None
+
+
 class Conflict(_Frozen):
     """One Conflict of a merge attempt.
 
@@ -177,7 +205,10 @@ class Conflict(_Frozen):
     Conflicts and a dotted property path for schema Conflicts. ``base``, ``ours`` and
     ``theirs`` hold the competing values (``None`` means absent) and the ``*_hash`` fields the
     hashes of the elements they come from. Grouped Conflicts carry ``count`` members and a
-    ``sample`` of their keys.
+    ``sample`` of their keys. ``provenance`` says who or what changed each side and when: it is
+    set on open Attribute Conflicts (``DV1``, ``DV3``) when the merge has a Lineage loader and
+    knows the Lineage of at least one side, and ``None`` otherwise. It is not part of the
+    fingerprint.
     """
 
     kind: ConflictKind
@@ -197,6 +228,7 @@ class Conflict(_Frozen):
     details: dict[str, JsonValue] = Field(default_factory=dict)
     choices: tuple[ResolutionChoice, ...] = ()
     machine_resolvable: bool = False
+    provenance: ConflictProvenance | None = None
 
     @property
     def grouped(self) -> bool:

{lorebase_core-0.3.1 → lorebase_core-0.4.0}/src/lorebase_core/merge/engine.py

@@ -133,16 +133,22 @@ class MergeInput:
 
 class MergeResult(StrEnum):
     UP_TO_DATE = "up_to_date"
-    """Theirs is already contained in ours: the target does not change."""
+    """Theirs is already contained in ours: the target does not change. ``root`` is ours and
+    ``parents`` is ``(ours,)``."""
     FAST_FORWARD = "fast_forward"
-    """The target moves to theirs."""
+    """The target moves to theirs. ``root`` is theirs' tree. A caller that moves the ref to
+    ``theirs`` writes nothing; one that commits ``root`` as returned gets a Revision whose only
+    parent is ours, so history stays connected."""
     MERGED = "merged"
     """A merge Revision with parents ``(ours, theirs)`` is to be written."""
 
 
 @dataclass(frozen=True)
 class MergedTree:
-    """A clean merge: the new tree and its changeset against ours (the first parent)."""
+    """A clean merge: the new tree and its changeset against ours (the first parent).
+
+    ``parents`` is never empty: ``(ours, theirs)`` for a merge, ``(ours,)`` for a fast-forward
+    or an up-to-date result, so committing ``root`` with ``parents`` never writes a root."""
 
     result: MergeResult
     root: bytes
@@ -286,7 +292,7 @@ class _Engine:
             theirs=merge_input.theirs,
             base=base,
             virtual_base=False,
-            parents=(),
+            parents=(merge_input.ours,),
             changes=(),
             stats=changeset_stats(()),
         )
@@ -304,7 +310,7 @@ class _Engine:
             theirs=merge_input.theirs,
             base=base,
             virtual_base=False,
-            parents=(),
+            parents=(merge_input.ours,),
             changes=changes,
             stats=changeset_stats(changes),
         )

{lorebase_core-0.3.1 → lorebase_core-0.4.0}/src/lorebase_core/merge/state.py

@@ -17,10 +17,12 @@ from lorebase_core.merge.conflicts import (
     AutoResolution,
     Conflict,
     ConflictKind,
+    ConflictProvenance,
     Resolution,
     ResolutionChoice,
     ResolutionError,
     Side,
+    SideProvenance,
     conflict_fingerprint,
 )
 from lorebase_core.merge.objects import ObjectStore, SchemaLoader, load_object
@@ -370,7 +372,25 @@ class Context:
 
     def report(self, conflict: Conflict) -> None:
         if not self.virtual:
-            self.conflicts.append(conflict)
+            self.conflicts.append(self.with_provenance(conflict))
+
+    def with_provenance(self, conflict: Conflict) -> Conflict:
+        """``conflict`` with who and when of each side, when a Lineage loader knows them.
+
+        Only Attribute Conflicts have a last change per side; without a loader, or when it
+        knows neither side, the Conflict is returned as it is.
+        """
+        if self.lineage is None or conflict.kind not in _ATTRIBUTE_KINDS:
+            return conflict
+        ours = self.lineage_entry(Side.OURS, conflict)
+        theirs = self.lineage_entry(Side.THEIRS, conflict)
+        if ours is None and theirs is None:
+            return conflict
+        provenance = ConflictProvenance(
+            ours=None if ours is None else _side_provenance(ours),
+            theirs=None if theirs is None else _side_provenance(theirs),
+        )
+        return conflict.model_copy(update={"provenance": provenance})
 
     def group(
         self,
@@ -431,6 +451,20 @@ class Context:
         return (values[0], values[1], values[2])
 
 
+def _side_provenance(stamp: ChangeStamp) -> SideProvenance:
+    labels = sorted(stamp.labels)
+    named = dict(label.split(":", 1) for label in labels)
+    return SideProvenance(
+        provenance_id=stamp.id,
+        at=stamp.at.isoformat(),
+        actor=named.get("actor"),
+        origin=named.get("origin"),
+        source=named.get("source"),
+        principal=named.get("principal"),
+        labels=tuple(labels),
+    )
+
+
 def other_side(side: Side) -> Side:
     return Side.THEIRS if side is Side.OURS else Side.OURS
 

lorebase_core-0.4.0/tests/merge/test_fast_forward.py

@@ -0,0 +1,35 @@
+"""A fast-forward result committed as returned keeps the history connected."""
+
+from __future__ import annotations
+
+from lorebase_core.merge import ConflictKind, MergeResult
+
+from .support import Edit, Repo, attempt, base_records, base_schema, merged, supplier
+
+
+def _fork() -> tuple[Repo, bytes, bytes, bytes]:
+    repo = Repo()
+    base = repo.commit("base", Edit(schema=base_schema(), put=list(base_records())))
+    source = repo.commit("source", Edit().upsert(supplier("S-1", vat="IT001", rating="4")), base)
+    model = repo.commit("model", Edit().upsert(supplier("S-1", vat="IT001", rating="5")), base)
+    return repo, base, source, model
+
+
+def test_fast_forward_commit_stays_connected_to_the_target() -> None:
+    repo, base, source, model = _fork()
+    forward = merged(repo.merge(base, source))
+    assert forward.result is MergeResult.FAST_FORWARD
+    assert forward.root == repo.roots[source]
+    assert forward.parents == (base,)
+
+    head = repo.add("main", forward.root, *forward.parents)
+    result = attempt(repo.merge(head, model))
+    assert result.base == base
+    assert [c.kind for c in result.conflicts] == [ConflictKind.ATTRIBUTE_VALUE]
+
+
+def test_up_to_date_result_keeps_the_target_as_parent() -> None:
+    repo, base, source, _ = _fork()
+    same = merged(repo.merge(source, base))
+    assert same.result is MergeResult.UP_TO_DATE
+    assert same.parents == (source,)

{lorebase_core-0.3.1 → lorebase_core-0.4.0}/tests/merge/test_policies.py

@@ -197,6 +197,67 @@ def test_schema_authority_ranks_the_attribute_source_first() -> None:
     assert result.auto_resolutions[0].choice is ResolutionChoice.THEIRS
 
 
+# provenance of open Conflicts ---------------------------------------------------------------
+
+
+def test_open_conflicts_carry_who_and_when_of_each_side() -> None:
+    scenario = _conflicting()
+    loader = lineage(scenario, *_both(edit(1, "alice", T2), sync(2, ERP, T1)))
+    result = attempt(scenario.merge(lineage=loader))
+    assert {c.attribute for c in result.conflicts} == {NAME, COUNTRY}
+    for conflict in result.conflicts:
+        provenance = conflict.provenance
+        assert provenance is not None
+        ours, theirs = provenance.ours, provenance.theirs
+        assert ours is not None
+        assert theirs is not None
+        assert (ours.provenance_id, ours.at) == (ident("prv", 1), "2026-03-02T10:00:00+00:00")
+        assert (ours.actor, ours.origin, ours.principal, ours.source) == (
+            "alice",
+            "operation",
+            "alice",
+            None,
+        )
+        assert (theirs.provenance_id, theirs.at) == (ident("prv", 2), "2026-03-01T10:00:00+00:00")
+        assert (theirs.actor, theirs.origin, theirs.principal, theirs.source) == (
+            "scribe",
+            "source_sync",
+            None,
+            ERP,
+        )
+        assert theirs.labels == tuple(sorted(origin_labels(sync(2, ERP, T1))))
+
+
+def test_open_conflicts_without_a_lineage_loader_carry_no_provenance() -> None:
+    scenario = _conflicting()
+    result = attempt(scenario.merge())
+    assert [c.provenance for c in result.conflicts] == [None, None]
+    assert "provenance" not in {
+        name for c in result.conflicts for name in c.model_dump(exclude_none=True)
+    }
+
+
+def test_a_side_of_unknown_lineage_is_left_out() -> None:
+    scenario = _conflicting()
+    one_sided = lineage(scenario, {}, {NAME: sync(2, ERP, T1)})
+    result = attempt(scenario.merge(lineage=one_sided))
+    by_attribute = {c.attribute: c.provenance for c in result.conflicts}
+    assert by_attribute[COUNTRY] is None
+    named = by_attribute[NAME]
+    assert named is not None
+    assert named.ours is None
+    assert named.theirs is not None
+    assert named.theirs.source == ERP
+
+
+def test_provenance_does_not_change_the_fingerprint() -> None:
+    scenario = _conflicting()
+    loader = lineage(scenario, *_both(edit(1, "alice", T2), sync(2, ERP, T1)))
+    plain = attempt(scenario.merge())
+    stamped = attempt(scenario.merge(lineage=loader))
+    assert [c.fingerprint for c in stamped.conflicts] == [c.fingerprint for c in plain.conflicts]
+
+
 # newest_wins ------------------------------------------------------------------------------
 
 

{lorebase_core-0.3.1 → lorebase_core-0.4.0}/tests/merge/test_properties.py

@@ -140,7 +140,7 @@ def test_fast_forward_detection(world: World, allowed: bool) -> None:
     assert forward.root == repo.roots[descendant]
     if allowed:
         assert forward.result is MergeResult.FAST_FORWARD
-        assert forward.parents == ()
+        assert forward.parents == (ours,)
     else:
         assert forward.result is MergeResult.MERGED
         assert forward.parents == (ours, descendant)

lorebase_core-0.3.1/src/lorebase_core/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.3.1"