Implement Phase 2 semantic model and improve documentation quality

.cspell.yaml

@@ -56,6 +56,7 @@ words:
   - sysml2tools
   - kerml
   - KerML
+  - supertypes
   - daltskin
   - interp
   - Dlanguage

.reviewmark.yaml

@@ -170,6 +170,78 @@ reviews:
       - "test/DemaConsulting.SysML2Tools.Tests/Parser/WorkspaceParserTests.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Parser/OmgModelsTests.cs"
 
+  - id: SysML2Tools-Core-Parser-Changes
+    title: Review of Parser Changes for Phase 2 (StdlibLoader KerML + ParseSourceToCst)
+    context:
+      - docs/reqstream/sysml2-tools-core/parser.yaml
+      - docs/design/sysml2-tools-core/parser.md
+    paths:
+      - "src/DemaConsulting.SysML2Tools/Parser/WorkspaceParser.cs"
+      - "src/DemaConsulting.SysML2Tools/Parser/Internal/StdlibLoader.cs"
+      - "test/DemaConsulting.SysML2Tools.Tests/Parser/WorkspaceParserTests.cs"
+
+  - id: SysML2Tools-Core-Semantic-Design
+    title: Review that DemaConsulting.SysML2Tools Semantic Design is Consistent and Complete
+    context:
+      - docs/reqstream/sysml2-tools-core/semantic.yaml
+    paths:
+      - "docs/design/introduction.md"
+      - "docs/design/sysml2-tools-core.md"
+      - "docs/design/sysml2-tools-core/semantic.md"
+      - "docs/design/sysml2-tools-core/semantic/**/*.md"
+
+  - id: SysML2Tools-Core-Semantic-Verification
+    title: Review that DemaConsulting.SysML2Tools Semantic Verification is Consistent and Complete
+    context:
+      - docs/reqstream/sysml2-tools-core/semantic.yaml
+    paths:
+      - "docs/verification/introduction.md"
+      - "docs/verification/sysml2-tools-core.md"
+      - "docs/verification/sysml2-tools-core/semantic.md"
+      - "docs/verification/sysml2-tools-core/semantic/**/*.md"
+
+  - id: SysML2Tools-Core-Semantic-AllRequirements
+    title: Review that All DemaConsulting.SysML2Tools Semantic Requirements are Complete
+    context:
+      - docs/design/sysml2-tools-core.md
+      - docs/reqstream/sysml2-tools-core.yaml
+    paths:
+      - "docs/reqstream/sysml2-tools-core/semantic/**/*.yaml"
+      - "docs/reqstream/sysml2-tools-core/semantic.yaml"
+
+  - id: SysML2Tools-Core-Semantic-Implementation
+    title: Review of DemaConsulting.SysML2Tools Semantic Implementation
+    context:
+      - docs/reqstream/sysml2-tools-core/semantic.yaml
+      - docs/design/sysml2-tools-core/semantic.md
+    paths:
+      - "src/DemaConsulting.SysML2Tools/Semantic/WorkspaceLoader.cs"
+      - "src/DemaConsulting.SysML2Tools/Semantic/SysmlLoadResult.cs"
+      - "src/DemaConsulting.SysML2Tools/Semantic/SysmlWorkspace.cs"
+      - "src/DemaConsulting.SysML2Tools/Semantic/Internal/SysmlNode.cs"
+      - "src/DemaConsulting.SysML2Tools/Semantic/Internal/AstBuilder.cs"
+      - "src/DemaConsulting.SysML2Tools/Semantic/Internal/SymbolTable.cs"
+      - "src/DemaConsulting.SysML2Tools/Semantic/Internal/ReferenceResolver.cs"
+      - "src/DemaConsulting.SysML2Tools/Semantic/Internal/SupertypeWalker.cs"
+      - "test/DemaConsulting.SysML2Tools.Tests/Semantic/WorkspaceLoaderTests.cs"
+      - "test/DemaConsulting.SysML2Tools.Tests/Semantic/SemanticOmgModelsTests.cs"
+
+  - id: SysML2Tools-Core-Semantic-WorkspaceLoader
+    title: Review of DemaConsulting.SysML2Tools Semantic WorkspaceLoader Unit Implementation
+    context:
+      - docs/design/sysml2-tools-core.md
+      - docs/reqstream/sysml2-tools-core.yaml
+      - docs/design/sysml2-tools-core/semantic.md
+      - docs/reqstream/sysml2-tools-core/semantic.yaml
+    paths:
+      - "docs/reqstream/sysml2-tools-core/semantic/workspace-loader.yaml"
+      - "docs/design/sysml2-tools-core/semantic/workspace-loader.md"
+      - "docs/verification/sysml2-tools-core/semantic/workspace-loader.md"
+      - "src/DemaConsulting.SysML2Tools/Semantic/WorkspaceLoader.cs"
+      - "test/DemaConsulting.SysML2Tools.Tests/Semantic/WorkspaceLoaderTests.cs"
+      - "test/DemaConsulting.SysML2Tools.Tests/Semantic/SemanticOmgModelsTests.cs"
+      - "test/SysMLModels/software-structure.sysml"
+
   # SysML2Tools SVG Renderer
   - id: SysML2Tools-Svg-Architecture
     title: Review that DemaConsulting.SysML2Tools.Svg Architecture Satisfies Requirements

