@memoarchitect/ontology 0.7.0 → 0.8.22

package/src/artifacts/templates/dhf/system/sad.md

@@ -0,0 +1,173 @@
+---
+id: sad-system
+title: System Architecture Description
+standard: ISO/IEC/IEEE 42010:2022
+clauses: ["5", "6", "IEC 62304:2006+AMD1:2015 §5.3", "IEC 60601-1:2005+AMD1:2012+AMD2:2020 §4.2"]
+required_for: ["CE", "FDA_510k", "MDR"]
+---
+
+{{include:shared/snippets/document-control-header.md}}
+
+{{toc}}
+
+---
+
+## 1. Purpose
+
+This System Architecture Description (SAD) defines the overall cyber-physical architecture of **{{project.product}}** per ISO/IEC/IEEE 42010:2022 and satisfies architecture requirements across IEC 62304 §5.3 (software) and IEC 60601-1 (hardware).
+
+---
+
+## 2. System Overview
+
+A high-level view of the **{{project.product}}** system, drawn live from the architecture model:
+
+```memo-query
+kind: [SoftwareSystem, HardwareAssembly, PhysicalAssembly]
+display: table
+columns: name, layer, doc
+sort: name
+empty: "No system-level elements defined."
+```
+
+**Total elements:**
+
+```memo-query
+kind: [SoftwareSystem, SoftwareComponent, SoftwareModule, HardwareAssembly, PhysicalAssembly, PhysicalSubassembly, HardwareComponent, PhysicalComponent]
+display: count
+label: Total system elements
+```
+
+---
+
+## 3. SEI Viewpoints
+
+This architecture is described using the Software Engineering Institute (SEI) Views and Beyond approach, adapted for cyber-physical systems.
+
+### 3.1 Module View (Implementation Structure)
+
+The static structure of the system's implementation units. Hardware and software are sibling directories in the `implementation` layer, so the two subsections are distinguished by **kind**, not by a layer filter — there is no hardware layer and no software layer.
+
+#### 3.1.1 Software Implementation Units (IEC 62304 §5.3.1)
+
+```memo-query
+kind: [SoftwareSystem, SoftwareComponent, SoftwareModule]
+display: table
+columns: name, layer, doc
+sort: name
+empty: "No software implementation units defined."
+```
+
+#### 3.1.2 Hardware Implementation Units
+
+```memo-query
+kind: [PhysicalAssembly, HardwareAssembly, PhysicalSubassembly, PhysicalComponent, HardwareComponent]
+display: table
+columns: name, layer, doc
+sort: name
+empty: "No hardware implementation units defined."
+```
+
+### 3.2 Component-and-Connector (C&C) View (Runtime Execution)
+
+Runtime behaviour: the components executing in the system and the connectors through which they interact.
+
+#### 3.2.1 Runtime Environments
+
+```memo-query
+kind: [RuntimeEnvironment, DeploymentUnit]
+display: table
+columns: name, layer, doc
+sort: name
+empty: "No runtime environments or deployment units defined."
+```
+
+#### 3.2.2 Interfaces and Data Flows
+
+Cyber-physical interactions and data flows between components:
+
+```memo-query
+kind: [Interface, LogicalInterface, ComponentExchange, InterfaceElement, MemoPort, DataPort, SensorPort, CommandPort, SoftwarePort, PhysicalPort, LogicalPort]
+display: table
+columns: name, kind, layer, doc
+sort: name
+empty: "No interfaces, ports or component exchanges defined."
+```
+
+### 3.3 Allocation View (Environment Mapping)
+
+Software elements mapped to their execution environments.
+
+#### 3.3.1 Deployment Units
+
+```memo-query
+kind: DeploymentUnit
+traverse: outgoing deploysTo
+display: table
+columns: name, kind, layer, doc
+sort: name
+empty: "No deployments defined. Add DeploysTo links from DeploymentUnit to the processing node."
+```
+
+---
+
+## 4. Architecture Decisions & Segregation
+
+Significant architecture decisions, alternatives considered, and rationale — including decisions driven by risk control measures (ISO 14971) or cybersecurity considerations.
+
+### 4.1 Segregation of Safety Classes (IEC 62304 §5.3.5)
+
+_[TODO: Describe how safety-critical items are segregated from non-safety-critical items, and the rationale for the integrity of each boundary]_
+
+---
+
+## 5. SOUP Components
+
+Software of Unknown Provenance used by **{{project.product}}**, derived by traversing `dependsOnSoup` from the software items. MEMO has no `SOUPComponent` kind: SOUP is a *relationship* a project's own software item has to a third-party item, which is why it is traversed rather than typed.
+
+```memo-query
+kind: [SoftwareSystem, SoftwareComponent, SoftwareModule]
+traverse: outgoing dependsOnSoup
+display: table
+columns: name, kind, layer, doc
+sort: name
+empty: "No SOUP identified. Add DependsOnSoup links from software items to the SOUP they depend on."
+```
+
+---
+
+## 6. Standards Compliance and Traceability
+
+Maps architectural elements to the regulatory clauses they claim, for compliance audits. Both tables are relationship tables — rows are `ConformsTo` links, with columns drawn from both endpoints. Each is scoped to one standard by the clause's declaring package, since the standards library is one package per standard; a clause *number* would not do it, because "5" is a clause of seven of the standards MEMO ships.
+
+### 6.1 Compliance with IEC 62304
+
+```memo-query
+select: relationships
+kind: conformsTo
+where: target.package == "memo_artifacts_standards_iec_62304"
+display: table
+columns: source, source.kind, target.clauseNumber, target.title
+sort: target.clauseNumber
+empty: "No IEC 62304 compliance traces defined."
+```
+
+### 6.2 Compliance with IEC 60601-1
+
+```memo-query
+select: relationships
+kind: conformsTo
+where: target.package == "memo_artifacts_standards_iec_60601_1"
+display: table
+columns: source, source.kind, target.clauseNumber, target.title
+sort: target.clauseNumber
+empty: "No IEC 60601-1 compliance traces defined."
+```
+
+---
+
+{{include:shared/snippets/revision-history-table.md}}
+
+{{include:shared/snippets/approval-block.md}}
+
+{{include:shared/snippets/references-section.md}}

