sysmlpy 0.96.2__tar.gz → 0.96.3__tar.gz

{sysmlpy-0.96.2 → sysmlpy-0.96.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysmlpy
-Version: 0.96.2
+Version: 0.96.3
 Summary: 
 License-File: LICENSE
 Author: Jon R. Fox (mycr0ft)
@@ -987,6 +987,70 @@ See [`docs/plantuml-examples/`](docs/plantuml-examples/) for all rendered exampl
 | 15 | Relationship Matrix (GridView) | Relationship Matrix |
 | 16 | Tabular View — Color | Tabular View (color) |
 
+## Element Identity: Stable Interchange IDs
+
+Element `@id`s in interchange exports follow one of two schemes, and a
+reconciliation mechanism that follows the model across edits:
+
+**Default — position-derived (deterministic per source text).** Every
+`@graph` element gets `uuid5` from its tree position (parent id + key +
+index).  Same source text ⇒ byte-identical JSON in any process.
+
+```python
+from sysmlpy import to_interchange
+document = to_interchange(model)              # position-derived @ids
+```
+
+**`stable_ids=True` — content-addressed (L2 idempotency).** Named
+elements hash their declared qualified-name path + metaclass type;
+unnamed elements hash the nearest named anchor plus the structural path
+from it.  Inserting or reordering unrelated elements elsewhere leaves
+untouched ids unchanged:
+
+```python
+document = to_interchange(model, stable_ids=True)
+```
+
+```bash
+sysmlpy export model.sysml --stable-ids
+```
+
+**`reconcile_ids` — a registry sidecar (L3 identity).**  Content ids
+still re-mint when an *ancestor is renamed* (the qualified-name path
+changes) or an element moves to a different parent.  To follow a model
+across its lifetime, keep the previous export as a **registry file**
+and reconcile each new export against it: every element whose
+(declared name, type) matches exactly one registry entry adopts the
+registry's id.  Matching is injective — ambiguous (duplicated) keys
+match nothing and keep derived ids, so the document stays unique.
+
+```python
+from pathlib import Path
+from sysmlpy import loads, to_interchange, interchange_to_json_text
+
+registry_path = Path("model.json")
+document = (to_interchange(model, stable_ids=True)
+            if not registry_path.exists() else
+            to_interchange(model, reconcile_with=registry_path))
+registry_path.write_text(interchange_to_json_text(document))
+```
+
+Or as a one-liner on the CLI — the registry file is typically also the
+output file, making every export a fixed point after the first:
+
+```bash
+sysmlpy export model.sysml --reconcile-with model.json -o model.json
+```
+
+Round-trip guarantee: `from_interchange` on a reconciled document
+rebuilds the live model; re-exporting it *with the reconciled document
+as its registry* reproduces the identical `@graph`.  Elements renamed
+so thoroughly that no name matches fall back to fresh derived ids
+(becoming new registry entries on the next write).  See
+`docs/stable-identities.md` for the full analysis and
+`examples/element_identity.py` for a runnable walkthrough of all
+identity layers.
+
 ## ReqIF Interchange (Requirements Interchange Format)
 
 sysmlpy imports and exports **ReqIF 1.0** — the OMG requirements interchange

{sysmlpy-0.96.2 → sysmlpy-0.96.3}/README.md

@@ -951,6 +951,70 @@ See [`docs/plantuml-examples/`](docs/plantuml-examples/) for all rendered exampl
 | 15 | Relationship Matrix (GridView) | Relationship Matrix |
 | 16 | Tabular View — Color | Tabular View (color) |
 
+## Element Identity: Stable Interchange IDs
+
+Element `@id`s in interchange exports follow one of two schemes, and a
+reconciliation mechanism that follows the model across edits:
+
+**Default — position-derived (deterministic per source text).** Every
+`@graph` element gets `uuid5` from its tree position (parent id + key +
+index).  Same source text ⇒ byte-identical JSON in any process.
+
+```python
+from sysmlpy import to_interchange
+document = to_interchange(model)              # position-derived @ids
+```
+
+**`stable_ids=True` — content-addressed (L2 idempotency).** Named
+elements hash their declared qualified-name path + metaclass type;
+unnamed elements hash the nearest named anchor plus the structural path
+from it.  Inserting or reordering unrelated elements elsewhere leaves
+untouched ids unchanged:
+
+```python
+document = to_interchange(model, stable_ids=True)
+```
+
+```bash
+sysmlpy export model.sysml --stable-ids
+```
+
+**`reconcile_ids` — a registry sidecar (L3 identity).**  Content ids
+still re-mint when an *ancestor is renamed* (the qualified-name path
+changes) or an element moves to a different parent.  To follow a model
+across its lifetime, keep the previous export as a **registry file**
+and reconcile each new export against it: every element whose
+(declared name, type) matches exactly one registry entry adopts the
+registry's id.  Matching is injective — ambiguous (duplicated) keys
+match nothing and keep derived ids, so the document stays unique.
+
+```python
+from pathlib import Path
+from sysmlpy import loads, to_interchange, interchange_to_json_text
+
+registry_path = Path("model.json")
+document = (to_interchange(model, stable_ids=True)
+            if not registry_path.exists() else
+            to_interchange(model, reconcile_with=registry_path))
+registry_path.write_text(interchange_to_json_text(document))
+```
+
+Or as a one-liner on the CLI — the registry file is typically also the
+output file, making every export a fixed point after the first:
+
+```bash
+sysmlpy export model.sysml --reconcile-with model.json -o model.json
+```
+
+Round-trip guarantee: `from_interchange` on a reconciled document
+rebuilds the live model; re-exporting it *with the reconciled document
+as its registry* reproduces the identical `@graph`.  Elements renamed
+so thoroughly that no name matches fall back to fresh derived ids
+(becoming new registry entries on the next write).  See
+`docs/stable-identities.md` for the full analysis and
+`examples/element_identity.py` for a runnable walkthrough of all
+identity layers.
+
 ## ReqIF Interchange (Requirements Interchange Format)
 
 sysmlpy imports and exports **ReqIF 1.0** — the OMG requirements interchange

{sysmlpy-0.96.2 → sysmlpy-0.96.3}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "sysmlpy"
-version = "0.96.2"
+version = "0.96.3"
 description = ""
 authors = [{ name = "Jon R. Fox (mycr0ft)", email = "jon.fox@drfox.com" }]
 readme = "README.md"

{sysmlpy-0.96.2 → sysmlpy-0.96.3}/src/sysmlpy/__init__.py

@@ -20,6 +20,7 @@ __all__ = [
     "as_sequence_view", "as_case_view", "as_browser_view",
     "extract_traceability", "TraceabilityReport", "RequirementTrace",
     "to_interchange", "from_interchange", "interchange_to_json_text",
+    "reconcile_ids",
     "reqif_import", "reqif_import_model", "reqif_export",
     "evaluate_expression", "evaluate_calculation", "collect_values",
     "check_constraints", "ConstraintReport", "ConstraintResult",
@@ -35,7 +36,7 @@ __all__ = [
     "render_state_transition_view_svg", "boxes_view",
 ]
 __author__ = "Jon Fox"
-__version__ = "0.96.2"
+__version__ = "0.96.3"
 
 from sysmlpy.usage import (
     Item, Attribute, Part, Port, Action, Reference, UseCase, Requirement, Interface, Message,
@@ -57,6 +58,7 @@ from sysmlpy.traceability import (
 )
 from sysmlpy.interchange import (
     to_interchange, from_interchange, interchange_to_json_text,
+    reconcile_ids,
 )
 from sysmlpy.reqif_io import (
     reqif_import, reqif_import_model, reqif_export,

{sysmlpy-0.96.2 → sysmlpy-0.96.3}/src/sysmlpy/__main__.py

@@ -393,8 +393,22 @@ def cmd_export(args) -> int:
         print(f"Parse error: {e}", file=sys.stderr)
         return 2
 
+    # --reconcile-with <registry>: adopt ids from the previous export
+    # (the registry file itself is typically the output path — ids stay
+    # stable from then on, even across edits that re-mint derived ids).
+    reconcile_with = None
+    if getattr(args, "reconcile_with", None):
+        reg_path = Path(args.reconcile_with)
+        if reg_path.exists():
+            reconcile_with = reg_path
+        else:
+            print(f"Registry file '{reg_path}' not found — minting fresh "
+                  "stable ids (delete the flag or create the file to "
+                  "reconcile).", file=sys.stderr)
+
     try:
-        document = to_interchange(model)
+        document = to_interchange(model, stable_ids=args.stable_ids,
+                                  reconcile_with=reconcile_with)
     except Exception as e:
         print(f"Error: export failed on this model: {e}", file=sys.stderr)
         return 1
@@ -967,6 +981,20 @@ def build_parser() -> argparse.ArgumentParser:
         "--compact", action="store_true",
         help="Emit compact JSON (no indentation)",
     )
+    p_export.add_argument(
+        "--stable-ids", action="store_true",
+        help="Content-address element @ids (L2 idempotency): ids follow "
+             "declared qualified-name paths, so inserting/reordering "
+             "unrelated elements elsewhere leaves untouched ids unchanged",
+    )
+    p_export.add_argument(
+        "--reconcile-with", metavar="REGISTRY",
+        help="Adopt element @ids from a previous export document (implies "
+             "--stable-ids); ids of name-matched elements survive edits "
+             "(L3 identity): re-export repeatedly with "
+             "'--reconcile-with model.json -o model.json' to keep ids "
+             "stable across the model's lifetime",
+    )
     p_export.add_argument(
         "-l", "--library",
         help="Path to SysML v2 library files to use for parsing",

{sysmlpy-0.96.2 → sysmlpy-0.96.3}/src/sysmlpy/interchange.py

@@ -63,14 +63,18 @@ from __future__ import annotations
 
 import json as _json
 import uuid as _uuid
+from collections import Counter as _Counter
+from pathlib import Path as _Path
 
 __all__ = [
     "INTERCHANGE_CONTEXT",
     "INTERCHANGE_VOCABULARY",
     "INTERCHANGE_NAMESPACE",
+    "STABLE_NAMESPACE",
     "to_interchange",
     "from_interchange",
     "interchange_to_json_text",
+    "reconcile_ids",
     "build_jsonld_context",
 ]
 
@@ -108,33 +112,157 @@ def _child_id(parent_id: str, key: str, index: int) -> str:
     )
 
 
+# ---------------------------------------------------------------------------
+# stable (content-addressed) identifiers — L2 idempotency
+# ---------------------------------------------------------------------------
+
+#: UUID namespace for content-addressed ``stable_ids=True`` identifiers
+#: (distinct from :data:`INTERCHANGE_NAMESPACE` so the two schemes never
+#: collide even in theory).
+STABLE_NAMESPACE = _uuid.uuid5(
+    _uuid.NAMESPACE_URL,
+    "https://github.com/mycr0ft/sysmlpy/interchange/stable-ids",
+)
+
+
+def _identification_of(node: dict):
+    """The ``Identification`` node declared *by* this element, if any.
+
+    The parser models names as ``Identification`` dicts nested under
+    ``declaration``/``definition`` nodes; usages nest theirs under
+    ``declaration.declaration.identification``.  A recursive search
+    finds any shape without hard-coding the path — but it must not
+    descend through the containment edges (``ownedRelatedElement``,
+    ``body``): a wrapper (``PackageMember``, ``DefinitionElement``…)
+    merely *contains* named elements and must not claim their names.
+    Descending into them would let the root claim every name in the
+    model, corrupting every identity path.
+    """
+    if not isinstance(node, dict):
+        return None
+    if node.get("name") == "Identification":
+        return node
+    for k, v in node.items():
+        if k in ("ownedRelatedElement", "body"):
+            continue  # containment edges: names below belong to children
+        if isinstance(v, list):
+            for item in v:
+                found = _identification_of(item)
+                if found is not None:
+                    return found
+        elif isinstance(v, dict):
+            found = _identification_of(v)
+            if found is not None:
+                return found
+    return None
+
+
+class _StableIdAssigner:
+    """Content-addressed ``@id`` assignment over the visitor-dict tree.
+
+    An element's id hashes its *identity path*: the chain of declared
+    names from the root down to the nearest declared ancestor, plus the
+    element's own declared name (if any) and ``@type``.  Concretely:
+
+    - Named element: ``uuid5(STABLE_NAMESPACE, qn + "|" + type)``
+      where ``qn`` is the dot-joined declared names of the element and
+      all its declared ancestors (e.g. ``P.Engine.power``).
+    - Unnamed element below a declared ancestor: hashes the anchor QN,
+      the structural path from that ancestor (dictionary keys +
+      sibling indexes), and the ``@type`` — so it moves only if the
+      structure *between* it and its named anchor changes, never when
+      unrelated siblings elsewhere shift indexes.
+    - Root: hashes the tree path under the fixed ``"root"`` anchor.
+
+    Same-name sibling collisions (two ``part def Engine`` under one
+    parent) share a base hash; the occurrence index among content-key
+    siblings is appended so ids stay unique.  Elements in a collision
+    group shift when a group sibling is inserted before them — the
+    documented degradation for L2 (see docs/stable-identities.md).
+    """
+
+    def __init__(self):
+        #: base content-key -> next occurrence index
+        self._occurrence: dict = {}
+        #: node id() -> assigned @id (each dict node is visited once)
+        self._assigned: dict = {}
+
+    def id_for(self, node: dict, qn_path: tuple, struct_path: tuple) -> str:
+        ident = _identification_of(node) if isinstance(node, dict) else None
+        own_name = (ident or {}).get("declaredName")
+        type_name = node.get("name") if isinstance(node, dict) else None
+        if own_name:
+            qn = "|".join(qn_path + (own_name,))
+            key = f"{qn}|{type_name}"
+        else:
+            key = "root" if not qn_path and not struct_path else (
+                "|".join(qn_path) + "||" + _struct_text(struct_path)
+                + f"|{type_name}"
+            )
+        n = self._occurrence.get(key, 0)
+        self._occurrence[key] = n + 1
+        if n:
+            key = f"{key}|#{n}"
+        return "sysml:" + str(_uuid.uuid5(STABLE_NAMESPACE, key))
+
+
+def _struct_text(struct_path: tuple) -> str:
+    return ">".join(f"{key}:{i}" for key, i in struct_path)
+
+
 def _flatten(node: dict, parent_id: str, key: str, index: int,
-             graph: list) -> str:
+             graph: list, assigner: "_StableIdAssigner | None" = None,
+             parent_qn: tuple = (), parent_struct: tuple = ()) -> str:
     """Recursively flatten a visitor-dict node into the graph.
 
+    With ``assigner=None`` (default) ids are position-derived
+    (``_child_id``).  With an :class:`_StableIdAssigner`, ids are
+    content-addressed: named elements hash their qualified-name path,
+    unnamed elements hash the nearest named anchor plus the structural
+    path from it — see :class:`_StableIdAssigner`.
+
     Returns the ``@id`` assigned to this node.
     """
-    elem_id = _child_id(parent_id, key, index)
+    if assigner is not None:
+        struct_path = parent_struct + ((key, index),)
+        elem_id = assigner.id_for(node, parent_qn, struct_path)
+        ident = _identification_of(node)
+        own_name = (ident or {}).get("declaredName")
+        child_qn = parent_qn + ((own_name,) if own_name else ())
+        child_struct = struct_path
+    else:
+        elem_id = _child_id(parent_id, key, index)
+        child_qn = ()
+        child_struct = ()
     elem = {"@id": elem_id, "@type": node.get("name")}
     for k, v in node.items():
         if k == "name":
             continue  # captured as @type
-        elem[k] = _flatten_value(v, elem_id, k, graph)
+        elem[k] = _flatten_value(v, elem_id, k, graph,
+                                 assigner=assigner, parent_qn=child_qn,
+                                 parent_struct=child_struct)
     graph.append(elem)
     return elem_id
 
 
-def _flatten_value(v, elem_id: str, key: str, graph: list):
+def _flatten_value(v, elem_id: str, key: str, graph: list,
+                   assigner: "_StableIdAssigner | None" = None,
+                   parent_qn: tuple = (), parent_struct: tuple = ()):
     """Flatten one property value: dicts become @id refs, scalars inline."""
     if v is None or isinstance(v, (str, int, float, bool)):
         return v
     if isinstance(v, dict):
-        return {"@id": _flatten(v, elem_id, key, 0, graph)}
+        return {"@id": _flatten(v, elem_id, key, 0, graph,
+                                assigner=assigner, parent_qn=parent_qn,
+                                parent_struct=parent_struct)}
     if isinstance(v, list):
         out = []
         for i, item in enumerate(v):
             if isinstance(item, dict):
-                out.append({"@id": _flatten(item, elem_id, key, i, graph)})
+                out.append({"@id": _flatten(item, elem_id, key, i, graph,
+                                            assigner=assigner,
+                                            parent_qn=parent_qn,
+                                            parent_struct=parent_struct)})
             else:
                 out.append(item)
         return out
@@ -230,7 +358,8 @@ def _extract_properties(source):
     return props, types
 
 
-def to_interchange(source, *, vocabulary=None, explicit_terms=False):
+def to_interchange(source, *, vocabulary=None, explicit_terms=False,
+                   stable_ids=False, reconcile_with=None):
     """Export a model to the SysML v2 JSON interchange representation.
 
     Parameters
@@ -246,6 +375,30 @@ def to_interchange(source, *, vocabulary=None, explicit_terms=False):
         ``property → <vocabulary>#property`` term definitions for
         every property and metaclass in the document (see
         :func:`build_jsonld_context`).
+    stable_ids : bool
+        When true, ``@id``s are **content-addressed** (L2 idempotency):
+        named elements hash their qualified-name path and ``@type``,
+        unnamed elements hash the nearest named ancestor plus the
+        structural path from it.  Inserting or reordering unrelated
+        siblings elsewhere in the document then leaves every
+        untouched element's id unchanged — with the default
+        position-derived ids those ids all shift.  Same-name sibling
+        groups (two ``part def Engine`` under one parent) are
+        disambiguated by occurrence index; ids inside such a group do
+        shift on group-local insertion.  See
+        ``docs/stable-identities.md`` for the full analysis.
+    reconcile_with : dict or str, optional
+        A previous export (document dict or JSON text of one) to adopt
+        ids from — see :func:`reconcile_ids`.  Implies
+        ``stable_ids=True`` (reconciled re-exports must replay the
+        same id scheme the registry was written with).  The typical
+        workflow keeps the *previous* export file as the registry::
+
+            if Path("model.json").exists():
+                doc = to_interchange(model, reconcile_with="model.json")
+            else:
+                doc = to_interchange(model, stable_ids=True)
+            Path("model.json").write_text(interchange_to_json_text(doc))
 
     Returns
     -------
@@ -285,7 +438,9 @@ def to_interchange(source, *, vocabulary=None, explicit_terms=False):
         )
 
     graph: list = []
-    root_id = _flatten(root_dict, "root", "ownedRelationship", 0, graph)
+    assigner = _StableIdAssigner() if (stable_ids or reconcile_with) else None
+    root_id = _flatten(root_dict, "root", "ownedRelationship", 0, graph,
+                       assigner=assigner)
     context = dict(INTERCHANGE_CONTEXT)
     if vocabulary:
         context["@vocab"] = vocabulary.rstrip("/#") + "#"
@@ -293,11 +448,138 @@ def to_interchange(source, *, vocabulary=None, explicit_terms=False):
         context = build_jsonld_context(
             {"@graph": graph}, vocabulary=vocabulary
         )
-    return {
+    document = {
         "@context": context,
         "@id": root_id,
         "@graph": graph,
     }
+    if reconcile_with is not None:
+        document = reconcile_ids(document, reconcile_with)
+    return document
+
+
+# ---------------------------------------------------------------------------
+# id registry reconciliation — L3 identity across edits (Phase 2 sidecar)
+# ---------------------------------------------------------------------------
+
+
+def _remap_refs(value, remap: dict):
+    """Rewrite every ``{"@id": old}`` ref to ``{"@id": new}``.  Top-level
+    element ids are rewritten by :func:`reconcile_ids` directly; this
+    walks nested property values (references, chains) so adopted ids
+    are consistent everywhere the document is rebuilt from."""
+    if isinstance(value, dict):
+        if set(value.keys()) == {"@id"}:
+            new_id = remap.get(value["@id"])
+            if new_id is not None:
+                value["@id"] = new_id
+            return
+        for v in value.values():
+            _remap_refs(v, remap)
+    elif isinstance(value, list):
+        for item in value:
+            _remap_refs(item, remap)
+
+
+def reconcile_ids(document: dict, registry) -> dict:
+    """Adopt element ids from a previous interchange export (the registry).
+
+    The registry is a previously exported document (``to_interchange``
+    output, as dict or JSON text) whose ``@graph`` maps ``@id`` to
+    ``(declaredName, @type)``.  Every element of ``document`` whose
+    ``(declaredName, @type)`` matches **exactly one** registry entry —
+    and exactly one same-key element in ``document`` — inherits the
+    registry's ``@id`` instead of its freshly derived one.  This is the
+    mechanism that keeps ids stable across edits that re-mint derived
+    ids (ancestor renames, re-nesting): identity follows the declared
+    name wherever the name survives the edit.
+
+    Matching is deliberately **injective**:
+
+    - the key must be unique on BOTH sides — when the model grows a
+      second ``PartDefinition`` while the registry has one, neither is
+      matched (a naive many-to-one adoption produced duplicate ids in
+      every rename-plus-insert scenario during the design spike);
+    - an old id already adopted by an earlier element is never adopted
+      again (first match wins in registry order);
+    - unmatched elements keep their freshly derived ids and become new
+      registry entries when the document is written back out.
+
+    Intended workflow (the export file doubles as the registry)::
+
+        document = to_interchange(model, stable_ids=True)
+        if Path("model.json").exists():
+            document = reconcile_ids(document, Path("model.json"))
+        Path("model.json").write_text(interchange_to_json_text(document))
+
+    Parameters
+    ----------
+    document : dict
+        A freshly exported document (``to_interchange`` output).
+    registry : dict or str
+        The previous export: a document dict or a JSON string (the
+        text form loads the sidecar file directly).
+
+    Returns
+    -------
+    dict
+        ``document`` with adopted ids (modified in place and returned).
+    """
+    if isinstance(registry, (_Path, str)):
+        # Accept a filesystem path to a registry file (including
+        # ``Path`` objects), OR the previous export as JSON text /
+        # document dict.  A str that names an existing, plausibly
+        # small file loads from disk; anything else is JSON text.
+        # (A str is only treated as a path if its length is a sane
+        # filename length — JSON documents can be megabytes.)
+        if isinstance(registry, _Path) or (
+                isinstance(registry, str) and len(registry) < 4097
+                and "\n" not in registry and _Path(registry).exists()):
+            registry = _Path(registry).read_text(encoding="utf-8-sig")
+        registry = _json.loads(registry)
+    if not isinstance(registry, dict):
+        raise ValueError(
+            "registry must be an interchange document dict or JSON "
+            f"string, got {type(registry).__name__}")
+    old_graph = registry.get("@graph")
+    new_graph = document.get("@graph")
+    if not isinstance(old_graph, list) or not isinstance(new_graph, list):
+        raise ValueError("both documents need an @graph array")
+
+    def _key(e):
+        return (e.get("declaredName"), e.get("@type"))
+
+    old_counts = _Counter(_key(e) for e in old_graph)
+    new_counts = _Counter(_key(e) for e in new_graph)
+    by_key: dict = {}
+    for e in old_graph:
+        k = _key(e)
+        # unique on BOTH sides — injective matching (see docstring)
+        if k in old_counts and old_counts[k] == 1 and new_counts.get(k) == 1 \
+                and k not in by_key:
+            by_key[k] = e["@id"]
+    used: set = set()
+
+    # id re-map for refs: a matched element's *derived* id (assigned
+    # during this export) must yield to the adopted registry id in
+    # EVERY nested ``{"@id": ...}`` reference too — element ids are
+    # only the top level; typed-by references, target refs and child
+    # chains all point at the derived ids and would dangle after a
+    # top-level-only rewrite.
+    remap: dict = {}
+    for e in new_graph:
+        k = _key(e)
+        old_id = by_key.get(k)
+        if old_id is not None and old_id not in used:
+            used.add(old_id)
+            derived_id = e["@id"]
+            e["@id"] = old_id
+            remap[derived_id] = old_id
+
+    if remap:
+        for e in new_graph:
+            _remap_refs(e, remap)
+    return document
 
 
 def interchange_to_json_text(document: dict, *, indent: int = 2) -> str: