@memoarchitect/ontology 0.6.5 → 0.8.22

package/src/assurance/safety_risk/postmarket_surveillance/memo_postmarket_surveillance.sysml

@@ -0,0 +1,27 @@
+package memo_assurance_safety_risk_postmarket_surveillance {
+    private import Metaobjects::SemanticMetadata;
+    private import ScalarValues::*;
+    private import memo_core_relationships::*;   // MemoRelationship
+
+    private import memo_core_common::*;
+
+    part def PostMarketSurveillance :> MemoPart {
+        attribute surveillanceKind : String;
+        attribute dataSource : String;
+        attribute reportingObligation : String;
+    }
+
+    // ── Relations owned by this package ─────────────────────────────
+    // Moved out of memo_core_relationships: their ends are typed against
+    // types declared here, and core must not depend on a domain package.
+    connection def FeedsBackTo :> MemoRelationship {
+        end feedbackItem : PostMarketSurveillance :>> source;
+        end designElement : MemoPart :>> target;
+    }
+    abstract connection feedsBackToLinks : FeedsBackTo[*];
+    metadata def <feedsBackTo> FeedsBackToMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = feedsBackToLinks meta SysML::Usage;
+    }
+}

package/src/assurance/verification_validation/clinical_evaluation/memo_clinical_evaluation.sysml

@@ -0,0 +1,11 @@
+package memo_assurance_verification_validation_clinical_evaluation {
+    private import ScalarValues::*;
+
+    private import memo_core_common::*;
+
+    part def ClinicalEvaluation :> MemoPart {
+        attribute evaluationStage : String;
+        attribute clinicalDataSource : String;
+        attribute conclusion : String;
+    }
+}

package/src/assurance/verification_validation/memo_assurance.sysml

