update graph

Author: KSemenenko

Directory.Packages.props

@@ -5,6 +5,7 @@
 
   <ItemGroup>
     <PackageVersion Include="dotNetRdf" Version="3.5.1" />
+    <PackageVersion Include="dotNetRdf.Shacl" Version="3.5.1" />
     <PackageVersion Include="DotNet.ReproducibleBuilds" Version="1.2.25" />
     <PackageVersion Include="Markdig" Version="1.1.2" />
     <PackageVersion Include="Microsoft.Extensions.AI" Version="10.4.1" />

docs/ADR/ADR-0001-rdf-sparql-library.md

@@ -11,6 +11,7 @@ Related Features: `docs/Architecture.md`
 - [x] Analyze upstream graph stack and .NET options.
 - [x] Choose the RDF/SPARQL dependency.
 - [x] Add dotNetRDF to the production project.
+- [x] Add `dotNetRdf.Shacl` when graph validation became a first-class library boundary.
 - [x] Add flow tests that query generated graphs through SPARQL.
 - [x] Run build, test, format, and coverage commands.
 - [x] Update `docs/Architecture.md` if dependency boundaries change.
@@ -41,12 +42,13 @@ Non-goals:
 
 ## Decision
 
-Use dotNetRDF as the RDF graph, serialization, and SPARQL engine for the first .NET implementation slice.
+Use dotNetRDF as the RDF graph, serialization, SPARQL, and SHACL validation engine for the .NET implementation.
 
 Key points:
 
 - dotNetRDF replaces Python RDFLib for the C# port.
 - The selected package supports RDF/SPARQL in .NET and the user guide documents in-memory RDF data and in-memory SPARQL querying, which matches the no-server core runtime boundary.
+- The `dotNetRdf.Shacl` package provides a SHACL processor over in-memory RDF graphs, which keeps validation standards-based and local.
 - Markdig and YamlDotNet will handle Markdown/front matter parsing separately.
 - AI extraction remains behind an extraction port that uses `Microsoft.Extensions.AI.IChatClient`; provider/orchestration packages are not part of this RDF dependency decision.
 
@@ -64,6 +66,7 @@ flowchart LR
     None --> Builder
     Builder --> DotNetRdf["dotNetRDF graph"]
     DotNetRdf --> Sparql["Local SPARQL execution"]
+    DotNetRdf --> Shacl["Local SHACL validation"]
     DotNetRdf --> Turtle["Turtle writer"]
     DotNetRdf --> JsonLd["JSON-LD writer"]
 ```
@@ -99,13 +102,15 @@ flowchart LR
 ### Negative / risks
 
 - The core library takes a dependency on dotNetRDF APIs.
+- SHACL validation uses dotNetRDF report objects internally, but public results stay in repository-owned models.
 - JSON-LD support may require a specific package shape or writer availability in the selected version.
 - Performance characteristics are inherited from dotNetRDF and must be measured before promising large-scale query throughput.
 
 Mitigations:
 
 - Hide dependency details behind `KnowledgeGraph` query methods, `KnowledgeSearchService`, and serialization methods where practical.
 - Add tests for serialization and SPARQL query paths.
+- Add tests for SHACL conformance and violation report paths.
 - Keep remote/federated SPARQL out of the first slice.
 
 ## Impact
@@ -151,6 +156,7 @@ Mitigations:
   - Serialize the graph and parse/inspect the output.
 - Negative flows:
   - Reject mutating SPARQL operations.
+  - Validate malformed graph metadata through SHACL reports.
   - Default no-extractor mode.
   - Explicit Tiktoken token-distance mode.
 - Edge flows:
@@ -183,6 +189,7 @@ Mitigations:
 | TST-003 | Mutating SPARQL query | Integration | Rejected before execution | Safety |
 | TST-004 | Empty input | Integration | Empty graph and empty search results | Edge |
 | TST-005 | Malformed assertion syntax | Integration | Ignored without graph corruption | Negative |
+| TST-006 | SHACL validation | Integration | Valid graphs conform and invalid graph metadata reports violations | Standards validation |
 
 ## Rollout and migration
 
@@ -196,3 +203,4 @@ No migration exists yet. This is the initial implementation decision.
 - `external/lqdev-markdown-ld-kb/.ai-memex/blog-post-zero-cost-knowledge-graph-from-markdown.md`
 - dotNetRDF upstream repository: `https://github.com/dotnetrdf/dotnetrdf`
 - dotNetRDF user guide: `https://dotnetrdf.org/docs/stable/user_guide/index.html`