package/src/artifacts/templates/dhf/system/standards-checklist.md

@@ -0,0 +1,87 @@
+---
+id: standards-checklist
+title: Standards Conformance Checklist
+standard: ISO 13485:2016
+clauses: ["4.2", "7.3.10"]
+required_for: ["CE", "FDA_510k", "FDA_PMA", "MDR"]
+---
+
+{{include:shared/snippets/document-control-header.md}}
+
+{{toc}}
+
+---
+
+## 1. Purpose
+
+This checklist is the clause-by-clause conformance record for **{{project.product}}**. It lists every clause the project's declared regulatory regimes require, states whether the project claims it, and — where it does — names the element that carries the claim and the evidence behind it.
+
+It replaces a hand-maintained conformance matrix. The difference that matters is that this one **cannot silently go empty**: it is generated from the clause library, so a clause nobody has claimed appears as a row marked *Gap*, not as an absent line.
+
+**How to read this document.**
+
+| Status | Meaning |
+| --- | --- |
+| ✅ Evidenced | Something claims the clause, and that claim reaches verification, a risk control, or an approved controlled document. |
+| 🟡 Claimed | Something claims the clause, but no evidence is linked to it yet. |
+| ❌ Gap | Nothing in the project claims the clause. |
+
+A **Gap** is not a defect in the model. Coverage is profile-dependent — that is why it is a report and not a consistency rule, and why `memo_rules_coverage` is deliberately empty. A gap says the project has not claimed that clause *yet*, which is the normal state of a project in flight.
+
+**Scope.** The clauses below are those of the standards the project's `regulatoryRegime` declaration pulls in. Method and reference standards that no regime mandates — the FMEA method, the architecture-description standard — are listed separately in §4; their clauses are claimable but not required, so they have no gap count.
+
+`memo standards check` prints the same numbers at the command line, from the same computation.
+
+---
+
+## 2. Coverage Summary
+
+```memo-standards
+display: summary
+empty: "No standards are in scope. Declare `regulatoryRegime` on the project's ProjectMethodBinding."
+```
+
+---
+
+## 3. Clause-by-Clause Record
+
+Every required clause, including the ones nothing claims. The unclaimed rows are the point of the document.
+
+```memo-standards
+display: checklist
+status: all
+empty: "No standards are in scope for the declared regimes."
+```
+
+---
+
+## 4. Standards Not Required by the Declared Regimes
+
+Method and reference standards, and packs outside this project's submission targets. A clause claimed here is real traceability; it is simply not something a regime obliges this project to claim, so nothing here is counted as a gap.
+
+```memo-standards
+display: checklist
+scope: unrequired
+status: claimed
+empty: "No clauses are claimed outside the required standards."
+```
+
+---
+
+## 5. Open Gaps
+
+The working list. Each row is a clause a declared regime requires and nothing in the project claims.
+
+```memo-standards
+display: checklist
+status: gaps
+empty: "No open gaps — every required clause is claimed."
+```
+
+---
+
+{{include:shared/snippets/revision-history-table.md}}
+
+{{include:shared/snippets/approval-block.md}}
+
+{{include:shared/snippets/references-section.md}}