docs/design/introduction.md

@@ -37,7 +37,14 @@ system, subsystem, and unit levels:
     - **WorkspaceParser** (Unit) — public API: parses file glob patterns and source strings against the embedded stdlib
     - **Internal** (Subsystem) — internal implementation details
       - **SysmlDiagnosticListener** (Unit) — collects ANTLR4 syntax errors as SysmlDiagnostic records
-      - **StdlibLoader** (Unit) — enumerates and loads embedded .sysml stdlib resources; defers .kerml to Phase 2
+      - **StdlibLoader** (Unit) — enumerates and loads embedded stdlib resources; KerML errors are downgraded to Warnings
+  - **Semantic** (Subsystem) — SysML/KerML semantic model: symbol table, reference resolution, supertype walking
+    - **WorkspaceLoader** (Unit) — public API: loads SysML/KerML files into a semantic workspace
+    - **Internal** (Subsystem) — internal semantic implementation
+      - **AstBuilder** (Unit) — builds AST from ANTLR4 CST with qualified names and supertype lists
+      - **SymbolTable** (Unit) — registry mapping qualified names to declaration nodes
+      - **ReferenceResolver** (Unit) — resolves supertype references; detects circular imports
+      - **SupertypeWalker** (Unit) — walks specialization chains; detects cyclic specialization
 - **DemaConsulting.SysML2Tools.Svg** (System) — SVG renderer: renders `LayoutTree` to
   SVG output with zero external dependencies
   - TODO: subsystems and units to be defined in Phase 4+
@@ -50,7 +57,7 @@ system, subsystem, and unit levels:
   - **Cli** (Subsystem) — command-line argument parsing and I/O
     - **Context** (Unit) — argument parser and I/O owner
   - **Lint** (Subsystem) — lint command implementation
-    - **LintCommand** (Unit) — resolves glob patterns, invokes WorkspaceParser, reports diagnostics
+    - **LintCommand** (Unit) — resolves glob patterns, invokes WorkspaceLoader, reports diagnostics
   - **SelfTest** (Subsystem) — self-validation test runner
     - **Validation** (Unit) — self-validation test runner
   - **Utilities** (Subsystem) — shared utilities

docs/design/sysml2-tools-core.md

@@ -6,10 +6,14 @@ The `DemaConsulting.SysML2Tools` core library provides the SysML v2 parsing engi
 standard library, and the foundation for future semantic model, layout algorithms, and the
 `IRenderer` interface shared by all renderer packages.
 