@@ -1,4 +1,5 @@
 package memo_assurance_verification_validation {
+    private import Metaobjects::SemanticMetadata;
     private import ScalarValues::*;
 
     private import memo_core_common::*;
@@ -10,10 +11,17 @@ package memo_assurance_verification_validation {
     // Verification and validation cases are SysML v2 verification cases
     // (behaviours that check requirements), not verifiable structures — they
     // derive from the MemoVerificationCase foundation, not MemoPart.
+    // `status` is NOT redeclared here. It used to be re-declared as a String,
+    // which shadowed the `status : ElementStatusKind` every MEMO base carries
+    // and let a verification case hold an editorial status no other element
+    // could hold — against the "one status vocabulary in MEMO" rule stated in
+    // memo_requirements.sysml. The values it actually held ("planned") were an
+    // EXECUTION state, not an editorial one; execution state belongs in an
+    // attribute of its own (see RiskControlMeasure.verificationStatus), not in
+    // a second spelling of `status`.
     verification def VerificationCase :> MemoVerificationCase {
         attribute methodKind : VerificationMethodKind;
         attribute acceptanceCriteria : String;
-        attribute status : String;
     }
     verification def ValidationCase :> MemoVerificationCase {
         attribute validationMethod : ValidationMethodKind;
@@ -21,29 +29,17 @@ package memo_assurance_verification_validation {
         attribute acceptanceCriteria : String;
         attribute clinicalContext : String;
     }
-    part def TestArtifact specializes MemoEvidence {
-        attribute version : String;
-        attribute artifactKind : ArtifactKind;
-        attribute resultSummary : String;
-    }
-    part def Evidence specializes MemoEvidence {
-        attribute version : String;
-        attribute evidenceType : String;
-        attribute integrityStatus : String;
-    }
-
-    // A scenario executed to verify — selected path with purpose
-    // 'verification'.
-    part def VerificationScenario specializes MemoScenario {
-        attribute verificationEnvironment : String;
-        attribute stimulusSummary : String;
-    }
-
     // Operational validation confirms the user's goal is achieved in the
     // use environment (§5): ValidationCase validates a UseCase.
     // Safety-critical functions must trace to verification (rules/coverage).
     connection def ExecutesScenario :> MemoRelationship {
-        end verificationCase : VerificationCase;
-        end scenario : MemoScenario;
+        end verificationCase : VerificationCase :>> source;
+        end scenario : MemoScenario :>> target;
+    }
+    abstract connection executesScenarioLinks : ExecutesScenario[*];
+    metadata def <executesScenario> ExecutesScenarioMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = executesScenarioLinks meta SysML::Usage;
     }
 }

package/src/core/annotations/memo_annotations.sysml

@@ -0,0 +1,96 @@
+// Universal model annotations carried as model content rather than source-text
+// `doc` / `comment` annotations. Comments capture review conversation, notes
+// preserve useful context, and rationales explain why an engineering choice was
+// made. Each is independently traceable, queryable, and exportable.
+//
+// The distinction is deliberate and load-bearing: `description` is what an
+// element IS, a ModelComment is what someone SAID ABOUT IT. A design review
+// needs an author, a timestamp, a thread, and a resolution state, and none of
+// those survive inside a documentation string. Merging the two would put
+// unresolved review chatter into a generated DHF section, so they never merge.
+//
+// Annotations attach to every metaclass — parts, actions, requirements, views,
+// connections, and MEMO specializations — so CommentsOn, RationaleFor, and
+// NotesOn leave their subject ends untyped, following the MemoLink precedent in
+// memo_core_relationships.
+package memo_core_annotations {
+    private import Metaobjects::SemanticMetadata;
+    private import ScalarValues::*;
+
+    private import memo_core_common::*;
+    private import memo_core_enumerations::*;
+    private import memo_core_relationships::*;
+
+    abstract part def ModelAnnotation specializes MemoPart {
+        // `body` is the annotation content; `shortDescription` is the one-line
+        // form shown in badges, tables, and generated indexes.
+        attribute body : String;
+        attribute author : String;
+        // ISO 8601. Strings, not a date type: MEMO stays portable content and
+        // does not depend on a tool's date library.
+        attribute createdAt : String;
+        // Optional pinpoint inside the annotated element: an attribute name,
+        // requirement clause, diagram node, or other stable local reference.
+        attribute anchor : String;
+    }
+
+    part def ModelComment specializes ModelAnnotation {
+        attribute commentStatus : CommentStatusKind;
+        // Why the comment closed. Required in practice for `resolved` and
+        // `rejected` — a closed review point with no stated disposition is an
+        // audit gap.
+        attribute resolution : String;
+        attribute resolvedBy : String;
+        attribute resolvedAt : String;
+    }
+
+    part def ModelRationale specializes ModelAnnotation {
+        // Decision, trade-off, standard clause, or evidence that the rationale
+        // rests on. The body explains the reasoning in full.
+        attribute basis : String;
+    }
+
+    part def ModelNote specializes ModelAnnotation {
+        // A lightweight category for filtering notes without constraining their
+        // content (for example assumption, usage, implementation, or warning).
+        attribute noteKind : String;
+    }
+
+    // Replies form a thread through the ordinary Composes relation (parent
+    // comment → reply), so CR-ONT-001's acyclicity invariant already covers
+    // comment threads and no thread-specific relation is needed.
+    // The end is `remark`, not `comment`: `comment` is a reserved KerML
+    // keyword and cannot name a feature.
+    connection def CommentsOn :> MemoRelationship {
+        end remark : ModelComment :>> source;
+        end annotatedElement :>> target;
+    }
+    abstract connection commentsOnLinks : CommentsOn[*];
+    metadata def <commentsOn> CommentsOnMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = commentsOnLinks meta SysML::Usage;
+    }
+
+    connection def RationaleFor :> MemoRelationship {
+        end rationaleRecord : ModelRationale :>> source;
+        end justifiedElement :>> target;
+    }
+    abstract connection rationaleForLinks : RationaleFor[*];
+    metadata def <rationaleFor> RationaleForMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = rationaleForLinks meta SysML::Usage;
+    }
+
+    connection def NotesOn :> MemoRelationship {
+        end noteRecord : ModelNote :>> source;
+        end notedElement :>> target;
+    }
+    abstract connection notesOnLinks : NotesOn[*];
+    metadata def <notesOn> NotesOnMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = notesOnLinks meta SysML::Usage;
+    }
+}

package/src/core/common/memo_common.sysml