+- SHACL validation feature: `docs/Features/GraphShaclValidation.md`

docs/Architecture.md

@@ -1,6 +1,6 @@
 # Markdown-LD Knowledge Bank Architecture
 
-Date: 2026-04-11
+Date: 2026-04-15
 
 ## Purpose
 
@@ -32,6 +32,7 @@ flowchart LR
     Graph --> Sparql["In-memory SPARQL executor API"]
     Graph --> Search["In-memory graph search API"]
     Graph --> Focused["Focused graph search API"]
+    Graph --> Shacl["SHACL validation API"]
     Graph --> Serializers["Turtle and JSON-LD serializers"]
     Graph --> Merge["Thread-safe graph merge API"]
     IChatClient["Microsoft.Extensions.AI IChatClient"] --> ChatExtractor
@@ -50,6 +51,7 @@ sequenceDiagram
     participant Chat as IChatClient
     participant Tokenizer as Tiktoken tokenizer
     participant Graph as KnowledgeGraphBuilder
+    participant BuiltGraph as KnowledgeGraph
     participant Query as InMemorySparqlExecutor
 
     Caller->>Pipeline: BuildAsync(documents, options)
@@ -69,6 +71,9 @@ sequenceDiagram
     Router-->>Pipeline: Entities, assertions, optional token index
     Pipeline->>Graph: Add facts as RDF triples
     Graph-->>Pipeline: In-memory KnowledgeGraph
+    Pipeline-->>Caller: MarkdownKnowledgeBuildResult
+    Caller->>BuiltGraph: ValidateShacl(optional shapes)
+    BuiltGraph-->>Caller: SHACL validation report
     Caller->>Query: ExecuteSelect(graph, sparql)
     Query-->>Caller: SPARQL bindings
 ```
@@ -84,6 +89,7 @@ flowchart TB
         Tokens["Tiktoken: subword TF-IDF vectors, keyphrase topics, explicit entity hints, and token-distance search"]
         Rules["Capability rules: graph_entities, graph_edges, graph_groups, graph_related, graph_next_steps"]
         Rdf["RDF: graph construction, namespaces, serialization"]
+        Shacl["SHACL: default shapes, validation reports, assertion metadata"]
         Query["Query: SPARQL and graph search"]
     end
 
@@ -99,6 +105,7 @@ flowchart TB
     FlowTests --> Tokens
     FlowTests --> Rules
     FlowTests --> Rdf
+    FlowTests --> Shacl
     FlowTests --> Query
 ```
 
@@ -138,6 +145,7 @@ flowchart LR
 
 - Parsing depends on Markdig and YamlDotNet.
 - RDF graph building and SPARQL execution depend on dotNetRDF.
+- SHACL validation depends on `dotNetRdf.Shacl` and runs against the in-memory graph through `VDS.RDF.Shacl.ShapesGraph`.
 - LLM extraction depends on `Microsoft.Extensions.AI.Abstractions` and accepts `IChatClient`.
 - Tiktoken extraction depends on `Microsoft.ML.Tokenizers` and the O200k data package. It uses tokenizer IDs and Unicode word n-gram keyphrase candidates only, and does not add an embedding provider. The default vector weighting is subword TF-IDF fitted over the current build corpus.
 - Embeddings are not required for the core graph build/query flow.
@@ -154,6 +162,7 @@ Required first-slice scenarios:
 - Empty Markdown input produces an empty graph without throwing.
 - Explicit Tiktoken mode builds section/segment/topic/entity-hint nodes plus `schema:hasPart`, `schema:about`, `schema:mentions`, and token-distance `kb:relatedTo` edges without network access.
 - Capability graph rules build `kb:memberOf`, `kb:relatedTo`, and `kb:nextStep` workflow edges from Markdown front matter or caller options, and focused search returns primary, related, and next-step result groups.
+- SHACL validation uses default Markdown-LD Knowledge Bank shapes or caller-supplied shapes, and assertion confidence/provenance metadata is represented as RDF statements so validation remains RDF-native.
 - English, Ukrainian, French, and German queries over same-language token graphs produce a higher hit rate than cross-language translated-topic queries.
 - Term frequency, binary presence, and subword TF-IDF token weighting modes are covered by focused and flow tests.
 - SPARQL mutating queries are rejected before execution.