package/src/artifacts/templates/dhf/system/standards-traceability.md

@@ -0,0 +1,125 @@
+---
+id: standards-traceability
+title: Standards Traceability Matrix
+standard: ISO 13485:2016
+clauses: ["7.3.9", "IEC 62304:2006+AMD1:2015 §5.1", "IEC 60601-1:2005+AMD1:2012+AMD2:2020 §4.2", "ISO 14971:2019 §4.4"]
+required_for: ["CE", "FDA_510k", "MDR"]
+---
+
+{{include:shared/snippets/document-control-header.md}}
+
+{{toc}}
+
+---
+
+## 1. Purpose
+
+This Standards Traceability Matrix cross-references the requirements and architectural elements of the **{{project.product}}** cyber-physical system against the clauses of applicable regulatory standards. It is the automated compliance checklist an auditor reads.
+
+**How to read this document.** Every table below is *relationship-shaped*: a row is a `ConformsTo` link, with the clause on one end and the conforming element on the other. `select: relationships` makes the link the row, so both ends are addressable as columns.
+
+Each section is scoped to one standard by the clause's declaring package — the standards library is one package per standard, which makes `target.package` an exact per-standard selector. A clause *number* is not one: "5" is a clause of seven of the standards MEMO ships, so a matrix filtered on clause number would silently mix IEC 62304 §5 with ISO 14971 §5.
+
+A clause with no `ConformsTo` link is a gap. Enumerating the gaps is `memo standards check`, not this document — this document shows what the project *does* claim.
+
+---
+
+## 2. IEC 62304 Software Lifecycle Processes
+
+Maps IEC 62304 clauses to the system elements that satisfy them.
+
+```memo-query
+select: relationships
+kind: conformsTo
+where: target.package == "memo_artifacts_standards_iec_62304"
+display: table
+columns: target.clauseNumber, target.title, source, source.kind
+sort: target.clauseNumber
+empty: "No IEC 62304 compliance traces defined."
+```
+
+### 2.1 Document Traceability (IEC 62304)
+
+```memo-query
+select: relationships
+kind: tracesToDocument
+where: source.package == "memo_artifacts_standards_iec_62304"
+display: table
+columns: source.clauseNumber, source.title, target, sectionReference
+sort: source.clauseNumber
+empty: "No IEC 62304 document traces defined."
+```
+
+---
+
+## 3. IEC 60601-1 Medical Electrical Equipment Safety
+
+Maps IEC 60601-1 clauses to the hardware elements and requirements that satisfy them.
+
+```memo-query
+select: relationships
+kind: conformsTo
+where: target.package == "memo_artifacts_standards_iec_60601_1"
+display: table
+columns: target.clauseNumber, target.title, source, source.kind
+sort: target.clauseNumber
+empty: "No IEC 60601-1 compliance traces defined."
+```
+
+### 3.1 Document Traceability (IEC 60601-1)
+
+```memo-query
+select: relationships
+kind: tracesToDocument
+where: source.package == "memo_artifacts_standards_iec_60601_1"
+display: table
+columns: source.clauseNumber, source.title, target, sectionReference
+sort: source.clauseNumber
+empty: "No IEC 60601-1 document traces defined."
+```
+
+---
+
+## 4. ISO 14971 Risk Management
+
+Maps ISO 14971 risk management clauses to their conforming elements — the risk management plan, the hazard analysis, the risk controls.
+
+```memo-query
+select: relationships
+kind: conformsTo
+where: target.package == "memo_artifacts_standards_iso_14971"
+display: table
+columns: target.clauseNumber, target.title, source, source.kind
+sort: target.clauseNumber
+empty: "No ISO 14971 compliance traces defined."
+```
+
+---
+
+## 5. Standards and Clauses in Scope
+
+The clause library itself, as element queries — the standards this project's documents cite, and the clauses available to claim.
+
+```memo-query
+kind: RegulatoryStandard
+display: table
+columns: name, designation, edition, issuer
+sort: designation
+empty: "No standards declared. Add RegulatoryStandard instances for the standards this project claims."
+```
+
+```memo-query
+kind: StandardClause
+display: table
+columns: clauseNumber, title, normativeStrength, doc
+sort: clauseNumber
+empty: "No standard clauses declared. Add StandardClause instances for the clauses this project claims."
+```
+
+---
+
+{{include:shared/snippets/revision-history-table.md}}
+
+{{include:shared/snippets/approval-block.md}}
+
+{{include:shared/snippets/references-section.md}}