-The system contains one subsystem in Phase 1: **Parser**, which is further divided into the public
-API unit (`WorkspaceParser`) and an internal subsystem (`Internal`) containing
-`SysmlDiagnosticListener` and `StdlibLoader`. Supporting data types (`DiagnosticSeverity`,
-`SysmlDiagnostic`, `WorkspaceParseResult`) are declared at the `Parser` namespace level.
+The system contains two subsystems in Phase 2: **Parser** and **Semantic**. The Parser subsystem
+provides syntax-level parsing, while the Semantic subsystem builds a symbol table and performs
+reference resolution. The Parser subsystem is further divided into the public API unit
+(`WorkspaceParser`) and an internal subsystem (`Internal`) containing `SysmlDiagnosticListener`
+and `StdlibLoader`. The Semantic subsystem contains the public `WorkspaceLoader` unit and an
+internal subsystem with `AstBuilder`, `SymbolTable`, `ReferenceResolver`, and `SupertypeWalker`.
+Supporting data types (`DiagnosticSeverity`, `SysmlDiagnostic`, `WorkspaceParseResult`,
+`SysmlLoadResult`, `SysmlWorkspace`) are declared at the appropriate namespace levels.
 
 ```mermaid
 flowchart TD
@@ -18,8 +22,20 @@ flowchart TD
         SysmlDiagnosticListener
         StdlibLoader
     end
+    subgraph Semantic
+        WorkspaceLoader
+        AstBuilder
+        SymbolTable
+        ReferenceResolver
+        SupertypeWalker
+    end
     WorkspaceParser --> StdlibLoader
     WorkspaceParser --> SysmlDiagnosticListener
+    WorkspaceLoader --> WorkspaceParser
+    WorkspaceLoader --> AstBuilder
+    WorkspaceLoader --> SymbolTable
+    WorkspaceLoader --> ReferenceResolver
+    WorkspaceLoader --> SupertypeWalker
 ```
 
 ## External Interfaces
@@ -62,15 +78,39 @@ file path.
 - *Role*: Data type.
 - *Values*: `Info`, `Warning`, `Error`.
 
+**WorkspaceLoader.LoadAsync**: Loads the embedded stdlib plus every user file into a semantic workspace.
+
+- *Type*: In-process .NET static async method.
+- *Role*: Provider.
+- *Contract*: Accepts `IEnumerable<string> filePaths`; returns `Task<SysmlLoadResult>` containing
+  the semantic workspace, all collected diagnostics, and a `HasErrors` flag. Stdlib ASTs are
+  cached; user files are parsed in parallel on the thread pool.
+- *Constraints*: `filePaths` must not be null; each path should be a readable file path.
+
+**SysmlLoadResult**: Aggregate result record returned by `WorkspaceLoader.LoadAsync`.
+
+- *Type*: Sealed record.
+- *Role*: Data transfer object.
+- *Contract*: Exposes `SysmlWorkspace? Workspace`, `IReadOnlyList<SysmlDiagnostic> Diagnostics`,
+  and `bool HasErrors`.
+
+**SysmlWorkspace**: Semantic workspace containing all registered declarations.
+
+- *Type*: Sealed class.
+- *Role*: Data container.
+- *Contract*: Exposes `IReadOnlyList<string> Files` and
+  `IReadOnlyDictionary<string, object> Declarations`.
+
 ## Dependencies
 
 - **Antlr4.Runtime.Standard** — ANTLR4 C# runtime; provides `AntlrInputStream`,
   `CommonTokenStream`, `IAntlrErrorListener<T>`, and the infrastructure for running
   the pre-generated `SysMLv2Lexer` and `SysMLv2Parser`. See *ANTLR4 Integration Design*.
 - **Embedded Stdlib resources** — 94 SysML v2 standard library files (58 `.sysml` + 36
   `.kerml`) from the Systems-Modeling/SysML-v2-Release tag 2026-04; licensed EPL-2.0 and
-  committed under `Stdlib/`. Phase 1 loads only the `.sysml` files; `.kerml` files are
-  embedded but not parsed until Phase 2.
+  committed under `Stdlib/`. All 94 stdlib files (58 `.sysml` + 36 `.kerml`) are loaded by
+  WorkspaceLoader; KerML parse errors are downgraded to Warnings because the SysML v2 grammar
+  does not fully cover KerML-specific syntax.
 
 ## Risk Control Measures
 
@@ -96,6 +136,26 @@ N/A — not a safety-classified software item.
 6. After all async work completes, `WorkspaceParser.ParseAsync` concatenates stdlib and user-file
    paths and diagnostics into a `WorkspaceParseResult` and returns it.
 