@@ -183,3 +192,4 @@ Coverage requirement: 95%+ line coverage for changed production code.
 - LLM extraction dependency decision: `docs/ADR/ADR-0002-llm-extraction-ichatclient.md`
 - Capability graph rules decision: `docs/ADR/ADR-0004-capability-graph-rules.md`
 - Capability graph rules feature: `docs/Features/CapabilityGraphRules.md`
+- SHACL validation feature: `docs/Features/GraphShaclValidation.md`

docs/Features/GraphShaclValidation.md

@@ -0,0 +1,67 @@
+# Graph SHACL Validation
+
+Date: 2026-04-15
+
+## Purpose
+
+Markdown-LD Knowledge Bank validates built RDF graphs with SHACL so callers can detect malformed graph construction through a standards-based report instead of custom post-processing.
+
+The feature uses `dotNetRdf.Shacl` over the in-memory `KnowledgeGraph`. It does not add a server, database, cache, provider SDK, or Python runtime.
+
+## Flow
+
+```mermaid
+flowchart LR
+    Markdown["Markdown documents"] --> Pipeline["MarkdownKnowledgePipeline"]
+    Pipeline --> Facts["Merged entities and assertions"]
+    Facts --> Reification["Direct RDF edges plus rdf:Statement metadata"]
+    Reification --> Graph["KnowledgeGraph"]
+    Shapes["Default or caller SHACL shapes"] --> Validator["dotNetRDF ShapesGraph"]
+    Graph --> Validator
+    Validator --> Report["KnowledgeGraphShaclValidationReport"]
+    Report --> Caller["Caller"]
+```
+
+## Default Shapes
+
+The built-in shapes graph validates:
+
+- `schema:Article` nodes have `schema:name` and IRI provenance.
+- common entity classes have `schema:name`.
+- `schema:sameAs` values are IRIs.
+- `prov:wasDerivedFrom` values are IRIs.
+- reified `rdf:Statement` assertion metadata has one IRI subject, predicate, object, and a decimal `kb:confidence` from 0 through 1.
+
+Callers can pass custom Turtle SHACL shapes to `KnowledgeGraph.ValidateShacl(shapesTurtle)` or `MarkdownKnowledgeBuildResult.ValidateShacl(shapesTurtle)`.
+
+## Assertion Metadata
+
+Graph assertions remain direct RDF edges for existing SPARQL/search callers. Each assertion also receives RDF reification metadata:
+
+```mermaid
+flowchart TB
+    Subject["subject IRI"] -->|"direct predicate"| Object["object IRI"]
+    Statement["blank rdf:Statement"] -->|"rdf:subject"| Subject
+    Statement -->|"rdf:predicate"| Predicate["predicate IRI"]
+    Statement -->|"rdf:object"| Object
+    Statement -->|"kb:confidence"| Confidence["xsd:decimal"]
+    Statement -->|"prov:wasDerivedFrom"| Source["source IRI or invalid literal"]
+```
+
+Invalid caller-authored `sameAs` and provenance values are represented as literals so SHACL can report node-kind violations instead of silently dropping them.
+
+## Testing Methodology
+
+Flow tests cover:
+
+- valid Markdown and configured graph rules conform to the default shapes;
+- invalid `schema:sameAs`, provenance, and assertion confidence produce SHACL results;
+- caller-supplied shapes validate the same built graph;
+- sameAs-first entity merge rewrites assertion endpoints before validation.
+
+Verification commands:
+
+- `dotnet build MarkdownLd.Kb.slnx --no-restore`
+- `dotnet test --solution MarkdownLd.Kb.slnx --configuration Release`
+- `dotnet format MarkdownLd.Kb.slnx --verify-no-changes`
+- coverage command from the root `AGENTS.md`

src/MarkdownLd.Kb/MarkdownLd.Kb.csproj

@@ -12,6 +12,7 @@
 
   <ItemGroup>
     <PackageReference Include="dotNetRdf" />
+    <PackageReference Include="dotNetRdf.Shacl" />
     <PackageReference Include="Markdig" />
     <PackageReference Include="Microsoft.Extensions.AI" />
     <PackageReference Include="Microsoft.Extensions.AI.Abstractions" />

src/MarkdownLd.Kb/Pipeline/KnowledgeFactMerger.cs

