Support typed sibling bindings for fidelity ladders

Three sibling MetadataUsages all named verificationBinding cannot get
stable ids (their qualified names collide), so a ladder needs the
SysML-native form: named usages typed by one 'metadata def
verificationBinding'. extract_bindings and rule S2K010 now share an
is_binding predicate accepting either form; the writer renders the
typing ('metadata analyticBinding : verificationBinding about ...'); the
parser keeps a named usage's typing as its definition ref and maps
'metadata def' declarations; builder.metadata gains a definition
parameter and builder.metadata_def creates the annotation kind.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NoLtnms93KQL7Jsp9GrZZo

Author: jman4162

src/sysml2kit/backends/sysmlpy.py

@@ -24,7 +24,7 @@
 from sysml2kit.model.analysis import AnalysisCaseDefinition, AnalysisCaseUsage
 from sysml2kit.model.base import Element, Ref
 from sysml2kit.model.container import Model
-from sysml2kit.model.metadata import MetadataUsage
+from sysml2kit.model.metadata import MetadataDefinition, MetadataUsage
 from sysml2kit.model.relations import (
     AllocateRelationship,
     DeriveRelationship,
@@ -67,6 +67,7 @@
     "AnalysisCaseDefinition": AnalysisCaseDefinition,
     "AnalysisCaseUsage": AnalysisCaseUsage,
     "ConnectionUsage": ConnectionUsage,
+    "MetadataDefinition": MetadataDefinition,
 }
 
 #: Keys never descended when extracting declaration-level facts.
@@ -431,6 +432,14 @@ def _walk(self, node: Any, model: Model, owner: Element | None, state: _WalkStat
             )
             metadata_element = MetadataUsage(declared_name=name, values=values)
             model.add(metadata_element, owner=owner)
+            # A named-and-typed usage (``metadata x : verificationBinding``)
+            # keeps its typing as a definition ref; when the name itself came
+            # from the typing slot there is nothing separate to resolve.
+            ident = node.get("identification")
+            if isinstance(ident, dict) and ident.get("declaredName"):
+                typing = _first(node.get("ownedFeatureTyping"), "QualifiedName")
+                if typing and typing.get("names"):
+                    state.typings.append((metadata_element, list(typing["names"])))
             if annotated:
                 state.annotations.append((metadata_element, annotated))
             return

src/sysml2kit/model/builder.py

@@ -10,7 +10,7 @@
 from sysml2kit.model.analysis import AnalysisCaseDefinition, AnalysisCaseUsage
 from sysml2kit.model.base import Element, Ref
 from sysml2kit.model.container import Model
