[validation] add requirements and spec

bazel/rules/rules_score/docs/index.rst

@@ -39,6 +39,7 @@ safety analysis to the top-level SEooC assembly.
 
    tool_reference/specs/bazel_component
    tool_reference/specs/component_sequence
+   tool_reference/specs/class_design_implementation
 
 .. toctree::
    :maxdepth: 2

bazel/rules/rules_score/docs/requirements/use_cases.trlc

@@ -163,4 +163,14 @@ section "Use Cases" {
         affected_tools = [Tools.Verifier, Tools.PlantumlParser, Tools.Bazel]
     }
 
+    ToolQualification.UseCase Validate_Unit_Specification_Documents {
+        description = '''
+            As a software developer I want the build to verify that unit design
+            class and sequence diagrams are consistent with the corresponding
+            implementation artefacts so that unit-level design drift is
+            detected automatically during the build.
+        '''
+        affected_tools = [Tools.Verifier, Tools.PlantumlParser, Tools.LibClang, Tools.Bazel]
+    }
+
 }

validation/core/BUILD

@@ -23,6 +23,7 @@ filegroup(
     name = "specifications",
     srcs = [
         "docs/specifications/bazel_component.md",
+        "docs/specifications/class_design_implementation.md",
         "docs/specifications/component_sequence.md",
     ],
     visibility = ["//visibility:public"],

validation/core/docs/requirements/tool_requirements.trlc

@@ -119,6 +119,90 @@ section "Tool Requirements" {
 
         }
 
+        section "Class Design Implementation Validator" {
+
+            ToolQualification.ToolRequirement ClassDesignImplementationEntityConsistency {
+                description = '''The validator shall report an error when an
+                entity modeled in the unit design class diagram has no
+                corresponding entity in the implementation class diagram, or
+                when the matching implementation entity differs in entity
+                type. Consistency of type aliases, variables, methods, enum
+                literals, relationships, and template parameters is specified
+                by the dedicated requirements below.'''
+                derived_from = [UseCases.Validate_Unit_Specification_Documents]
+                satisfied_by = Verifier
+            }
+
+            ToolQualification.ToolRequirement ClassDesignImplementationTemplateParameterConsistency {
+                description = '''The validator shall report an error when
+                template parameters modeled on a unit design entity or method
+                differ from the template parameters on the matching
+                implementation entity or method.'''
+                derived_from = [UseCases.Validate_Unit_Specification_Documents]
+                satisfied_by = Verifier
+            }
+
+            ToolQualification.ToolRequirement ClassDesignImplementationTypeAliasConsistency {
+                description = '''The validator shall report an error when a
+                type alias modeled in a unit design entity is missing from the
+                matching implementation entity, or when the matching
+                implementation type alias differs in original type.'''
+                derived_from = [UseCases.Validate_Unit_Specification_Documents]
+                satisfied_by = Verifier
+            }
+
+            ToolQualification.ToolRequirement ClassDesignImplementationVariableConsistency {
+                description = '''The validator shall report an error when a
+                variable modeled in a unit design entity is missing from the
+                matching implementation entity, or when the matching
+                implementation variable differs in data type, visibility, or
+                static flag.'''
+                derived_from = [UseCases.Validate_Unit_Specification_Documents]
+                satisfied_by = Verifier
+            }
+
+            ToolQualification.ToolRequirement ClassDesignImplementationMethodConsistency {
+                description = '''The validator shall report an error when a
+                method modeled in a unit design entity is missing from the
+                matching implementation entity, or when the matching
+                implementation method differs in return type, visibility,
+                parameters, or method modifiers (`static`, `virtual`,
+                `abstract`, `override`, constructor, destructor, or
+                `noexcept`).'''
+                derived_from = [UseCases.Validate_Unit_Specification_Documents]
+                satisfied_by = Verifier
+            }
+
+            ToolQualification.ToolRequirement ClassDesignImplementationEnumLiteralConsistency {
+                description = '''The validator shall report an error when an
+                enum literal modeled in a unit design enum is missing from the
+                matching implementation enum, or when the matching
+                implementation enum literal data differs from the unit design.'''
+                derived_from = [UseCases.Validate_Unit_Specification_Documents]
+                satisfied_by = Verifier
+            }
+
+            ToolQualification.ToolRequirement ClassDesignImplementationRelationshipConsistency {
+                description = '''The validator shall report an error when a
+                relationship modeled in a unit design entity is missing from
+                the matching implementation entity, or when the matching
+                implementation relationship differs in source, target, or
+                relationship type.'''
+                derived_from = [UseCases.Validate_Unit_Specification_Documents]
+                satisfied_by = Verifier
+            }
+
+            ToolQualification.ToolRequirement ClassDesignImplementationTypeNormalization {
+                description = '''The validator shall normalize namespace
+                separators, the `std::` type prefix, and pointer or reference
+                spacing before comparing entity references and type names
+                between unit design and implementation class diagrams.'''
+                derived_from = [UseCases.Validate_Unit_Specification_Documents]
+                satisfied_by = Verifier
+            }
+
+        }
+
     }
 
 }

