@memoarchitect/ontology 0.6.5 → 0.8.22

package/src/core/relationships/memo_relationships.sysml

@@ -1,6 +1,9 @@
 package memo_core_relationships {
+    private import Metaobjects::SemanticMetadata;
     private import ScalarValues::*;
 
+    private import Connections::BinaryConnection;
+
     private import memo_core_common::*;
     private import memo_core_enumerations::*;
 
@@ -8,13 +11,52 @@ package memo_core_relationships {
     // Connection/Association), specializing the MemoRelationship base. The
     // relationship name is the verb; the RelationshipRegistry derives the
     // navigable type as camelCase(name) and navigation is bidirectional.
-    // Structural properties of a relation, declared here so authoring and
-    // validation read them from the ontology instead of assuming them. Both are
-    // unset on the base and carry the conservative reading: a relation forbids
-    // self-links and forbids repeats unless it says otherwise. A subtype opts
-    // out by redefining, e.g. `attribute :>> isReflexive = true;`.
-    abstract connection def MemoRelationship {
-        attribute linkStatus : LinkStatusKind;
+    //
+    // MemoRelationship roots on the SysML v2 standard library's
+    // Connections::BinaryConnection rather than floating free. Every two-ended
+    // `connection def` implicitly specializes it anyway; saying so explicitly
+    // is what lets MEMO relations be read as ordinary SysML connections by any
+    // conforming tool instead of as a MEMO-private construct.
+    //
+    // A relation is a MEMO element like any other, so it carries the same
+    // identification core as the part/action/item/requirement bases in
+    // memo_core_common — with four exceptions, R10-S5 (2026-08-13). `name`,
+    // `description`, `rationale` and `status` were declared here too, and a
+    // tree measurement found them dead weight: across every connection usage
+    // in src/ and examples/ (876 of them, 77 with a body at all), exactly one
+    // ever set `rationale` and none ever set `name`, `description` or
+    // `status`. The former `linkStatus` (planned/active/verified/obsolete) is
+    // already gone for the same reason: a link being "verified" was never an
+    // editorial state.
+    //
+    // The replacement is native, not a MEMO-authored substitute:
+    //   - `name`        → the connection usage's own declared name
+    //     (`connection linkFoo : Bar …`), which every usage already has.
+    //   - `description` → `doc /* … */` on the usage.
+    //   - `rationale`   → standard `Rationale` metadata: `@Rationale { :>> text
+    //     = "…"; }` (ModelingMetadata.sysml:95). `text` is exported into
+    //     `rel.attributes.rationale` by the builder, same key as before.
+    //   - `status`      → standard `StatusInfo` metadata: `@StatusInfo { :>>
+    //     status = StatusKind::…; }` (ModelingMetadata.sysml:60). StatusKind
+    //     (open/tbd/tbr/tbc/done/closed) is NOT ElementStatusKind
+    //     (proposed/draft/inReview/approved/released/deprecated/retired) — the
+    //     mapping between them, and why no MEMO-side conversion code exists, is
+    //     recorded in docs/reference/naming-and-native-constructs.md. Exported
+    //     into `rel.attributes.status`.
+    // Both metadata defs live in the standard `ModelingMetadata` package;
+    // `private import ModelingMetadata::*;` wherever they are applied.
+    //
+    // isReflexive/isUnique are structural properties of the relation itself,
+    // declared here so authoring and validation read them from the ontology
+    // instead of assuming them. Both are unset on the base and carry the
+    // conservative reading: a relation forbids self-links and forbids repeats
+    // unless it says otherwise. A subtype opts out by redefining, e.g.
+    // `attribute :>> isReflexive = true;`.
+    abstract connection def MemoRelationship :> Connections::BinaryConnection {
+        attribute id : String;
+        attribute uuid : String;
+        attribute shortDescription : String;
+        attribute sourceReference : String;
         doc /* True when an element may be related to itself by this relation.
              * Unset is read as false. */
         attribute isReflexive : Boolean;
@@ -24,209 +66,170 @@ package memo_core_relationships {
         attribute isUnique : Boolean;
     }
 
+    // ─── Metaclass-neutral ends (Track A0) ──────────────────────────────
+    //
+    // An end is left UNTYPED (`:>> source` / `:>> target`) wherever its
+    // legitimate endpoints do not share a MEMO base, and a rule in
+    // memo_rules_ontology states the constraint the type used to state.
+    //
+    // The reason is structural, not stylistic. KerML will not let a port or a
+    // behaviour specialize a part-based type, so a `MemoPart`-typed end forces
+    // everything it accepts to be a part. That is what made PhysicalPort and
+    // SoftwarePort part defs (so they could terminate exchanges), what made
+    // SystemFunction a part def with its behaviour stapled on through a
+    // separate action def, and what makes `allocate <function> to <actor>` —
+    // ARCADIA's own System Analysis mechanism — illegal, since Actor is a
+    // MemoPart but not an ArchitectureElement.
+    //
+    // Several of the relaxed ends were ALREADY being violated by real content
+    // before they were relaxed: `composes` links parts to WorkflowStep and
+    // OperationalActivity (action defs) and to SoftwarePort/PhysicalPort;
+    // `precedes` links OperationalActivity to OperationalActivity; `allocatedTo`
+    // has ActionUsage sources; `bindsToInterface` targets an `interface def`,
+    // which an InterfaceElement-typed end cannot hold. The types were not
+    // buying the strictness they appeared to buy.
+    //
+    // What is NOT relaxed stays typed on purpose: `verificationCase` and
+    // `validationCase` are verification defs, `performed` and `enabled` are
+    // MemoActions, `targetRequirement` is a MemoRequirementElement. Those ends
+    // name one metaclass and mean it.
+    //
+    // The strictness did not evaporate — see CR-ONT-060..CR-ONT-071 in
+    // src/rules/ontology/ontology_invariants.sysml. Relaxing the ends without
+    // those rules would have been a silent loss of every constraint the ends
+    // were carrying.
+    //
     // The general relation that can join any two model elements, whatever
-    // their metaclass. Most specific relations type their ends against a
-    // foundation (MemoPart, VerifiableElement, …). A small number of specific
-    // cross-metaclass relations leave an end untyped because their accepted
-    // constructs have no shared MEMO base; their names and attributes still
-    // carry a precise engineering meaning. MemoLink leaves both ends untyped
-    // and adds no domain-specific semantics, which is what makes it universal.
+    // their metaclass. MemoLink leaves both ends untyped and adds no
+    // domain-specific semantics, which is what makes it universal.
     //
     // It is deliberately the weakest relation in the ontology. Reach for it
-    // only when no specific relation carries the meaning, and say why in
-    // linkRationale — an untyped link with no stated reason is an audit gap,
-    // not a model fact.
+    // only when no specific relation carries the meaning, and say why in the
+    // inherited `rationale` — an untyped link with no stated reason is an
+    // audit gap, not a model fact.
     connection def MemoLink :> MemoRelationship {
         doc /* Generic association between any two model elements. */
-        attribute linkRationale : String;
-        end linkSource;
-        end linkTarget;
+        end linkSource :>> source;
+        end linkTarget :>> target;
+    }
+    abstract connection memoLinkLinks : MemoLink[*];
+    metadata def <memoLink> MemoLinkMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = memoLinkLinks meta SysML::Usage;
     }
 
     connection def DerivesFrom :> MemoRelationship {
-        // Drivers include needs and hazards (ISO 14971: hazards drive
-        // requirements). targetRequirement is untyped: Need is a requirement def
-        // (MemoNeed + RequirementDriver) and does not conform to VerifiableElement
-        // under SysIDE related-feature-conformance.
-        end sourceDriver : MemoPart;
-        end targetRequirement;
-    }
-    connection def SatisfiedBy :> MemoRelationship {
-        // Untyped: Need (requirement) instances must participate alongside Requirement.
-        end requiredElement;
-        end satisfyingElement : ArchitectureElement;
-    }
-    // Mitigates unifies the control/action → risk-element edges of the
-    // ISO 14971 / FMEA / FTA / cyber chains — MitigatesHazard,
-    // MitigatesVulnerability, MitigatedByControl, BrokenByControl,
-    // AddressedByAction — keyed by mitigationKind. control is the mitigating
-    // control/action; mitigatedElement is the hazard/vulnerability/failure/cut set.
-    enum def MitigationKind {
-        enum hazard;
-        enum vulnerability;
-        enum failureMode;
-        enum cutSet;
-        enum fmeaAction;
-    }
-    connection def Mitigates :> MemoRelationship {
-        attribute mitigationKind : MitigationKind;
-        // Untyped: controls/hazards may be item defs (RiskControlMeasure, Hazard, …).
-        end control;
-        end mitigatedElement;
-    }
-    connection def AllocatedTo :> MemoRelationship {
-        end function : ArchitectureElement;
-        end allocatedElement : ArchitectureElement;
-    }
-    // Realizes is the single realization relation (realizing/concrete element →
-    // realized/abstract element). It unifies RealizesInterface,
-    // RealizesComponentExchange, RealizedByArchitecture, RealizesScenario,
-    // ModuleRealizesLogical, ComponentRealizesModule, PhysicalModuleRealizesLogical,
+        // Drivers span metaclasses — a need is a requirement def, a hazard an
+        // item, a threat an item — so the source end stays untyped. The target
+        // is now typed: since Requirement re-rooted onto MemoRequirement, one
+        // type name covers the whole requirement family.
+        end sourceDriver :>> source;
+        end targetRequirement : MemoRequirementElement :>> target;
+    }
+    abstract connection derivesFromLinks : DerivesFrom[*];
+    metadata def <derivesFrom> DerivesFromMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = derivesFromLinks meta SysML::Usage;
+    }
+    // `Realizes` (realizing/concrete element → realized/abstract element) is
+    // native `#refinement dependency` (R10-S6): write
+    // `#refinement dependency <realizing> to <realized>;` instead. It used to
+    // unify RealizesInterface, RealizesComponentExchange,
+    // RealizedByArchitecture, RealizesScenario, ModuleRealizesLogical,
+    // ComponentRealizesModule, PhysicalModuleRealizesLogical,
     // Implements{Component,Procedure}, UIRealizesFunctional,
-    // FunctionalRealizesOper{ative,ational} and ScenarioRealizesUseCase.
-    connection def Realizes :> MemoRelationship {
-        end realizing : MemoPart;
-        end realized : MemoPart;
-    }
-    connection def VerifiedBy :> MemoRelationship {
-        // Requirements, risk controls, and architecture components are
-        // all legitimate verification targets
-        end verificationTarget : MemoPart;
-        end verificationCase : MemoVerificationCase;
-    }
+    // FunctionalRealizesOper{ative,ational} and ScenarioRealizesUseCase; the
+    // native form keeps that reach, since `#refinement` places no metaclass
+    // restriction on either end.
     connection def ProducesEvidence :> MemoRelationship {
-        end producer : MemoVerificationCase;
-        end producedEvidence : MemoEvidence;
-    }
-    connection def IncludedIn :> MemoRelationship {
-        end sourceElement : MemoPart;
-        end targetView : MemoPart;
-    }
-    connection def Precedes :> MemoRelationship {
-        attribute sameStepRequired : Boolean;
-        attribute precedenceRationale : String;
-        end predecessor : ArchitectureElement;
-        end successor : ArchitectureElement;
-    }
-    connection def ResolvesToMethodology :> MemoRelationship {
-        end boundModelElement : MemoPart;
-        end resolvedMethodology : MemoPart;
-    }
-
-    // ISO 14971 risk chain — distinct sequence-of-events relations over risk elements.
-    connection def TracesRisk :> MemoRelationship {
-        end sourceRiskElement : MemoPart;
-        end targetRiskElement : MemoPart;
-    }
-    connection def AssessedAgainst :> MemoRelationship {
-        end risk : MemoPart;
-        end riskMatrix : MemoPart;
-    }
+        end producer : MemoVerificationCase :>> source;
+        end producedEvidence : MemoEvidence :>> target;
+    }
+    abstract connection producesEvidenceLinks : ProducesEvidence[*];
+    metadata def <producesEvidence> ProducesEvidenceMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = producesEvidenceLinks meta SysML::Usage;
+    }
+    // `Precedes` is native `succession` (`first a then b;`), R10-S6.
+    // `sameStepRequired`/`precedenceRationale` had zero usages anywhere in
+    // the tree (same free-deletion shape R10-S5 found for `rationale`), so
+    // there was no content to carry forward.
 
     connection def ThreatenedBy :> MemoRelationship {
         attribute threatRole : String;
-        end protectedAsset : ArchitectureElement;
-        end realizedThreat : RequirementDriver;
+        end protectedAsset : ArchitectureElement :>> source;
+        end realizedThreat : RequirementDriver :>> target;
     }
