sysmlpy 0.96.2__tar.gz → 0.96.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysmlpy
-Version: 0.96.2
+Version: 0.96.4
 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.4}/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.4}/pyproject.toml

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

{sysmlpy-0.96.2 → sysmlpy-0.96.4}/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.4"
 
 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.4}/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",