package/src/artifacts/templates/dhf/system/syrs.md

@@ -0,0 +1,128 @@
+---
+id: syrs
+title: System Requirements Specification
+standard: IEC 60601-1:2005+AMD1:2012+AMD2:2020
+clauses: ["4.2", "IEC 62304:2006+AMD1:2015 §5.2", "ISO 14971:2019 §5"]
+required_for: ["CE", "FDA_510k", "MDR"]
+---
+
+{{include:shared/snippets/document-control-header.md}}
+
+{{toc}}
+
+---
+
+## 1. Purpose
+
+This System Requirements Specification (SyRS) defines the top-level requirements for the **{{project.product}}** cyber-physical system, serving as the bridge between user needs and the lower-level hardware (IEC 60601-1) and software (IEC 62304) requirements.
+
+One standard is named above because a document claims one; the others it feeds are carried in `clauses:`.
+
+---
+
+## 2. System Requirements Summary
+
+Summary metrics for the system requirements captured in the model:
+
+```memo-query
+kind: Requirement
+where: requirementKind == "RequirementKind::system"
+display: count
+label: Total system requirements
+```
+
+---
+
+## 3. Functional Requirements
+
+Binding system requirements — those carrying a `shall` obligation:
+
+```memo-query
+kind: Requirement
+where: obligation == "ObligationKind::shall"
+display: table
+columns: name, requirementKind, doc
+sort: name
+empty: "No requirements carry a `shall` obligation. Set `obligation` on Requirement elements."
+```
+
+### All System Requirements
+
+```memo-query
+kind: Requirement
+where: requirementKind == "RequirementKind::system"
+display: table
+columns: name, requirementKind, safetyClass, doc
+sort: name
+empty: "No system requirements defined. Add Requirement elements with requirementKind = system."
+```
+
+---
+
+## 4. Requirements Allocation
+
+How system requirements are allocated down to hardware and software.
+
+### 4.1 Elements System Requirements Are Satisfied By
+
+```memo-query
+kind: Requirement
+where: requirementKind == "RequirementKind::system"
+traverse: outgoing satisfiedBy
+display: table
+columns: name, kind, layer, doc
+sort: name
+empty: "No system requirements are linked to a satisfying element. Add SatisfiedBy links."
+```
+
+### 4.2 Function Allocation
+
+The allocation table proper — which element allocates to which — is a relationship table, not an element table. It is grouped by the kind of the receiving element, which is where the hardware/software split actually lives: `AllocatedTo` joins two architecture elements and carries no layer of its own, so a single comparison cannot ask for "the hardware ones" without naming one hardware kind and dropping the rest.
+
+```memo-query
+select: relationships
+kind: allocatedTo
+display: grouped
+group_by: target.kind
+columns: source, source.kind, target, target.layer
+sort: source
+empty: "No allocations defined. Add AllocatedTo links."
+```
+
+---
+
+## 5. Non-Functional Requirements
+
+### 5.1 System Performance Requirements
+
+_[TODO: Define system performance requirements (e.g. overall throughput, latency, physical capacities)]_
+
+### 5.2 System Safety Requirements
+
+Hazards from the ISO 14971 analysis that system-level risk controls must address:
+
+```memo-query
+kind: [Hazard, HazardousSituation]
+display: table
+columns: name, layer, doc
+sort: name
+empty: "No hazards defined in the risk model."
+```
+
+The risk controls answering them:
+
+```memo-query
+kind: RiskControlMeasure
+display: table
+columns: name, layer, doc
+sort: name
+empty: "No risk controls defined."
+```
+
+---
+
+{{include:shared/snippets/revision-history-table.md}}
+
+{{include:shared/snippets/approval-block.md}}
+
+{{include:shared/snippets/references-section.md}}