+### Semantic Data Flow
+
+1. `WorkspaceLoader.LoadAsync` awaits the shared `Lazy<Task<StdlibSemanticResult>>` stdlib
+   semantic task. On first call, the factory fires `Task.Run(BuildStdlibSemanticAsync)`, which
+   enumerates all embedded manifest resources matching both `.sysml` and `.kerml` extensions,
+   reads each stream, parses to a CST via `WorkspaceParser.ParseSourceToCst`, builds a typed
+   AST via `AstBuilder.Build`, and collects all diagnostics (KerML errors downgraded to Warnings).
+2. Concurrently, all caller-supplied file paths are dispatched to the thread pool via
+   `Task.WhenAll`, each reading file content and calling `WorkspaceParser.ParseSourceToCst`
+   followed by `AstBuilder.Build`; file I/O failures are caught and returned as Error-severity
+   diagnostics.
+3. `SymbolTable.RegisterAll` is called for each stdlib and user AST root, building the
+   qualified-name registry.
+4. `ReferenceResolver.ResolveAll` iterates all registered symbols, resolving supertype
+   references and emitting Warning diagnostics for unresolved names and circular imports.
+5. `SupertypeWalker.WalkAll` traverses every specialization chain, detecting cyclic
+   specialization and emitting Warning diagnostics for detected cycles.
+6. A `SysmlWorkspace` is constructed from the loaded file list and symbol table, and wrapped
+   in a `SysmlLoadResult` with all accumulated diagnostics.
+
 ## Design Constraints
 
 - Platform: multi-targets net8.0, net9.0, and net10.0 on Windows, Linux, and macOS.
@@ -104,5 +164,6 @@ N/A — not a safety-classified software item.
 - The ANTLR4-generated C# files under `Parser/Antlr/` are committed to the repository and
   must not be manually edited; they are regenerated using `antlr-4.13.1-complete.jar` as
   documented in `Grammar/README.md`.
-- Phase 1 performs syntax-only parsing (CST construction). No semantic model, symbol table,
-  or reference resolution is performed.
+- `WorkspaceParser` provides syntax-only parsing (CST construction). Semantic model
+  construction, symbol table registration, and reference resolution are performed by
+  `WorkspaceLoader` in the Semantic subsystem.

docs/design/sysml2-tools-core/semantic.md

@@ -0,0 +1,80 @@
+## DemaConsulting.SysML2Tools — Semantic Subsystem
+
+### Overview
+
+The Semantic subsystem builds a semantic workspace from the parsed SysML/KerML source files. It
+operates as a second layer above the Parser subsystem, consuming ANTLR4 CSTs produced by
+`WorkspaceParser` and transforming them into a structured symbol table with resolved references.
+
+### Interfaces
+
+The Semantic subsystem contains one public unit (`WorkspaceLoader`) and an internal subsystem
+(`Internal`) containing `AstBuilder`, `SymbolTable`, `ReferenceResolver`, and `SupertypeWalker`.
+
+```mermaid
+flowchart TD
+    subgraph Semantic
+        WorkspaceLoader
+        subgraph Internal
+            AstBuilder
+            SymbolTable
+            ReferenceResolver
+            SupertypeWalker
+        end
+    end
+    WorkspaceLoader --> AstBuilder
+    WorkspaceLoader --> SymbolTable
+    WorkspaceLoader --> ReferenceResolver
+    WorkspaceLoader --> SupertypeWalker
+    AstBuilder --> SymbolTable
+```
+
+**WorkspaceLoader.LoadAsync**: Loads the embedded stdlib plus every file in the provided
+collection asynchronously.
+
+- *Type*: In-process .NET static async method.
+- *Role*: Provider.
+- *Contract*: Accepts `IEnumerable<string> filePaths`; returns `Task<SysmlLoadResult>` containing
+  a `SysmlWorkspace` with all qualified-name declarations and all collected diagnostics. Stdlib
+  is loaded and cached; user files are parsed in parallel on the thread pool.
+- *Constraints*: `filePaths` must be valid, readable file paths. KerML stdlib parse errors are
+  downgraded to Warnings since the SysML v2 grammar does not fully cover KerML syntax.
+
+**SysmlLoadResult**: Aggregate result returned by `WorkspaceLoader.LoadAsync`.
+
+- *Type*: Sealed record.
+- *Role*: Data transfer object.
+- *Contract*: Exposes `SysmlWorkspace? Workspace`, `IReadOnlyList<SysmlDiagnostic> Diagnostics`,
+  and `bool HasErrors`.
+
+**SysmlWorkspace**: Fully-loaded and semantically-resolved workspace.
+
+- *Type*: Sealed class.
+- *Role*: Data container.
+- *Contract*: Exposes `IReadOnlyList<string> Files` and `IReadOnlyDictionary<string, object> Declarations`
+  mapping qualified names to declaration nodes.
+
+### Design
+
+1. `WorkspaceLoader.LoadAsync` awaits the shared `Lazy<Task<StdlibSemanticResult>>` stdlib result.
+   On first call the factory fires `Task.Run(BuildStdlibSemanticAsync)`, which reads each stdlib
+   resource stream, calls `WorkspaceParser.ParseSourceToCst`, downgrades KerML parse errors to
+   Warnings, builds an AST via `AstBuilder`, and registers it into a `SymbolTable`.
+2. Concurrently, all caller-supplied file paths are dispatched via `Task.WhenAll`, each parsing
+   its content via `WorkspaceParser.ParseSourceToCst`, building an AST, and registering into
+   the same `SymbolTable`.
+3. `ReferenceResolver.ResolveAll` traverses all AST nodes, checks each supertype name against
+   the symbol table, and emits Warning diagnostics for unresolved references. It also builds
+   an import graph and performs cycle detection.
+4. `SupertypeWalker.WalkAll` traverses specialization chains for all symbols and emits Warning
+   diagnostics for cyclic specialization.
+5. A `SysmlWorkspace` is constructed from the loaded file list and symbol table, and returned
+   in a `SysmlLoadResult`.
+
+### Design Constraints
+
+- KerML stdlib files are parsed with the SysML v2 grammar; any parse errors are downgraded to
+  Warnings since the grammar does not fully support KerML-specific syntax.
+- The stdlib AST and symbol table are cached in a static `Lazy<Task<>>` and shared across all
+  concurrent callers.
+- `AstBuilder` is not thread-safe — a separate instance is created for each file.