-    connection def Exploits :> MemoRelationship {
-        end realizedThreat : RequirementDriver;
-        end enablingVulnerability : MemoPart;
-    }
-    connection def RealizedByScenario :> MemoRelationship {
-        end realizedThreat : RequirementDriver;
-        end scenario : MemoPart;
+    abstract connection threatenedByLinks : ThreatenedBy[*];
+    metadata def <threatenedBy> ThreatenedByMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = threatenedByLinks meta SysML::Usage;
     }
     connection def DerivesCyberRequirement :> MemoRelationship {
-        end sourceThreatOrRisk : RequirementDriver;
-        end targetRequirement : VerifiableElement;
+        end sourceThreatOrRisk : RequirementDriver :>> source;
+        end targetRequirement : MemoRequirementElement :>> target;
     }
-    connection def ImpactsSafety :> MemoRelationship {
-        attribute tracePurpose : String;
-        end cyberElement : MemoPart;
-        end safetyElement : MemoPart;
+    abstract connection derivesCyberRequirementLinks : DerivesCyberRequirement[*];
+    metadata def <derivesCyberRequirement> DerivesCyberRequirementMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = derivesCyberRequirementLinks meta SysML::Usage;
     }
     connection def CrossesTrustBoundary :> MemoRelationship {
         attribute crossingKind : InterfaceKind;
-        end boundary : InterfaceElement;
-        end crossingItem : MemoPart;
+        end boundary :>> source;
+        end crossingItem :>> target;
+    }
+    abstract connection crossesTrustBoundaryLinks : CrossesTrustBoundary[*];
+    metadata def <crossesTrustBoundary> CrossesTrustBoundaryMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = crossesTrustBoundaryLinks meta SysML::Usage;
     }
 
     connection def Validates :> MemoRelationship {
         // Validation targets include use cases and other behavioural elements,
         // so the target remains untyped across SysML metaclass families.
-        end validationTarget;
-        end validationCase : MemoVerificationCase;
-    }
-    connection def DependsOnSoup :> MemoRelationship {
-        end component : ArchitectureElement;
-        end soupItem : MemoPart;
+        end validationTarget :>> source;
+        end validationCase : MemoVerificationCase :>> target;
     }