@@ -1,9 +1,32 @@
 // MEMO base hierarchy. Construct-specific foundations: one base per
-// SysML v2 metaclass family (part, action, port, interface, item, requirement,
-// connection), each carrying the shared MEMO semantics. Common inheritance
+// SysML v2 metaclass family (part, action, port, interface, item, use case,
+// requirement, constraint, verification, state, connection), each carrying
+// the shared MEMO semantics. Common inheritance
 // across metaclasses is not portable, so non-part bases re-declare the small
 // identification core and share classification through the metadata defs in
 // memo_core_dimensions.
+//
+// ─── The identification core ────────────────────────────────────────────
+// Every MEMO base below declares the SAME attributes, in the same order,
+// with no exceptions:
+//
+//     id, uuid, name, shortDescription, description,
+//     rationale, sourceReference, status
+//
+// They are re-declared per metaclass only because KerML will not let an
+// action, port, item, requirement, or connection inherit from a part def.
+// The duplication is a language constraint, not a design choice — so treat
+// the block as one unit: anything added or removed here is added or removed
+// in all of them. The drift this replaces was real (MemoPort carried no
+// sourceReference and no status; MemoRequirement and MemoNeed each invented
+// their own status attribute), and drift here shows up as an element whose
+// properties panel is missing fields its neighbours have.
+//
+// `uuid` is the stable technical identity: never displayed, never used as a
+// label, never reused. Authors normally leave it unset and let the compiler
+// derive it (memo-tools assigns a v5 UUID over file+kind+id); set it
+// explicitly on an element whose file or id must be free to change without
+// breaking external references to it, and the authored value wins.
 package memo_core_common {
     private import ScalarValues::*;
 
@@ -26,7 +49,16 @@ package memo_core_common {
     abstract part def MemoPart {
         // identity
         attribute id : String;
+        attribute uuid : String;
         attribute name : String;
+        // Two description registers on every MEMO element, because views have
+        // two densities. `shortDescription` is the one-line form a table cell,
+        // matrix header, chip, or diagram node can show whole; `description` is
+        // the full prose a properties panel or a generated document section
+        // renders. A view picks the register that fits — it never truncates
+        // the long one, because a silently clipped sentence in a DHF table is
+        // a defect, not a layout choice.
+        attribute shortDescription : String;
         attribute description : String;
         // traceability
         attribute rationale : String;
@@ -48,13 +80,36 @@ package memo_core_common {
     abstract part def VerifiableElement specializes MemoPart;
     abstract part def ArchitectureElement specializes MemoPart;
     part def InterfaceElement specializes MemoPart;
-    part def MemoEvidence specializes MemoPart;
+    enum def EvidenceKind { enum testArtifact; enum evidence; enum formativeEvaluation; enum usabilityValidation; enum securityClaim; }
+    part def MemoEvidence specializes MemoPart {
+        attribute evidenceKind : EvidenceKind;
+        attribute version : String;
+        attribute artifactKind : ArtifactKind[0..1];
+        attribute resultSummary : String;
+        attribute evidenceType : String;
+        attribute integrityStatus : String;
+        // Promoted from the retired `UsabilityValidation` and
+        // `FormativeEvaluation` specializations. The collapse in `02083c5`
+        // deleted both subclasses without carrying their fields up, so an
+        // IEC 62366-1 evaluation record lost what it actually reports.
+        // Promoted on the standard's terms, not on in-tree usage: MEMO is a
+        // library, so what its own examples happen to set says nothing about
+        // what an adopter's usability file needs.
+        attribute participantProfile : String;
+        attribute participantCount : Integer;
+        attribute acceptanceCriteria : String;
+        attribute evaluationMethod : String;
+        attribute findingsSummary : String;
+        attribute designChangesTriggered : String;
+    }
     abstract part def AnalysisArtifact specializes MemoPart;
 
+    // Document-bound elements add only what a document needs beyond the two
+    // description registers every MemoPart now carries: a title and its place
+    // in a document. The former `shortDescription`/`longDescription` pair is
+    // gone — short is inherited, and `description` IS the long form.
     part def DocumentedElement specializes MemoPart {
         attribute title : String;
-        attribute shortDescription : String;
-        attribute longDescription : String;
         attribute documentUsage : String[*];
         attribute sectionIdentifier : String;
     }
@@ -65,7 +120,9 @@ package memo_core_common {
     // and interaction steps specialize MemoAction.
     action def MemoAction {
         attribute id : String;
+        attribute uuid : String;
         attribute name : String;
+        attribute shortDescription : String;
         attribute description : String;
         attribute rationale : String;
         attribute sourceReference : String;
@@ -75,9 +132,13 @@ package memo_core_common {
     // Boundary feature foundation for typed ports.
     port def MemoPort {
         attribute id : String;
+        attribute uuid : String;
         attribute name : String;
+        attribute shortDescription : String;
         attribute description : String;
-        attribute direction : DirectionKind;
+        attribute rationale : String;
+        attribute sourceReference : String;
+        attribute status : ElementStatusKind;
     }
 
     // Interaction-contract foundation for interface definitions between ports.
@@ -85,20 +146,33 @@ package memo_core_common {
         end source;
         end target;
         attribute id : String;
+        attribute uuid : String;
         attribute name : String;
+        attribute shortDescription : String;
         attribute description : String;
         attribute rationale : String;
         attribute sourceReference : String;
     }
 
-    // Exchange-content foundation: everything that flows — information,
-    // command, material, energy — is an item, not a part.
-    item def MemoExchangeItem {
+    // Single item foundation. Standards, hazards, stored software data, and
+    // message payloads are all item-native concepts. Whether an item is
+    // exchanged is expressed by its use in a port or flow, not by a second
+    // ontology root.
+    abstract item def MemoItem {
         attribute id : String;
+        attribute uuid : String;
         attribute name : String;
+        attribute shortDescription : String;
         attribute description : String;
         attribute rationale : String;
         attribute sourceReference : String;
+        attribute status : ElementStatusKind;
+        // What the item CARRIES, as distinct from what it is called. Removed
+        // by `595bfac` while modelling native wrappers; nothing replaced them,
+        // and every exchange item in the examples went on setting them. A
+        // measured value without its unit, its range, or its terminology code
+        // is not a regulated data item — an IVD result is "5.5 mg/dL, LOINC
+        // 2345-7", not "5.5".
         attribute semantics : String;
         attribute unit : String;
         attribute minValue : String;
@@ -108,23 +182,58 @@ package memo_core_common {
         attribute codes : TerminologyCode[0..*];
     }
 
+    // Use-case foundation. The domain UseCase adds its goal and actor
+    // references; identity is carried here so use cases do not maintain a
+    // partial hand-written copy of the MEMO identification core.
+    abstract use case def MemoUseCase {
+        attribute id : String;
+        attribute uuid : String;
+        attribute name : String;
+        attribute shortDescription : String;
+        attribute description : String;
+        attribute rationale : String;
+        attribute sourceReference : String;
+        attribute status : ElementStatusKind;
+    }
+
+    // General constraint foundation. Executable consistency rules and
+    // reusable quantitative constraints are both native constraint defs.
+    abstract constraint def MemoConstraint {
+        attribute id : String;
+        attribute uuid : String;
+        attribute name : String;
+        attribute shortDescription : String;
+        attribute description : String;
+        attribute rationale : String;
+        attribute sourceReference : String;
+        attribute status : ElementStatusKind;
+    }
+
     // Requirement-family foundations. MemoNeed captures a problem-space
     // expectation in stakeholder language; MemoRequirement a testable
     // solution-space obligation.
-    requirement def MemoNeed {
-        attribute needId : String;
+    // Shared base of the requirement family. It exists so a relation end can
+    // say "a need or a requirement" with one type name — before it, every end
+    // that had to accept both was left untyped.
+    abstract requirement def MemoRequirementElement {
+        attribute id : String;
+        attribute uuid : String;
+        attribute name : String;
+        attribute shortDescription : String;
+        attribute description : String;
+        attribute rationale : String;
+        attribute sourceReference : String;
+        attribute status : ElementStatusKind;
         attribute statement : String;
-        attribute needRationale : String;
+    }
+
+    requirement def MemoNeed :> MemoRequirementElement {
         attribute needSource : String;
         attribute priority : String;
-        attribute needStatus : ElementStatusKind;
     }
 
-    requirement def MemoRequirement {
-        attribute requirementId : String;
-        attribute statement : String;
+    requirement def MemoRequirement :> MemoRequirementElement {
         attribute acceptanceCriteria : String;
-        attribute requirementStatus : ElementStatusKind;
     }
 
     // Verification-case foundation. A SysML v2 verification case is a behaviour
@@ -133,10 +242,13 @@ package memo_core_common {
     // identification core rather than inheriting it.
     verification def MemoVerificationCase {
         attribute id : String;
+        attribute uuid : String;
         attribute name : String;
+        attribute shortDescription : String;
         attribute description : String;
         attribute rationale : String;
         attribute sourceReference : String;
+        attribute status : ElementStatusKind;
     }
 
     // State foundation. SysML v2 states (state machines and their mode states)
@@ -144,12 +256,22 @@ package memo_core_common {
     // re-declare the identification core instead of specializing MemoPart
     // Transitions stay part-based to keep their traceable safety
     // attributes (id, sourceReference, priority, sameStepCritical).
-    abstract state def MemoState {
+    enum def StateKind { enum mode; enum logical; }
+
+    state def MemoState {
+        attribute stateKind : StateKind;
         attribute id : String;
+        attribute uuid : String;
         attribute name : String;
+        attribute shortDescription : String;
         attribute description : String;
         attribute rationale : String;
         attribute sourceReference : String;
+        attribute status : ElementStatusKind;
+        attribute modeKind : String;
+        attribute entryCondition : String;
+        attribute exitCondition : String;
+        attribute modePurpose : String;
     }
 
     part def Citation specializes MemoPart {

package/src/core/consistency_rules/consistency_rules.sysml

@@ -6,6 +6,13 @@ package memo_core_consistency_rules {
     private import memo_core_common::*;
     private import memo_core_enumerations::*;
 
+    // Common supertype of every executable MEMO rule. It carries no members of
+    // its own: a rule's metadata is declared on the rule, and a shared member
+    // here would be shadowed by every rule that sets it. Its job is to give
+    // RulePolicy a type to reference, so a policy names a rule the way SysML
+    // names anything else rather than through a parallel string-ID namespace.
+    abstract constraint def MemoConsistencyRule :> MemoConstraint;
+
     part def ConsistencyRule specializes MemoPart {
         attribute appliesTo : String;
         attribute predicate : RulePredicateKind;

package/src/core/dimensions/dimensions.sysml

@@ -10,9 +10,13 @@ package memo_core_dimensions {
     private import ScalarValues::*;
 
     // Realization stages of one element identity across the product
-    // lifecycle (specification through retirement). Orthogonal to the axis:
+    // lifecycle (proposal through retirement). Orthogonal to the axis:
     // a single identity progresses through stages without changing its owner.
     enum def RealizationStageKind {
+        // Put forward but not yet specified — a candidate under consideration,
+        // so a design alternative can be modelled and traced without implying
+        // it has been accepted into the specification.
+        enum proposed;
         enum specified;
         enum designed;
         enum built;
@@ -35,7 +39,19 @@ package memo_core_dimensions {
 
     // Editorial status of the model element itself (distinct from the
     // lifecycle of the thing the element describes).
+    // This is the ONE status vocabulary in MEMO: every element carries
+    // `status : ElementStatusKind`, whatever its metaclass. The former
+    // per-family variants (RequirementStatusKind, LinkStatusKind,
+    // MemoNeed::needStatus) are gone — three overlapping status dropdowns on
+    // one element was cognitive load, not precision.
+    //
+    // The V&V states the requirement variant carried (implemented, verified,
+    // validated) are deliberately NOT here: they are facts about links, not
+    // editorial states. An element is implemented when a Realizes link exists,
+    // verified when VerifiedBy does, validated when Validates does. Duplicating
+    // them as an attribute lets the attribute disagree with the graph.
     enum def ElementStatusKind {
+        enum proposed;
         enum draft;
         enum inReview;
         enum approved;