package/src/assurance/cybersecurity/memo_cybersecurity.sysml

@@ -1,5 +1,7 @@
 package memo_assurance_cybersecurity {
+    private import Metaobjects::SemanticMetadata;
     private import ScalarValues::*;
+    private import memo_core_relationships::*;   // MemoRelationship
 
     private import memo_core_common::*;
     private import memo_core_enumerations::*;
@@ -27,7 +29,7 @@ package memo_assurance_cybersecurity {
         attribute authenticationExpected : Boolean;
     }
 
-    item def Threat specializes RiskDriver {
+    part def Threat specializes RiskDriver {
         attribute threatCategory : ThreatCategoryKind;
         attribute attackVector : String;
         attribute threatSource : String;
@@ -37,7 +39,7 @@ package memo_assurance_cybersecurity {
         attribute strideCategory : ThreatCategoryKind;
     }
 
-    item def Vulnerability specializes MemoPart {
+    item def Vulnerability specializes RiskItem {
         attribute weakness : String;
         attribute exploitability : String;
         attribute discoveryMethod : String;
@@ -46,18 +48,6 @@ package memo_assurance_cybersecurity {
         attribute remediable : Boolean;
     }
 
-    // A scenario specialization: an attack path through the
-    // system, classified by the shared scenario dimensions with purpose
-    // `cybersecurity`.
-    action def ThreatScenario specializes MemoScenario {
-        attribute actorDescription : String;
-        attribute assumptionSummary : String;
-        attribute guaranteeSummary : String;
-        attribute securityObjective : String;
-        attribute abuseCaseReference : String;
-        attribute defaultCategory : ThreatCategoryKind;
-    }
-
     item def CyberHazard specializes Hazard {
         attribute securityImpact : String;
         attribute safetyImpact : String;
@@ -66,7 +56,7 @@ package memo_assurance_cybersecurity {
         attribute linkedSafetyHazardId : String;
     }
 
-    item def CyberRisk specializes Risk {
+    part def CyberRisk specializes Risk {
         attribute exploitabilityEstimate : String;
         attribute attackComplexity : String;
         attribute detectability : DetectionKind;
@@ -88,15 +78,44 @@ package memo_assurance_cybersecurity {
         attribute defaultConcern : ConcernKind;
     }
 
-    item def TrustBoundary specializes InterfaceElement {
+    part def TrustBoundary specializes InterfaceElement {
         attribute boundaryType : String;
         attribute crossingConstraint : String;
         attribute trustAssumption : String;
     }
 
-    part def SecurityClaim specializes MemoEvidence {
-        attribute claimText : String;
-        attribute claimScope : String;
-        attribute supportedByEvidence : 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 Exploits :> MemoRelationship {
+        end realizedThreat : RequirementDriver :>> source;
+        end enablingVulnerability : Vulnerability :>> target;
+    }
+    abstract connection exploitsLinks : Exploits[*];
+    metadata def <exploits> ExploitsMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = exploitsLinks meta SysML::Usage;
+    }
+    connection def RealizedByScenario :> MemoRelationship {
+        end realizedThreat : RequirementDriver :>> source;
+        end scenario : MemoScenario :>> target;
+    }
+    abstract connection realizedByScenarioLinks : RealizedByScenario[*];
+    metadata def <realizedByScenario> RealizedByScenarioMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = realizedByScenarioLinks meta SysML::Usage;
+    }
+    connection def ImpactsSafety :> MemoRelationship {
+        attribute tracePurpose : String;
+        end cyberElement : MemoPart :>> source;
+        end safetyElement : RiskItem :>> target;
+    }
+    abstract connection impactsSafetyLinks : ImpactsSafety[*];
+    metadata def <impactsSafety> ImpactsSafetyMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = impactsSafetyLinks meta SysML::Usage;
     }
 }

package/src/assurance/human_factors/memo_human_factors.sysml

@@ -4,6 +4,7 @@
 // engineering chain: user → task → use error → hazard → risk control →
 // usability validation.
 package memo_assurance_human_factors {
+    private import Metaobjects::SemanticMetadata;
     private import ScalarValues::*;
 
     private import memo_core_common::*;
@@ -19,32 +20,38 @@ package memo_assurance_human_factors {
         attribute rootCauseType : String;
     }
 
-    // A use scenario whose performance could lead to a hazardous situation
-    // (IEC 62366-1 3.9); selected for summative evaluation.
-    action def HazardRelatedUseScenario specializes MemoScenario {
-        attribute hazardReference : String;
-        attribute selectionRationale : String;
+    connection def CommitsUseError :> MemoRelationship {
+        end task : UserTask :>> source;
+        end useError : UseError :>> target;
     }
-
-    part def FormativeEvaluation specializes MemoEvidence {
-        attribute evaluationMethod : String;
-        attribute findingsSummary : String;
-        attribute designChangesTriggered : String;
+    abstract connection commitsUseErrorLinks : CommitsUseError[*];
+    metadata def <commitsUseError> CommitsUseErrorMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = commitsUseErrorLinks meta SysML::Usage;
     }
-
-    part def UsabilityValidation specializes MemoEvidence {
-        attribute participantProfile : String;
-        attribute participantCount : Integer;
-        attribute acceptanceCriteria : String;
-        attribute resultSummary : String;
+    connection def EvaluatesTask :> MemoRelationship {
+        end evaluation : MemoEvidence :>> source;
+        end task : UserTask :>> target;
+    }
+    abstract connection evaluatesTaskLinks : EvaluatesTask[*];
+    metadata def <evaluatesTask> EvaluatesTaskMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = evaluatesTaskLinks meta SysML::Usage;
     }
 
-    connection def CommitsUseError :> MemoRelationship {
-        end task : UserTask;
-        end useError : UseError;
+    // ── 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 TestedByUsability :> MemoRelationship {
+        end uiElementOrTask : MemoPart :>> source;
+        end usabilityTest : MemoEvidence :>> target;
     }
-    connection def EvaluatesTask :> MemoRelationship {
-        end evaluation : MemoEvidence;
-        end task : UserTask;
+    abstract connection testedByUsabilityLinks : TestedByUsability[*];
+    metadata def <testedByUsability> TestedByUsabilityMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = testedByUsabilityLinks meta SysML::Usage;
     }
 }