-
-    // Performs unifies the former Performs / PerformsActivity / PerformsFunction
-    // synonyms. The performer (operational entity, actor, or system action) and
-    // the performed element (activity or function) are distinguished by the end
-    // instance types, so generic MemoPart ends keep this in core without a
-    // dependency on architecture-layer types.
-    connection def Performs :> MemoRelationship {
-        end performer : MemoPart;
-        end performed : MemoPart;
+    abstract connection validatesLinks : Validates[*];
+    metadata def <validates> ValidatesMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = validatesLinks meta SysML::Usage;
     }
 
     // Enables unifies the former EnablesWorkflow / EnablesActivity synonyms
     // (an enabling system/function enables a workflow/activity).
     connection def Enables :> MemoRelationship {
-        end enabling : MemoPart;
-        end enabled : MemoPart;
+        end enabling :>> source;
+        end enabled : MemoAction :>> target;
     }
-
-    connection def HostedBy :> MemoRelationship {
-        end processingNode : ArchitectureElement;
-        end hostAssembly : ArchitectureElement;
+    abstract connection enablesLinks : Enables[*];
+    metadata def <enables> EnablesMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = enablesLinks meta SysML::Usage;
     }
 
-    connection def HasFailureMode :> MemoRelationship {
-        end element : ArchitectureElement;
-        end failureMode : MemoPart;
-    }
-    // Causes unifies the former causal edges of the ISO 14971 / FMEA / FTA
-    // chains — CausesEffect, CausedBy, ContributesToHazard, LeadsToHazard,
-    // OriginatesFrom, UseErrorLeadsToHazard — keyed by causeKind. cause is the
-    // originating element, effect the consequence.
-    enum def CauseKind {
-        enum failureCausesEffect;
-        enum failureCausedBy;
-        enum contributesToHazard;
-        enum leadsToHazard;
-        enum originatesFrom;
-        enum useErrorLeadsToHazard;
-    }
-    connection def Causes :> MemoRelationship {
-        attribute causeKind : CauseKind;
-        end cause : MemoPart;
-        end effect : MemoPart;
+    connection def HostedBy :> MemoRelationship {
+        end processingNode : ArchitectureElement :>> source;
+        end hostAssembly : ArchitectureElement :>> target;
     }
-    connection def DetectedBy :> MemoRelationship {
-        end failureMode : MemoPart;
-        end detectionMethod : MemoPart;
+    abstract connection hostedByLinks : HostedBy[*];
+    metadata def <hostedBy> HostedByMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = hostedByLinks meta SysML::Usage;
     }
 
-    connection def InputToGate :> MemoRelationship {
-        end input : MemoPart;
-        end gate : MemoPart;
-    }
-    connection def ProducesEvent :> MemoRelationship {
-        end gate : MemoPart;
-        end eventElement : MemoPart;
-    }
-    connection def ContainsEvent :> MemoRelationship {
-        end cutSet : MemoPart;
-        end eventElement : MemoPart;
-    }
 
-    connection def Decides :> MemoRelationship {
-        end decision : MemoPart;
-        end affectedElement : MemoPart;
-    }
+
 
     // Composes is the single whole/part decomposition relation. It unifies the
     // former ComposesLogical / AssemblyComprises / Contains{Component,Element} /
@@ -234,33 +237,35 @@ package memo_core_relationships {
     // Collection membership is carried by the end instance.
     // types, so the ends are generic MemoPart.
     connection def Composes :> MemoRelationship {
-        end parent : MemoPart;
-        end child : MemoPart;
+        end parent :>> source;
+        end child :>> target;
     }
-
-    connection def IdentifiesHazard :> MemoRelationship {
-        end deviation : MemoPart;
-        end hazard : MemoPart;
-    }
-    connection def AnalyzedBy :> MemoRelationship {
-        end element : ArchitectureElement;
-        end analysisArtifact : AnalysisArtifact;
+    abstract connection composesLinks : Composes[*];
+    metadata def <composes> ComposesMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = composesLinks meta SysML::Usage;
     }
 
-    connection def Changes :> MemoRelationship {
-        end changeRequest : MemoPart;
-        end changedElement : MemoPart;
-    }
-    connection def TestedByUsability :> MemoRelationship {
-        end uiElementOrTask : MemoPart;
-        end usabilityTest : VerifiableElement;
+    connection def AnalyzedBy :> MemoRelationship {
+        end element : ArchitectureElement :>> source;
+        end analysisArtifact : AnalysisArtifact :>> target;
     }
-    connection def FeedsBackTo :> MemoRelationship {
-        end feedbackItem : MemoPart;
-        end designElement : MemoPart;
+    abstract connection analyzedByLinks : AnalyzedBy[*];
+    metadata def <analyzedBy> AnalyzedByMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = analyzedByLinks meta SysML::Usage;
     }
+
     connection def BindsToInterface :> MemoRelationship {
-        end portElement : InterfaceElement;
-        end boundInterface : InterfaceElement;
+        end portElement :>> source;
+        end boundInterface :>> target;
+    }
+    abstract connection bindsToInterfaceLinks : BindsToInterface[*];
+    metadata def <bindsToInterface> BindsToInterfaceMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = bindsToInterfaceLinks meta SysML::Usage;
     }
 }