-from sysml2kit.model.metadata import MetadataUsage
+from sysml2kit.model.metadata import MetadataDefinition, MetadataUsage
 from sysml2kit.model.relations import (
     AllocateRelationship,
     DeriveRelationship,
@@ -193,19 +193,40 @@ def metadata(
     *,
     owner: Element | None = None,
     name: str | None = None,
+    definition: Element | None = None,
 ) -> MetadataUsage:
     """Attach a key-value metadata annotation to an element.
 
     Default ownership is the annotated element's owner (package level): the
     ``about`` reference carries the attachment, and package-level placement
     is what survives the textual notation (metadata inside definition bodies
-    is dropped by the parser).
+    is dropped by the parser). Passing ``definition`` types the usage by a
+    ``metadata def``, which lets sibling annotations carry distinct names
+    (a fidelity ladder) while sharing one annotation kind.
     """
-    usage = MetadataUsage(declared_name=name, annotated=Ref.to(annotated), values=dict(values))
+    usage = MetadataUsage(
+        declared_name=name,
+        annotated=Ref.to(annotated),
+        values=dict(values),
+        definition=Ref.to(definition) if definition is not None else None,
+    )
     default_owner = model.owner_of(annotated) or annotated
     return model.add(usage, owner=owner if owner is not None else default_owner)  # type: ignore[return-value]
 
 
+def metadata_def(
+    model: Model,
+    name: str,
+    *,
+    owner: Element | None = None,
+    doc: str | None = None,
+) -> MetadataDefinition:
+    """Add a reusable metadata annotation kind (``metadata def``)."""
+    return model.add(  # type: ignore[return-value]
+        MetadataDefinition(declared_name=name, doc=doc), owner=owner
+    )
+
+
 def _relate(
     model: Model,
     cls: type[SatisfyRelationship | VerifyRelationship | DeriveRelationship | AllocateRelationship],

src/sysml2kit/text/writer.py

@@ -186,6 +186,8 @@ def _render_attribute(model: Model, element: AttributeUsage, indent: str) -> str
 def _render_metadata(model: Model, element: MetadataUsage, indent: str) -> str:
     about = f" about {_name_of(model, element.annotated)}" if element.annotated else ""
     name = f" {escape_name(element.declared_name)}" if element.declared_name else ""
+    if element.definition is not None:
+        name += f" : {_name_of(model, element.definition)}"
     if not element.values:
         return f"{indent}metadata{name}{about};"
     inner = indent + _INDENT

src/sysml2kit/validation.py

@@ -193,7 +193,9 @@ def fidelity_ladder_shape(model: Model) -> Iterator[ValidationIssue]:
     per_analysis: dict[UUID, list[str | None]] = {}
     for el in model.iter_elements(kind=MetadataUsage):
         assert isinstance(el, MetadataUsage)
-        if el.declared_name != "verificationBinding" or el.annotated is None:
+        from sysml2kit.verify.binding import is_binding
+
+        if not is_binding(model, el) or el.annotated is None:
             continue
         label = el.values.get("fidelity")
         per_analysis.setdefault(el.annotated.target, []).append(

src/sysml2kit/verify/binding.py

@@ -31,6 +31,21 @@
 _PAYLOAD_PREFIX = "payload."
 
 
+def is_binding(model: Model, element: MetadataUsage) -> bool:
+    """Whether this metadata usage is a verificationBinding.
+
+    Either the usage itself is named ``verificationBinding`` or it is a
+    named usage typed by a ``metadata def verificationBinding`` — the
+    typed form is what lets several sibling bindings (a fidelity ladder)
+    coexist with distinct names.
+    """
+    if element.declared_name == BINDING_NAME:
+        return True
+    if element.definition is not None and element.definition.target in model.elements:
+        return model.resolve(element.definition).declared_name == BINDING_NAME
+    return False
+
+
 class BindingError(ValueError):
     """A verificationBinding metadata is malformed or unresolvable."""
 
@@ -59,7 +74,7 @@ def extract_bindings(model: Model) -> list[VerificationBinding]:
     bindings: list[VerificationBinding] = []
     for element in model.iter_elements(kind=MetadataUsage):
         assert isinstance(element, MetadataUsage)
-        if element.declared_name != BINDING_NAME:
+        if not is_binding(model, element):
             continue
         if element.annotated is None:
             raise BindingError(f"binding {element.element_id} annotates nothing")

tests/test_backend_fidelity.py

@@ -22,6 +22,7 @@
     builder,
 )
 from sysml2kit.text import write_model
+from sysml2kit.verify.binding import extract_bindings
 
 pytestmark = pytest.mark.parse
 
@@ -246,3 +247,40 @@ def test_full_traceability_round_trip():
     (binding,) = extract_bindings(reparsed)
     assert binding.engine == "fake"
     assert binding.config_ref == "c.json"
+
+
+def test_typed_binding_ladder_round_trip():
+    """Named usages typed by 'metadata def verificationBinding' survive text."""
+    model = Model()
+    pkg = builder.pkg(model, "Ladder")
+    binding_def = builder.metadata_def(model, "verificationBinding", owner=pkg)
+    analysis = builder.analysis(model, "study", owner=pkg)
+    builder.metadata(
+        model,
+        analysis,
+        {"engine": "a", "fidelity": "analytic", "costSeconds": 0.001},
+        name="analyticBinding",
+        definition=binding_def,
+    )
+    builder.metadata(
+        model,
+        analysis,
+        {"engine": "b", "fidelity": "pattern", "costSeconds": 1.0},
+        name="patternBinding",
+        definition=binding_def,
+    )
+    model.assign_stable_ids()  # distinct names: no sibling clash
+
+    reparsed = backend.parse(write_model(model))
+    bindings = {b.fidelity: b for b in extract_bindings(reparsed)}
+    assert set(bindings) == {"analytic", "pattern"}
+    assert bindings["analytic"].engine == "a"
+    assert bindings["pattern"].cost_s == 1.0
+
+
+def test_plain_named_metadata_is_not_a_binding():
+    model = Model()
+    pkg = builder.pkg(model, "P")
+    analysis = builder.analysis(model, "study", owner=pkg)
+    builder.metadata(model, analysis, {"engine": "a"}, name="somethingElse")
+    assert extract_bindings(model) == []

tests/test_validation.py

@@ -100,4 +100,5 @@ def test_s2k010_mixed_labeling_warns(vehicle: Model):
     )
     builder.metadata(vehicle, analysis, {"engine": "b"}, name="verificationBinding")
     issues = [i for i in validate(vehicle) if i.rule_id == "S2K010"]
-    assert issues and issues[0].severity == "warning"
+    assert issues
+    assert issues[0].severity == "warning"

tests/test_verify.py

@@ -258,7 +258,8 @@ def test_fidelity_ladder_escalate_policy():
     run = run_verification(model, registry=registry, policy="escalate", budget_s=10.0)
     assert calls == ["cheap", "costly"]  # thin margin (401 vs 400) escalated
     escalated = [v for v in run.requirements if v.escalated_from]
-    assert escalated and escalated[0].escalated_from == "analytic"
+    assert escalated
+    assert escalated[0].escalated_from == "analytic"
     assert escalated[0].fidelity == "pattern"
     assert set(run.seconds_by_fidelity) == {"analytic", "pattern"}
     assert run.passed