s3dgraphy 1.6.0.dev47__tar.gz → 1.6.0.dev49__tar.gz

{s3dgraphy-1.6.0.dev47/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev47
+Version: 1.6.0.dev49
 Summary: 3D Stratigraphic Graph Management Library for archaeological and heritage applications
 Author-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
 Maintainer-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>

{s3dgraphy-1.6.0.dev47 → s3dgraphy-1.6.0.dev49}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "s3dgraphy"
-version = "1.6.0.dev47"
+version = "1.6.0.dev49"
 description = "3D Stratigraphic Graph Management Library for archaeological and heritage applications"
 readme = "README.md"
 requires-python = ">=3.9"

{s3dgraphy-1.6.0.dev47 → s3dgraphy-1.6.0.dev49}/src/s3dgraphy/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.6.0.dev47"
+__version__ = "1.6.0.dev49"
 __datamodel_version__ = "1.5.5"  # s3Dgraphy connections datamodel version
 
 # s3Dgraphy/__init__.py

{s3dgraphy-1.6.0.dev47 → s3dgraphy-1.6.0.dev49}/src/s3dgraphy/api.py

@@ -646,6 +646,16 @@ def merge_containers(container, other):
     return merge_into_container(container, other)
 
 
+def merge_graphs(container, graph_ids: Optional[List[str]] = None):
+    """One graph for the overall view of the graphs of ``container`` (all,
+    or ``graph_ids``): nodes united by id, edges deduplicated by
+    ``(source, type, target)``, the links between them as edges. Returns
+    ``(graph, report)``; the container is not touched. See
+    :func:`s3dgraphy.container.merge_graphs`."""
+    from .container import merge_graphs as _merge
+    return _merge(container, graph_ids)
+
+
 # ── HDT-O: the study, its place, the heritage it is about ────────────────────
 
 def declare_hdto(graph: Graph, *, study=None, place=None, about=None,
@@ -804,7 +814,7 @@ def set_field(node, field: str, value, *, author=None,
     coming out of its tombstone.
     """
     from .crdt import Clock, write_field
-    from .editorial import normalize_orcid, now_iso
+    from .editorial import normalize_orcid, now_op_iso
 
     if field in ("data.lang", "data.from_lang") and value not in (None, ""):
         # a node's language is a BCP 47 tag; an invalid one is refused, not stored
@@ -812,7 +822,7 @@ def set_field(node, field: str, value, *, author=None,
         check_language_tag(value)
     payload = _node_payload_view(node)
     write_field(payload, field, value,
-                Clock(ts=at or now_iso(), by=normalize_orcid(author)))
+                Clock(ts=at or now_op_iso(), by=normalize_orcid(author)))
     _write_back(node, payload, field)
 
 
@@ -826,10 +836,10 @@ def clear_field(node, field: str, *, author=None,
     correctly, and wrongly, hand the value back.
     """
     from .crdt import Clock, clear_field as _clear
-    from .editorial import normalize_orcid, now_iso
+    from .editorial import normalize_orcid, now_op_iso
 
     payload = _node_payload_view(node)
-    _clear(payload, field, Clock(ts=at or now_iso(), by=normalize_orcid(author)))
+    _clear(payload, field, Clock(ts=at or now_op_iso(), by=normalize_orcid(author)))
     _write_back(node, payload, field)
 
 
@@ -873,7 +883,7 @@ def stamp_field(node, field: str, *, by=None, at: Optional[str] = None) -> None:
     but `set_field` is the one to use: it cannot be half-done.
     """
     from .crdt import Clock, set_field_clock
-    from .editorial import normalize_orcid, now_iso
+    from .editorial import normalize_orcid, now_op_iso
 
     data = getattr(node, "data", None)
     if not isinstance(data, dict):
@@ -881,7 +891,7 @@ def stamp_field(node, field: str, *, by=None, at: Optional[str] = None) -> None:
         node.data = data
     payload = {"data": data}
     set_field_clock(payload, field,
-                    Clock(ts=at or now_iso(), by=normalize_orcid(by)))
+                    Clock(ts=at or now_op_iso(), by=normalize_orcid(by)))
 
 
 def unstamped_fields(node) -> List[str]:

{s3dgraphy-1.6.0.dev47 → s3dgraphy-1.6.0.dev49}/src/s3dgraphy/container.py

@@ -1030,3 +1030,154 @@ def merge_into_container(container: Container, other: Container) -> MergeReport:
     # lie about how much has happened.
     bump_version(container)
     return report
+
+
+#: the id of the graph :func:`merge_graphs` returns
+MERGED_GRAPH_ID = "merged"
+
+
+def merge_graphs(container: Container,
+                 graph_ids: Optional[Iterable[str]] = None
+                 ) -> Tuple[Graph, Dict[str, Any]]:
+    """One graph for the overall view of several graphs of ``container`` —
+    the site whole again, after :meth:`GraphProjector.populate_container`
+    made one graph per saggio (s3Dgraphy#36).
+
+    Each saggio is a study of its own (E.D., 12 Oct 2026): its graph carries
+    a copy of the paradata it shares with the others (documents, authors,
+    epochs, places), with the SAME id. Summing the graphs counts those twice;
+    this does not:
+
+    * **nodes** united by id — the identity of a node shared between graphs
+      is its id, never its label (two documents named «D.01» in two studies
+      may be two documents, and stay two);
+    * **edges** deduplicated by ``(source, type, target)``, the definition of
+      «the same relation» :func:`_merge_graph_into` uses;
+    * **links** (:mod:`s3dgraphy.links`) between two merged graphs become
+      ordinary edges, with the link's id, type and attributes; a link whose
+      other end is not among them stays out, and the report names it.
+
+    The first graph (in ``graph_ids`` order, else the container's) gives the
+    version of a node; when another graph has the same id with different
+    content (the editorial stamps aside, as in a merge), the report says so
+    — node, graphs, which one was kept, which fields diverge. It does not
+    choose in silence. The same for an edge whose attributes differ.
+
+    Reads only: the container, its graphs and their links are not touched
+    (the merged graph holds copies), and nothing is written to file.
+
+    Returns ``(graph, report)``; ``report`` is a dict: ``graphs``,
+    ``nodes_in`` / ``nodes`` / ``nodes_merged`` (rows read, nodes kept, copies
+    folded), the same three for ``edges``, ``links_resolved``,
+    ``links_unresolved`` (one sentence each), ``conflicts`` (nodes),
+    ``edge_conflicts``, ``warnings``.
+    """
+    import copy
+    from .links import links_of_graph
+
+    ids = list(graph_ids) if graph_ids is not None else container.graph_ids()
+    unknown = [gid for gid in ids if gid not in container.graphs]
+    if unknown:
+        raise ValueError(f"no graph {', '.join(map(repr, unknown))} in this container")
+
+    merged = Graph(MERGED_GRAPH_ID, name="merged view")
+    auto_geo = [n.node_id for n in merged.nodes]
+    report: Dict[str, Any] = {
+        "graphs": list(ids), "nodes_in": 0, "nodes": 0, "nodes_merged": 0,
+        "edges_in": 0, "edges": 0, "edges_merged": 0,
+        "links_resolved": 0, "links_unresolved": [],
+        "conflicts": [], "edge_conflicts": [], "warnings": []}
+
+    nodes: Dict[str, Any] = {}
+    origin: Dict[str, str] = {}
+    content: Dict[str, Dict[str, Any]] = {}
+    contested: Dict[str, Dict[str, Any]] = {}
+    for gid in ids:
+        for node in container.graphs[gid].nodes:
+            report["nodes_in"] += 1
+            snap = _content_of(_node_snapshot(node))
+            if node.node_id not in nodes:
+                nodes[node.node_id] = copy.deepcopy(node)
+                origin[node.node_id] = gid
+                content[node.node_id] = snap
+                continue
+            report["nodes_merged"] += 1
+            if snap == content[node.node_id]:
+                continue
+            entry = contested.get(node.node_id)
+            if entry is None:
+                entry = contested[node.node_id] = {
+                    "node_id": node.node_id, "name": getattr(node, "name", None),
+                    "kept_from": origin[node.node_id],
+                    "graphs": [origin[node.node_id]], "fields": []}
+                report["conflicts"].append(entry)
+            entry["graphs"].append(gid)
+            for name in _diverging_fields(content[node.node_id], snap):
+                if name not in entry["fields"]:
+                    entry["fields"].append(name)
+
+    edges: Dict[Tuple[str, str, str], Any] = {}
+    edge_origin: Dict[Tuple[str, str, str], str] = {}
+    edge_ids = set()
+
+    def take(edge, gid: str) -> None:
+        key = (edge.edge_source, edge.edge_type, edge.edge_target)
+        attrs = getattr(edge, "attributes", None) or {}
+        if key in edges:
+            report["edges_merged"] += 1
+            if attrs != (getattr(edges[key], "attributes", None) or {}):
+                report["edge_conflicts"].append({
+                    "edge": list(key), "edge_id": edges[key].edge_id,
+                    "kept_from": edge_origin[key], "other": gid})
+            return
+        edge_id = edge.edge_id
+        # two graphs may have minted the same id for two relations
+        while edge_id in edge_ids:
+            edge_id = f"{edge_id}_merged"
+        kept = copy.deepcopy(edge)
+        kept.edge_id = edge_id
+        edges[key], edge_origin[key] = kept, gid
+        edge_ids.add(edge_id)
+
+    for gid in ids:
+        for edge in container.graphs[gid].edges:
+            report["edges_in"] += 1
+            take(edge, gid)
+
+    from .edges import Edge
+    chosen = set(ids)
+    for gid in ids:
+        for link in links_of_graph(container.graphs[gid]):
+            target = link["target"]
+            where = f"link '{link['id']}' of the graph '{gid}'"
+            if target["graph_id"] not in chosen:
+                report["links_unresolved"].append(
+                    f"{where}: the graph '{target['graph_id']}' is not merged")
+                continue
+            if link["source"] not in nodes or target["node_id"] not in nodes:
+                missing = (link["source"] if link["source"] not in nodes
+                           else target["node_id"])
+                report["links_unresolved"].append(f"{where}: no node '{missing}'")
+                continue
+            try:
+                edge = Edge(link["id"], link["source"], target["node_id"],
+                            link["edge_type"])
+            except ValueError as exc:
+                report["links_unresolved"].append(f"{where}: {exc}")
+                continue
+            edge.attributes = dict(link.get("attributes") or {})
+            report["edges_in"] += 1
+            report["links_resolved"] += 1
+            take(edge, gid)
+
+    # Graph() makes a geo position of its own; the members bring theirs
+    if any(getattr(n, "node_type", None) == "geo_position" for n in nodes.values()):
+        for node_id in auto_geo:
+            if node_id not in nodes:
+                merged.remove_node(node_id)
+    merged.nodes = list(merged.nodes) + [n for i, n in nodes.items()
+                                         if merged.find_node_by_id(i) is None]
+    merged.edges = list(edges.values())
+    report["nodes"] = len(nodes)
+    report["edges"] = len(edges)
+    return merged, report

{s3dgraphy-1.6.0.dev47 → s3dgraphy-1.6.0.dev49}/src/s3dgraphy/contract/connector.py

@@ -474,7 +474,7 @@ def apply_delta(section: Dict[str, Any], descriptor: ConnectorDescriptor,
     so a rejected write cannot leave half a subgraph behind.
     """
     from ..crdt import apply_op_to_section, make_op
-    from ..editorial import now_iso
+    from ..editorial import now_op_iso
 
     verdict = guard_write(descriptor, capability, delta,
                           node_types={str(n.get("id")): str(n.get("node_type") or "")
@@ -488,8 +488,9 @@ def apply_delta(section: Dict[str, Any], descriptor: ConnectorDescriptor,
     # in `data`) are written by the CRDT only when the op carries a clock —
     # measured: without one, a write landed unattributed even though the author was
     # right there. The identity and the clock are never typed by a caller
-    # (`editorial.py`'s rule), so the seam supplies the clock.
-    at = at or now_iso()
+    # (`editorial.py`'s rule), so the seam supplies the clock — an operation's,
+    # to the millisecond (E.D., 12 Oct 2026); the CRDT keeps the stamps at the second.
+    at = at or now_op_iso()
     applied = {"nodes": 0, "edges": 0}
     refused: List[Dict[str, Any]] = []
 

{s3dgraphy-1.6.0.dev47 → s3dgraphy-1.6.0.dev49}/src/s3dgraphy/crdt.py

@@ -17,7 +17,10 @@ Three pieces:
 (AUDIT1). Comparison is by instant, then by author, lexicographically smaller
 first. The tie-break is arbitrary and DECLARED (``tie-author``); what it must
 never be is "whichever I saw last", because then two people merging the same two
-files get different projects and no way to tell.
+files get different projects and no way to tell. The SAME clock on two different
+values (one hand, one instant: a connector's batch, a burst of renames) is
+settled by the value itself (``tie-value``, :func:`tie_rank`) — measured on 12
+Oct 2026, it used to be settled by arrival, and two copies kept two names.
 
 **Tombstones.** A deletion is not an absence, it is a mark: ``data.removed =
 {ts, by}``, inline, keeping the id. Views hide it; the merge SEES it. Without
@@ -73,7 +76,16 @@ OPS = ("add_node", "update_field", "remove_node", "add_edge", "remove_edge")
 #:                   The incoming value is kept (P3's behaviour) and the reason
 #:                   exists so nobody reads that as a judgement.
 #: ``resurrected`` — an edit later than a deletion brought the node back.
-FIELD_REASONS = ("newer", "tie-author", "unstamped", "resurrected")
+#: ``tie-explicit``— same instant, same author, and only ONE side carries the
+#:                   field's own clock (the other is dated by its node's stamp):
+#:                   the field's own clock wins — a field is written on a node
+#:                   that is already there.
+#: ``tie-value``   — same instant, same author, both clocks the field's own, two
+#:                   different values: the greater :func:`tie_rank` wins. Not a
+#:                   judgement — the one choice every copy makes whatever order
+#:                   the two arrive in.
+FIELD_REASONS = ("newer", "tie-author", "unstamped", "resurrected",
+                 "tie-explicit", "tie-value")
 
 
 # ── clocks ───────────────────────────────────────────────────────────────────
@@ -157,13 +169,35 @@ def compare_clocks(a: Clock, b: Clock) -> Tuple[int, str]:
     return (1, "tie-author") if ka < kb else (-1, "tie-author")
 
 
+def editorial_clock(clock: Clock) -> Clock:
+    """The clock as an EDITORIAL stamp records it: at the second.
+
+    Two precisions, one decision (E.D., 12 Oct 2026): the clock of an operation
+    (``op.ts``, ``field_clocks``, tombstones) is to the millisecond, because it
+    orders two hands; ``created_at`` / ``modified_at`` stay at the second
+    (:func:`s3dgraphy.editorial.now_iso`). Every stamp the CRDT writes from an
+    op's clock goes through here, and is compared at the second too — so two
+    hands in one second settle the stamp by the declared ``tie-author``, not by
+    arrival."""
+    if not clock.stamped:
+        return clock
+    from .editorial import normalize_instant
+    return Clock(ts=normalize_instant(clock.ts), by=clock.by)
+
+
 def clock_order(a: Clock, b: Clock) -> int:
     """Just the ordering of two clocks (-1 / 0 / 1), without the reason."""
     return compare_clocks(a, b)[0]
 
 
 def newer(a: Clock, b: Clock) -> Clock:
-    return a if clock_order(a, b) >= 0 else b
+    order = clock_order(a, b)
+    if order == 0:
+        # the same instant may be spelt two ways ("…:00Z", "…:00.000Z": a clock
+        # at the second and one at the millisecond): ONE spelling, whichever
+        # side is asked, or two copies differ by bytes nobody wrote
+        return a if (a.ts or "", a.by or "") >= (b.ts or "", b.by or "") else b
+    return a if order > 0 else b
 
 
 # ── reading a payload ────────────────────────────────────────────────────────
@@ -210,14 +244,17 @@ def field_clock(payload: Dict[str, Any], field_name: str) -> Clock:
     """
     data = payload.get("data") if isinstance(payload.get("data"), dict) else {}
     clocks = data.get(FIELD_CLOCKS_KEY)
+    # the two fallbacks are editorial stamps, so they are read at the second
+    # (`editorial_clock`) — as the CRDT writes them since 12 Oct 2026, and also
+    # when an older tool wrote one with its milliseconds
     if isinstance(clocks, dict):
         if field_name in clocks:
             return Clock.from_dict(clocks[field_name])
         if clocks:
             born = creation_stamp(payload)
             if born.stamped:
-                return born
-    return node_stamp(payload)
+                return editorial_clock(born)
+    return editorial_clock(node_stamp(payload))
 
 
 def is_stale_copy(payload: Dict[str, Any], field_name: str) -> bool:
@@ -444,6 +481,32 @@ def canonical(value: Any) -> str:
                       ensure_ascii=False, default=str)
 
 
+def tie_rank(value: Any, removed: bool = False) -> Tuple[int, bytes]:
+    """Where a field's state stands when two states carry the SAME clock.
+
+    The rule of ``tie-value``: the greater rank wins. An emptying ranks BELOW
+    every value (at the same instant a value is kept rather than lost); values
+    rank by the UTF-8 bytes of their :func:`canonical` JSON, which is code-point
+    order. A twin in another language must compare code points too — not
+    UTF-16 units, which order an emoji before ``"\\uffff"``."""
+    if removed:
+        return (0, b"")
+    return (1, canonical(value).encode("utf-8"))
+
+
+def _settle_tie(mine: Dict[str, Any], theirs: Dict[str, Any], name: str,
+                v_mine: Any, v_theirs: Any, mine_gone: bool,
+                theirs_gone: bool) -> Tuple[str, str]:
+    """``(winning side, reason)`` for two different states of one field under
+    the SAME clock (instant and author): ``tie-explicit``, else ``tie-value``."""
+    explicit_mine = clock_source(mine, name) == "field_clock"
+    explicit_theirs = clock_source(theirs, name) == "field_clock"
+    if explicit_mine != explicit_theirs:
+        return ("mine" if explicit_mine else "theirs"), "tie-explicit"
+    return ("mine" if tie_rank(v_mine, mine_gone) > tie_rank(v_theirs, theirs_gone)
+            else "theirs"), "tie-value"
+
+
 # ── the report ───────────────────────────────────────────────────────────────
 
 @dataclass
@@ -501,11 +564,9 @@ def merge_payloads(mine: Dict[str, Any], theirs: Dict[str, Any]) -> MergeOutcome
         "id": node_id,
         # identity is not a register: a type is decided when the node is made.
         # If the two disagree, the newer node stamp decides — and nothing else in
-        # this module lets identity race.
-        "node_type": (theirs.get("node_type")
-                      if clock_order(node_stamp(theirs), node_stamp(mine)) > 0
-                      else mine.get("node_type")) or mine.get("node_type")
-                     or theirs.get("node_type"),
+        # this module lets identity race. Under the same stamp the greater type
+        # name decides, so that the answer does not depend on which side is mine.
+        "node_type": _merge_type(mine, theirs),
     }
     outcome = MergeOutcome(payload=merged)
 
@@ -558,7 +619,12 @@ def merge_payloads(mine: Dict[str, Any], theirs: Dict[str, Any]) -> MergeOutcome
             # the date did not decide: the incoming state is kept, as it always
             # was, and the reason says the choice was not a judgement
             win_side = "theirs"
-        elif order >= 0:
+        elif order == 0:
+            # the SAME clock on two different states: the state decides, so
+            # that the result does not depend on which side is `mine`
+            win_side, reason = _settle_tie(mine, theirs, name, v_mine, v_theirs,
+                                           mine_gone, theirs_gone)
+        elif order > 0:
             win_side = "mine"
         else:
             win_side = "theirs"
@@ -611,7 +677,8 @@ def merge_payloads(mine: Dict[str, Any], theirs: Dict[str, Any]) -> MergeOutcome
     _merge_creation(merged, mine, theirs)
     last = Clock()
     for clock in list(winning_clocks.values()) + [node_stamp(mine), node_stamp(theirs)]:
-        last = newer(last, clock)
+        # at the second, like every stamp an op leaves (`_stamp_payload`)
+        last = newer(last, editorial_clock(clock))
     if last.stamped:
         data = merged.setdefault("data", {})
         data["modified_at"] = last.ts
@@ -645,6 +712,16 @@ def merge_payloads(mine: Dict[str, Any], theirs: Dict[str, Any]) -> MergeOutcome
     return outcome
 
 
+def _merge_type(mine: Dict[str, Any], theirs: Dict[str, Any]) -> Any:
+    a, b = mine.get("node_type"), theirs.get("node_type")
+    if not a or not b:
+        return a or b
+    order = clock_order(node_stamp(theirs), node_stamp(mine))
+    if order == 0:
+        return max(str(a), str(b))
+    return b if order > 0 else a
+
+
 def _merge_creation(merged: Dict[str, Any], mine: Dict[str, Any],
                     theirs: Dict[str, Any]) -> None:
     def creation(payload: Dict[str, Any]) -> Clock:
@@ -656,7 +733,14 @@ def _merge_creation(merged: Dict[str, Any], mine: Dict[str, Any],
     a, b = creation(mine), creation(theirs)
     if not a.stamped and not b.stamped:
         return
-    first = a if (not b.stamped or clock_order(a, b) <= 0) and a.stamped else b
+    if not b.stamped:
+        first = a
+    elif not a.stamped:
+        first = b
+    else:
+        order = clock_order(a, b)
+        # the earlier creation; under one clock, the one spelling `newer` picks
+        first = newer(a, b) if order == 0 else (a if order < 0 else b)
     data = merged.setdefault("data", {})
     data["created_at"] = first.ts
     if first.by:
@@ -1160,12 +1244,49 @@ def apply_op_to_section(section: Dict[str, Any], op: Dict[str, Any], *,
         wants_gone = op.get("remove") is True
         same_value = (gone == wants_gone
                       and canonical(get_field(existing, name)) == canonical(op.get("value")))
+        explicit = clock_source(existing, name) == "field_clock"
+        if order == 0 and same_value and reason == "tie-author" and (
+                not explicit or (newer(clock, current) is clock and clock.ts != current.ts)):
+            # the same value under the same clock: no content moves, but the
+            # field takes its OWN clock — against the node-stamp fallback it is
+            # still a write, and without the record an emptying under the same
+            # clock would win or lose by arrival (measured, 45 pairs in 20000);
+            # or the same instant spelt otherwise ("…:00Z" and "…:00.000Z"),
+            # where `newer` picks the one spelling
+            set_field_clock(existing, name, clock, removed=gone)
         if order < 0 or (order == 0 and same_value):
-            # the state is newer (or this is the same op again): nothing moves
+            # the state is newer (or this is the same op again): nothing moves…
+            # but the last-hand stamp sees this op like every other. The stamp is
+            # at the second and the field at the millisecond, so a stale op can
+            # still TIE the stamp — and if only applied ops counted, who is
+            # the last hand of that second would depend on the arrival (measured,
+            # 348 pairs in 20000). Counted always, the stamp is the max of all.
+            _stamp_payload(existing, clock, creation=False, auth=_op_auth(op)[0])
             return OpResult(False, "stale" if order < 0 else "idempotent", node_id)
         if order == 0 and not same_value and reason == "unstamped":
             # no clocks anywhere: the arriving value is taken, and declared
             pass
+        if order == 0 and reason == "tie-author":
+            # the SAME clock (instant and author) on a different state. Against
+            # a node-stamp fallback the op's own clock wins (`tie-explicit`);
+            # against the field's own clock the state decides (`tie-value`),
+            # never the arrival — measured on 12 Oct 2026, a burst of renames in
+            # one millisecond left the room on the last and EMStudio on the first
+            if not explicit:
+                reason = "tie-explicit"
+            elif tie_rank(op.get("value"), wants_gone) < tie_rank(get_field(existing, name), gone):
+                # the value stays; the node's last-hand stamp still sees this
+                # instant, so its spelling does not depend on which op won
+                _stamp_payload(existing, clock, creation=False, auth=_op_auth(op)[0])
+                return OpResult(False, "tie-value", node_id, [FieldOutcome(
+                    node_id=node_id, field=name, reason="tie-value",
+                    winner={"by": current.by, "at": current.ts, "side": "state",
+                            "removed": gone},
+                    loser={"by": clock.by, "at": clock.ts, "side": "op",
+                           "removed": wants_gone},
+                    loser_value=None if wants_gone else op.get("value"))])
+            else:
+                reason = "tie-value"
         loser_value = get_field(existing, name)
         # ONE act, the same one `api.set_field` performs: a value with its clock,
         # or an emptying with its tombstone. `remove: true` (or a null value with
@@ -1219,9 +1340,12 @@ def apply_op_to_section(section: Dict[str, Any], op: Dict[str, Any], *,
                 learned = _merge_declared(attrs, declared)
                 # the relation was created by its OLDEST add, whichever arrives
                 # first: without this two adds converge only in one order
-                born = Clock(ts=attrs.get("created_at"), by=attrs.get("created_by"))
-                if clock.stamped and (not born.stamped or clock_order(clock, born) < 0):
-                    attrs.update({"created_at": clock.ts, "created_by": clock.by})
+                # (a stamp, so at the second: `editorial_clock`)
+                born = editorial_clock(Clock(ts=attrs.get("created_at"),
+                                             by=attrs.get("created_by")))
+                stamp = editorial_clock(clock)
+                if stamp.stamped and (not born.stamped or clock_order(stamp, born) < 0):
+                    attrs.update({"created_at": stamp.ts, "created_by": stamp.by})
                     learned = True
                 mark = Clock.from_dict(attrs.get(REMOVED_KEY))
                 if mark.stamped and clock_order(clock, mark) > 0:
@@ -1234,7 +1358,8 @@ def apply_op_to_section(section: Dict[str, Any], op: Dict[str, Any], *,
                         else OpResult(False, "idempotent"))
         attrs = dict(declared)
         if clock.stamped:
-            attrs.update({"created_at": clock.ts, "created_by": clock.by})
+            stamp = editorial_clock(clock)
+            attrs.update({"created_at": stamp.ts, "created_by": stamp.by})
         if attrs:
             edge["attributes"] = attrs
         edges.append(edge)
@@ -1317,6 +1442,9 @@ def _stamp_payload(payload: Dict[str, Any], clock: Clock, *, creation: bool,
     """
     if not clock.stamped:
         return
+    # the op's clock is to the millisecond; the stamps it leaves stay at the
+    # second (E.D., 12 Oct 2026), compared as written — at the second
+    clock = editorial_clock(clock)
     data = payload.setdefault("data", {})
     if creation and not data.get("created_at"):
         data["created_at"] = clock.ts
@@ -1324,8 +1452,8 @@ def _stamp_payload(payload: Dict[str, Any], clock: Clock, *, creation: bool,
             data["created_by"] = clock.by
             if auth:
                 data["created_auth"] = dict(auth)
-    current = node_stamp(payload)
-    if clock_order(clock, current) >= 0:
+    current = editorial_clock(node_stamp(payload))
+    if newer(clock, current) is clock:
         data["modified_at"] = clock.ts
         if clock.by:
             data["modified_by"] = clock.by
@@ -1333,6 +1461,12 @@ def _stamp_payload(payload: Dict[str, Any], clock: Clock, *, creation: bool,
                 data["modified_auth"] = dict(auth)
             else:
                 data.pop("modified_auth", None)
+        else:
+            # a later hand nobody named: the previous hand is not the last any
+            # more, and leaving it beside this instant made a clock nobody had
+            # — one that depended on the order (measured, 12 Oct 2026)
+            data.pop("modified_by", None)
+            data.pop("modified_auth", None)
 
 
 def _op_auth(op: Dict[str, Any]):

{s3dgraphy-1.6.0.dev47 → s3dgraphy-1.6.0.dev49}/src/s3dgraphy/editorial.py

@@ -91,14 +91,56 @@ def normalize_auth(value: Any) -> Optional[Dict[str, str]]:
 def now_iso() -> str:
     """The current instant, UTC, second precision, ISO-8601 with a ``Z``.
 
-    Second precision on purpose: these stamps order edits and answer "when was
-    this touched", and microseconds would only add noise to every diff of every
-    em.json.
+    Second precision on purpose: these stamps (``created_at``, ``modified_at``)
+    answer "when was this touched", and microseconds would only add noise to
+    every diff of every em.json. What ORDERS two hands is the clock of an
+    operation, :func:`now_op_iso`.
     """
     return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace(
         "+00:00", "Z")
 
 
+def _op_instant(moment: datetime) -> str:
+    return (moment.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S")
+            + f".{moment.microsecond // 1000:03d}Z")
+
+
+def now_op_iso() -> str:
+    """The clock of an OPERATION: UTC, MILLISECOND precision, ``…:SS.mmmZ``.
+
+    E.D., 12 Oct 2026: the clock that orders two hands — an op's ``ts``, a
+    field's ``data.field_clocks.*.ts``, a tombstone — goes to the millisecond.
+    Measured on the table that morning: at the second, a correction made 300 ms
+    after another, in the same second, lost to it five times out of five
+    (decided by the smaller ORCID), and nobody saw. The editorial stamps stay at
+    the second (:func:`now_iso`). A clock at the second is still read and
+    compared: ``…:00Z`` is the same instant as ``…:00.000Z`` and earlier than
+    ``…:00.300Z``.
+    """
+    return _op_instant(datetime.now(timezone.utc))
+
+
+def normalize_op_instant(value: Any) -> Optional[str]:
+    """:func:`normalize_instant` for an operation's clock: the UTC spellings
+    come back as ``…:SS.mmmZ``, keeping the milliseconds — or as ``…:SSZ`` when
+    there are none, so that a clock written at the second keeps its spelling.
+    (``…:00.000Z`` through rdflib comes back as ``…:00Z``: the same instant.)"""
+    if value is None:
+        return None
+    text = str(value).strip()
+    if not text:
+        return None
+    try:
+        parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError:
+        return text
+    if parsed.tzinfo is None or parsed.utcoffset() != timezone.utc.utcoffset(None):
+        return text
+    if parsed.microsecond // 1000 == 0:
+        return normalize_instant(text)
+    return _op_instant(parsed)
+
+
 def normalize_orcid(value: Any) -> Optional[str]:
     """Reduce whatever was given to the canonical iD, or ``None``.
 

{s3dgraphy-1.6.0.dev47 → s3dgraphy-1.6.0.dev49}/src/s3dgraphy/importer/rdf_importer.py

@@ -1109,7 +1109,7 @@ class RDFImporter:
         ORCID IRI is returned to its bare canonical form, which is what the
         property graph stores.
         """
-        from ..editorial import normalize_instant, normalize_orcid
+        from ..editorial import normalize_instant, normalize_op_instant, normalize_orcid
 
         out: Dict[str, Any] = {}
         for key, pred in (("created_by", EM.createdBy),
@@ -1120,7 +1120,8 @@ class RDFImporter:
         # P4.1 · the tombstone comes back as a tombstone
         removed_at = self._one_literal(store, ref, EM.removedAt)
         if removed_at:
-            mark = {"ts": normalize_instant(removed_at)}
+            # an operation's clock: its milliseconds come back with it
+            mark = {"ts": normalize_op_instant(removed_at)}
             removed_by = self._one_object_text(store, ref, EM.removedBy)
             if removed_by:
                 mark["by"] = normalize_orcid(removed_by) or removed_by

{s3dgraphy-1.6.0.dev47 → s3dgraphy-1.6.0.dev49}/src/s3dgraphy/property_source.py

@@ -508,7 +508,9 @@ def remove_keeping_trace(graph, node_id: str, *, by: Optional[str] = None,
     if node is None:
         raise KeyError(f"no node {node_id!r}")
     deps = dependents_of(graph, node_id)
-    _ensure_data(node)[REMOVED_KEY] = Clock(ts=at or _now(), by=by).as_dict()
+    from .editorial import now_op_iso
+    # the CRDT's tombstone: an operation's clock, to the millisecond
+    _ensure_data(node)[REMOVED_KEY] = Clock(ts=at or now_op_iso(), by=by).as_dict()
     return {"node": node_id, "removed": node.data[REMOVED_KEY], "dependents": deps}