@@ -12,23 +12,28 @@ public KnowledgeExtractionResult Merge(params KnowledgeExtractionResult[] result
 
         var entities = new Dictionary<string, KnowledgeEntityFact>(StringComparer.OrdinalIgnoreCase);
         var assertions = new Dictionary<string, KnowledgeAssertionFact>(StringComparer.OrdinalIgnoreCase);
+        var entityAliases = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        var sameAsAliases = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        var pendingAssertions = new List<KnowledgeAssertionFact>();
 
         foreach (var result in results)
         {
             ArgumentNullException.ThrowIfNull(result);
 
             foreach (var entity in result.Entities)
             {
-                UpsertEntity(entities, CanonicalizeEntity(entity));
+                UpsertEntity(entities, entityAliases, sameAsAliases, CanonicalizeEntity(entity));
             }
 
-            foreach (var assertion in result.Assertions)
+            pendingAssertions.AddRange(result.Assertions);
+        }
+
+        foreach (var assertion in pendingAssertions)
+        {
+            var canonical = RewriteAssertionAliases(CanonicalizeAssertion(assertion), entityAliases);
+            if (IsValidAssertion(canonical))
             {
-                var canonical = CanonicalizeAssertion(assertion);
-                if (IsValidAssertion(canonical))
-                {
-                    UpsertAssertion(assertions, canonical);
-                }
+                UpsertAssertion(assertions, canonical);
             }
         }
 
@@ -94,12 +99,42 @@ private static bool IsValidAssertion(KnowledgeAssertionFact assertion)
                !string.IsNullOrWhiteSpace(assertion.ObjectId);
     }
 
-    private static void UpsertEntity(IDictionary<string, KnowledgeEntityFact> entities, KnowledgeEntityFact entity)
+    private static KnowledgeAssertionFact RewriteAssertionAliases(
+        KnowledgeAssertionFact assertion,
+        IReadOnlyDictionary<string, string> entityAliases)
+    {
+        return assertion with
+        {
+            SubjectId = ResolveEntityAlias(assertion.SubjectId, entityAliases),
+            ObjectId = ShouldRewriteObject(assertion)
+                ? ResolveEntityAlias(assertion.ObjectId, entityAliases)
+                : assertion.ObjectId,
+        };
+    }
+
+    private static bool ShouldRewriteObject(KnowledgeAssertionFact assertion)
+    {
+        return !assertion.Predicate.Equals(ExpectedSchemaSameAs, StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static string ResolveEntityAlias(string nodeId, IReadOnlyDictionary<string, string> entityAliases)
     {
-        var key = entity.Id ?? entity.Label;
+        return entityAliases.TryGetValue(nodeId, out var canonicalId)
+            ? canonicalId
+            : nodeId;
+    }
+
+    private static void UpsertEntity(
+        IDictionary<string, KnowledgeEntityFact> entities,
+        IDictionary<string, string> entityAliases,
+        IDictionary<string, string> sameAsAliases,
+        KnowledgeEntityFact entity)
+    {
+        var key = ResolveEntityKey(sameAsAliases, entity);
         if (!entities.TryGetValue(key, out var existing))
         {
-            entities[key] = entity;
+            entities[key] = entity with { Id = key };
+            IndexEntityAliases(entityAliases, sameAsAliases, key, entity);
             return;
         }
 
@@ -111,6 +146,41 @@ private static void UpsertEntity(IDictionary<string, KnowledgeEntityFact> entiti
             Confidence = Math.Max(existing.Confidence, entity.Confidence),
             Source = string.IsNullOrWhiteSpace(existing.Source) ? entity.Source : existing.Source,
         };
+        IndexEntityAliases(entityAliases, sameAsAliases, key, entities[key]);
+        IndexEntityAliases(entityAliases, sameAsAliases, key, entity);
+    }
+
+    private static string ResolveEntityKey(
+        IDictionary<string, string> sameAsAliases,
+        KnowledgeEntityFact entity)
+    {
+        foreach (var sameAs in entity.SameAs)
+        {
+            if (sameAsAliases.TryGetValue(sameAs, out var existingKey))
+            {
+                return existingKey;
+            }
+        }
+
+        return entity.Id ?? entity.Label;
+    }
+
+    private static void IndexEntityAliases(
+        IDictionary<string, string> entityAliases,
+        IDictionary<string, string> sameAsAliases,
+        string key,
+        KnowledgeEntityFact entity)
+    {
+        if (!string.IsNullOrWhiteSpace(entity.Id))
+        {
+            entityAliases[entity.Id] = key;
+        }
+
+        foreach (var sameAs in entity.SameAs)
+        {
+            entityAliases[sameAs] = key;
+            sameAsAliases[sameAs] = key;
+        }
     }
 
     private static void UpsertAssertion(IDictionary<string, KnowledgeAssertionFact> assertions, KnowledgeAssertionFact assertion)