validation/core/docs/specifications/class_design_implementation.md

@@ -0,0 +1,232 @@
+<!-- ----------------------------------------------------------------------------
+  Copyright (c) 2026 Contributors to the Eclipse Foundation
+
+  See the NOTICE file(s) distributed with this work for additional
+  information regarding copyright ownership.
+
+  This program and the accompanying materials are made available under the
+  terms of the Apache License Version 2.0 which is available at
+  https://www.apache.org/licenses/LICENSE-2.0
+
+  SPDX-License-Identifier: Apache-2.0
+----------------------------------------------------------------------------- -->
+
+# Class Design Implementation Specification
+
+## Purpose
+
+This validator enforces consistency between the class model in the unit design
+and the class model extracted from the implementation.
+
+It shall make sure that every class, member, method, enum literal, type alias,
+and relationship modeled in the unit design exists in the implementation and is
+compatible with it.
+
+Implementation-only entities and members are allowed. The unit design is the
+validated contract.
+
+## What is Validated
+
+The validator compares unit design class diagrams with implementation class
+diagrams produced by the C++ parser. It receives two indexed class-diagram
+inputs:
+
+| Input | Source | Meaning |
+|---|---|---|
+| `design_classes` | `unit_design` class diagram FlatBuffers | Required class model from the unit design |
+| `implementation_classes` | C++ parser class diagram FlatBuffers from `unit` implementation targets | Observed class model from implementation code |
+
+### Entity Presence and Type Consistency
+
+Every entity in the unit design class diagram must have a corresponding entity
+in the implementation class diagram. Matching entities must have the same entity
+type.
+*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationEntityConsistency`)*
+
+This item covers entity matching and entity type only. The consistency of data
+contained by a matched entity is covered by the following type alias, variable,
+method, enum literal, relationship, and template parameter items.
+
+```text
+' unit design class diagram
+package vehicle {
+  class "Transport"
+}
+
+' implementation C++ code
+namespace vehicle {
+  class Transport {}
+}
+```
+
+### Template Parameter Consistency
+
+Template parameters modeled on unit design entities and methods must match the
+template parameters on the corresponding implementation entities and methods.
+*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationTemplateParameterConsistency`)*
+
+```text
+' unit design class diagram
+class Repository<T> {
+  + FindById<Key>(id: Key) : T
+}
+
+' implementation C++ code
+template <typename T>
+class Repository {
+  template <typename Key>
+  T FindById(Key id);
+}
+```
+
+### Type Alias Consistency
+
+Every type alias modeled in the unit design entity must exist in the matching
+implementation entity. The alias name and normalized original type must match.
+*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationTypeAliasConsistency`)*
+
+```text
+' unit design class diagram
+class "Transport" {
+  using Payload = std::uint8_t
+}
+
+' implementation C++ code
+class Transport {
+public:
+  using Payload = std::uint8_t;
+};
+```
+
+### Variable Consistency
+
+Every variable modeled in the unit design entity must exist in the matching
+implementation entity. The variable name, normalized data type, visibility, and
+static flag must match.
+*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationVariableConsistency`)*
+
+```text
+' unit design class diagram
+class "Transport" {
+  - buffer: std::uint8_t*
+  {static} - instance_count: uint32_t
+}
+
+' implementation C++ code
+class Transport {
+private:
+  std::uint8_t* buffer;
+  static std::uint32_t instance_count;
+};
+```
+
+### Method Consistency
+
+Every method modeled in the unit design entity must exist in the matching
+implementation entity. The method name, visibility, parameters, and method
+modifiers must match. For non-constructor/non-destructor methods, normalized
+return type must also match. Method modifiers include `static`, `virtual`,
+`abstract`, `override`, constructor, destructor, and `noexcept`.
+*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationMethodConsistency`)*
+
+Method lookup first tries the full normalized signature. If no exact signature
+match exists and exactly one implementation method has the same name, that
+method is compared to produce field-level diagnostics. If multiple same-named
+implementation overloads exist, the design method is reported as missing because
+the validator cannot safely choose a candidate.
+
+```text
+' unit design class diagram
+class "Transport" {
+  + Dispatch(mode: std::uint8_t, payload: vehicle::Payload): bool
+}
+
+' implementation C++ code
+bool Transport::Dispatch(std::uint8_t mode, vehicle::Payload payload)
+```
+
+### Enum Literal Consistency
+
+Every enum literal modeled in the unit design enum must exist in the matching
+implementation enum. The full literal data must match.
+*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationEnumLiteralConsistency`)*
+
+```text
+' unit design class diagram
+enum "Mode" {
+  Startup
+  Shutdown
+}
+
+' implementation C++ code
+enum Mode {
+  Startup,
+  Shutdown,
+};
+```
+
+### Relationship Consistency
+
+Every relationship modeled on a unit design entity must exist on the matching
+implementation entity. Source, target, and relationship type must match.
+*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationRelationshipConsistency`)*
+
+```text
+' unit design class diagram
+struct Payload {}
+class Vehicle {
+  + Load(payload : Payload)
+}
+Vehicle ..> Payload
+
+' implementation C++ code
+struct Payload {};
+class Vehicle {
+public:
+  void Load(Payload payload);
+};
+```
+
+### Type Normalization
+
+Before comparing types, the validator applies limited normalization.
+*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationTypeNormalization`)*
+
+| Input form | Normalized form |
+|---|---|
+| `std::uint8_t` | `uint8_t` |
+| `uint8_t *` | `uint8_t*` |
+| `Payload &` | `Payload&` |
+
+## Failure Cases
+
+| Failure case | Validation rule |
+|---|---|
+| Missing implementation entity | Entity Presence and Type Consistency |
+| Entity type mismatch | Entity Presence and Type Consistency |
+| Entity template parameter mismatch | Template Parameter Consistency |
+| Missing type alias | Type Alias Consistency |
+| Type alias original type mismatch | Type Alias Consistency |
+| Missing variable | Variable Consistency |
+| Variable type, visibility, or static flag mismatch | Variable Consistency |
+| Missing method | Method Consistency |
+| Method return type, visibility, parameter, or modifier mismatch | Method Consistency |
+| Method template parameter mismatch | Template Parameter Consistency |
+| Missing enum literal | Enum Literal Consistency |
+| Enum literal data mismatch | Enum Literal Consistency |
+| Missing relationship | Relationship Consistency |
+| Relationship source, target, or type mismatch | Relationship Consistency |
+
+## Debug Output
+
+The validator emits debug output containing:
+
+- the design entity ID being compared
+- the implementation entity ID being compared
+- detailed design entity snapshots at trace level
+- detailed implementation entity snapshots at trace level
+- type aliases, variables, methods, template parameters, enum literals, and
+  relationships for each matched entity
+
+Failure messages contain source file and source line information when available.
+Missing or empty source metadata is rendered as `<unknown>`.