docs/design/sysml2-tools-core/semantic/internal.md

@@ -0,0 +1,53 @@
+### Semantic Internal Subsystem
+
+#### Overview
+
+The Semantic Internal subsystem provides the implementation details of the semantic loading pipeline.
+It contains four units: `AstBuilder`, `SymbolTable`, `ReferenceResolver`, and `SupertypeWalker`.
+
+#### Interfaces
+
+**`AstBuilder.Build(RootNamespaceContext)`**: Transforms the ANTLR4 CST root into a typed AST root.
+
+- *Type*: In-process .NET internal method.
+- *Role*: Provider.
+- *Contract*: Accepts a `SysMLv2Parser.RootNamespaceContext`; returns `SysmlPackageNode?` —
+  the root package node, or `null` if the root contains no named elements.
+
+**`SymbolTable.RegisterAll(SysmlNode?)`**: Registers all named nodes from an AST root.
+
+- *Type*: In-process .NET internal method.
+- *Role*: Provider.
+- *Contract*: Traverses the AST depth-first and inserts each non-null `QualifiedName` into
+  the symbol dictionary. Duplicate names are silently ignored.
+
+**`ReferenceResolver.ResolveAll(IEnumerable<(string, SysmlNode?)>)`**: Runs import-cycle detection
+and supertype reference resolution over all loaded file roots.
+
+- *Type*: In-process .NET internal method.
+- *Role*: Provider.
+- *Contract*: Accepts a list of `(FilePath, Root)` pairs; emits Warning diagnostics for
+  unresolved supertype names and for circular import chains.
+
+**`SupertypeWalker.WalkAll()`**: Traverses all specialization chains to detect cyclic specialization.
+
+- *Type*: In-process .NET internal method.
+- *Role*: Provider.
+- *Contract*: Iterates all symbols in the `SymbolTable`; emits Warning diagnostics for any
+  cycle detected.
+
+#### Design
+
+| Unit | Responsibility |
+| --- | --- |
+| `AstBuilder` | Visits ANTLR4 CST; builds typed AST nodes with qualified names and supertype lists |
+| `SymbolTable` | Registry mapping fully-qualified names to their AST nodes |
+| `ReferenceResolver` | Checks supertype references; detects circular import chains |
+| `SupertypeWalker` | Walks specialization chains; detects cyclic specialization |
+
+Interaction sequence:
+
+1. `WorkspaceLoader` creates one `AstBuilder` per file and calls `Build(rootNamespaceContext)`.
+2. The returned `SysmlPackageNode` root is passed to `SymbolTable.RegisterAll`.
+3. After all files are registered, `ReferenceResolver.ResolveAll` traverses all AST roots.
+4. Finally, `SupertypeWalker.WalkAll` iterates over all symbols in the table.