test fixes

Author: KSemenenko

README.md

@@ -587,9 +587,25 @@ internal static class ShaclValidationDemo
 }
 ```
 
-`ValidateShacl()` uses default Markdown-LD Knowledge Bank shapes backed by `dotNetRdf.Shacl`. The default shapes validate article names, entity names, `schema:sameAs` IRIs, provenance IRIs, and assertion confidence metadata.
+`ValidateShacl()` uses default Markdown-LD Knowledge Bank shapes backed by `dotNetRdf.Shacl`. The default shapes validate article names, entity names, `schema:sameAs` IRIs, provenance IRIs, and assertion confidence metadata when reified assertion metadata is present.
 
-Graph assertions remain direct RDF edges for existing SPARQL and search callers. Each assertion also gets RDF reification metadata as an `rdf:Statement` with `rdf:subject`, `rdf:predicate`, `rdf:object`, `kb:confidence`, and optional `prov:wasDerivedFrom`, so SHACL can validate assertion metadata without changing the query shape of the main graph.
+Graph assertions always remain direct RDF edges for existing SPARQL and search callers. Reified assertion metadata is now an explicit throughput trade-off:
+
+- default builds keep only the direct RDF edges, which is the fast path for large Markdown corpora and tokenized graphs
+- opt in to RDF reification when the caller needs `rdf:Statement` metadata with `rdf:subject`, `rdf:predicate`, `rdf:object`, `kb:confidence`, and optional `prov:wasDerivedFrom`
+
+Use `KnowledgeGraphBuildOptions.IncludeAssertionReification = true` when assertion-level provenance and confidence triples must be queryable:
+
+```csharp
+var pipeline = new MarkdownKnowledgePipeline(new MarkdownKnowledgePipelineOptions
+{
+    BaseUri = new Uri("https://kb.example/"),
+    BuildOptions = new KnowledgeGraphBuildOptions
+    {
+        IncludeAssertionReification = true,
+    },
+});
+```
 
 Pass custom Turtle shapes when the host application needs stricter rules:
 

docs/Features/GraphShaclValidation.md

@@ -14,10 +14,11 @@ The feature uses `dotNetRdf.Shacl` over the in-memory `KnowledgeGraph`. It does
 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"]
+    Facts --> Graph["KnowledgeGraph"]
+    Graph --> Reification["Optional rdf:Statement metadata"]
     Shapes["Default or caller SHACL shapes"] --> Validator["dotNetRDF ShapesGraph"]
     Graph --> Validator
+    Reification --> Validator
     Validator --> Report["KnowledgeGraphShaclValidationReport"]
     Report --> Caller["Caller"]
 ```
@@ -30,18 +31,18 @@ The built-in shapes graph validates:
 - 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.
+- reified `rdf:Statement` assertion metadata, when included, 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:
+Graph assertions remain direct RDF edges for existing SPARQL/search callers. RDF reification metadata is optional and controlled by `KnowledgeGraphBuildOptions.IncludeAssertionReification`.
 
 ```mermaid
 flowchart TB
     Subject["subject IRI"] -->|"direct predicate"| Object["object IRI"]
-    Statement["blank rdf:Statement"] -->|"rdf:subject"| Subject
+    Statement["optional blank rdf:Statement"] -->|"rdf:subject"| Subject
     Statement -->|"rdf:predicate"| Predicate["predicate IRI"]
     Statement -->|"rdf:object"| Object
     Statement -->|"kb:confidence"| Confidence["xsd:decimal"]

src/MarkdownLd.Kb/Graph/Build/KnowledgeGraphBuilder.cs

@@ -0,0 +1,129 @@
+using System.Globalization;
+using VDS.RDF;
+using static ManagedCode.MarkdownLd.Kb.Pipeline.PipelineConstants;
+
+namespace ManagedCode.MarkdownLd.Kb.Pipeline;
+
+internal sealed class KnowledgeGraphMaterializationContext(Graph graph)
+{
+    private readonly Dictionary<string, IUriNode> _uriNodes = new(StringComparer.Ordinal);
+    private readonly Dictionary<string, ILiteralNode> _literalNodes = new(StringComparer.Ordinal);
+    private readonly Dictionary<TypedLiteralKey, ILiteralNode> _typedLiteralNodes = [];
+    private readonly Dictionary<string, Uri?> _predicateUris = new(StringComparer.OrdinalIgnoreCase);
+    private readonly Dictionary<string, Uri> _typeUris = new(StringComparer.OrdinalIgnoreCase);
+
+    public Graph Graph { get; } = graph;
+
+    public IUriNode UriNode(Uri uri)
+    {
+        var key = uri.AbsoluteUri;
+        return _uriNodes.TryGetValue(key, out var node)
+            ? node
+            : _uriNodes[key] = Graph.CreateUriNode(uri);
+    }
+
+    public ILiteralNode LiteralNode(string value)
+    {
+        return _literalNodes.TryGetValue(value, out var node)
+            ? node
+            : _literalNodes[value] = Graph.CreateLiteralNode(value);
+    }
+
+    public ILiteralNode TypedLiteral(string value, Uri datatype)
+    {
+        var key = new TypedLiteralKey(value, datatype.AbsoluteUri);
+        return _typedLiteralNodes.TryGetValue(key, out var node)
+            ? node
+            : _typedLiteralNodes[key] = Graph.CreateLiteralNode(value, datatype);
+    }
+
+    public INode UriOrLiteralNode(string value)
+    {
+        return Uri.TryCreate(value, UriKind.Absolute, out var absolute)
+            ? UriNode(absolute)
+            : LiteralNode(value);
+    }
+
+    public ILiteralNode ConfidenceLiteral(double confidence)
+    {
+        return TypedLiteral(confidence.ToString(CultureInfo.InvariantCulture), XsdDecimalUri);
+    }
+
+    public ILiteralNode DateLiteral(string? value)
+    {
+        return DateOnly.TryParse(value, out var dateOnly)
+            ? TypedLiteral(dateOnly.ToString(DotNetDateFormat, CultureInfo.InvariantCulture), XsdDateUri)
+            : LiteralNode(value ?? string.Empty);
+    }
+
+    public Uri? ResolvePredicateUri(string predicate)
+    {
+        return _predicateUris.TryGetValue(predicate, out var cached)
+            ? cached
+            : _predicateUris[predicate] = ResolvePredicate(predicate);
+    }
+
+    public Uri ResolveTypeUri(string type)
+    {
+        return _typeUris.TryGetValue(type, out var cached)
+            ? cached
+            : _typeUris[type] = NormalizeTypeUri(type);
+    }
+
+    private static Uri? ResolvePredicate(string predicate)
+    {
+        if (predicate.Contains(':', StringComparison.Ordinal))
+        {
+            var separatorIndex = predicate.IndexOf(':');
+            var prefix = predicate[..separatorIndex];
+            var local = predicate[(separatorIndex + 1)..];
+            return prefix.ToLowerInvariant() switch
+            {
+                SchemaPrefix => new Uri(SchemaNamespaceText + local),
+                KbPrefix => new Uri(KbNamespaceText + local),
+                ProvPrefix => new Uri(ProvNamespaceText + local),
+                RdfPrefix => new Uri(RdfNamespaceText + local),
+                RdfsPrefix => new Uri(RdfsNamespaceText + local),
+                OwlPrefix => new Uri(OwlNamespaceText + local),
+                SkosPrefix => new Uri(SkosNamespaceText + local),
+                XsdPrefix => new Uri(XsdNamespaceText + local),
+                _ => Uri.TryCreate(predicate, UriKind.Absolute, out var prefixedAbsolute)
+                    ? prefixedAbsolute
+                    : null,
+            };
+        }
+
+        if (Uri.TryCreate(predicate, UriKind.Absolute, out var absolute))
+        {
+            return absolute;
+        }
+
+        return predicate.ToLowerInvariant() switch
+        {
+            MentionPredicateKey => SchemaMentionsUri,
+            AboutPredicateKey => SchemaAboutUri,
+            AuthorPredicateKey => SchemaAuthorUri,
+            CreatorPredicateKey => SchemaCreatorUri,
+            HasPartPredicateKey => SchemaHasPartUri,
+            SameAsPredicateKey => SchemaSameAsUri,
+            _ => null,
+        };
+    }
+
+    private static Uri NormalizeTypeUri(string type)
+    {
+        if (type.Contains(':', StringComparison.Ordinal))
+        {
+            return ResolvePredicate(type) ?? SchemaThingTypeUri();
+        }
+
+        return new Uri(SchemaNamespaceText + KnowledgeNaming.Slugify(type));
+    }
+
+    private static Uri SchemaThingTypeUri()
+    {
+        return new Uri(SchemaNamespaceText + KnowledgeNaming.Slugify(SchemaThingTypeText));
+    }
+
+    private readonly record struct TypedLiteralKey(string Value, string DatatypeUri);
+}

src/MarkdownLd.Kb/Graph/Build/KnowledgeGraphMaterializationContext.cs

@@ -6,6 +6,8 @@ public sealed record KnowledgeGraphBuildOptions
 
     public bool IncludeFrontMatterRules { get; init; } = true;
 
+    public bool IncludeAssertionReification { get; init; }
+
     public KnowledgeGraphSemanticLayerOptions SemanticLayers { get; init; } = KnowledgeGraphSemanticLayerOptions.Default;
 
     public IReadOnlyList<KnowledgeGraphEntityRule> Entities { get; init; } = [];

src/MarkdownLd.Kb/Graph/Build/KnowledgeGraphRules.cs

@@ -139,13 +139,19 @@ private void AddSkosLayer(
         AssertConceptScheme(graph, schemeNode, options.ConceptSchemeLabel, includeOntologyTypes);
 
         var aboutLabels = CollectAboutLabels(documents);
-        foreach (var conceptUri in CollectConceptUris(graph))
+        var conceptUris = CollectConceptUris(graph);
+        conceptUris.Remove(conceptSchemeUri);
+        var conceptLabels = CollectConceptLabels(graph);
+        var definedTerms = CollectTypedSubjects(graph, SchemaDefinedTermUri);
+        var sameAsTargets = CollectUriTargets(graph, SchemaSameAsUri);
+
+        foreach (var conceptUri in conceptUris)
         {
             var conceptNode = graph.CreateUriNode(conceptUri);
             _ = new SkosConcept(conceptNode, graph);
-            AssertConcept(graph, conceptNode, schemeNode, includeOntologyTypes && ShouldApplyOntologyConceptType(graph, conceptNode));
-            AssertConceptLabels(graph, conceptNode, aboutLabels);
-            MirrorSchemaSameAsAsSkosExactMatch(graph, conceptNode);
+            AssertConcept(graph, conceptNode, schemeNode, includeOntologyTypes && ShouldApplyOntologyConceptType(conceptUri, definedTerms, conceptLabels));
+            AssertConceptLabels(graph, conceptNode, conceptLabels, aboutLabels);
+            MirrorSchemaSameAsAsSkosExactMatch(graph, conceptNode, sameAsTargets);
         }
     }
 
@@ -195,10 +201,12 @@ private static void AssertConcept(
         graph.Assert(new Triple(conceptNode, graph.CreateUriNode(SkosTopConceptOfUri), schemeNode));
     }
 
-    private static bool ShouldApplyOntologyConceptType(Graph graph, IUriNode conceptNode)
+    private static bool ShouldApplyOntologyConceptType(
+        Uri conceptUri,
+        IReadOnlySet<Uri> definedTerms,
+        IReadOnlyDictionary<Uri, string> labels)
     {
-        return HasType(graph, conceptNode, SchemaDefinedTermUri) ||
-               TryGetLiteral(graph, conceptNode, SchemaNameUri) is not null;
+        return definedTerms.Contains(conceptUri) || labels.ContainsKey(conceptUri);
     }
 
     private static HashSet<Uri> CollectConceptUris(Graph graph)
@@ -227,13 +235,20 @@ private static void CollectTypedConceptUris(Graph graph, ISet<Uri> conceptUris)
         }
     }
 
-    private static bool HasType(Graph graph, IUriNode subject, Uri typeUri)
+    private static HashSet<Uri> CollectTypedSubjects(Graph graph, Uri typeUri)
     {
-        return graph.Triples.Any(triple => triple.Subject.Equals(subject) &&
-                                          triple.Predicate is IUriNode predicateNode &&
-                                          predicateNode.Uri == RdfTypeUri &&
-                                          triple.Object is IUriNode objectNode &&
-                                          objectNode.Uri == typeUri);
+        var subjects = new HashSet<Uri>();
+        foreach (var triple in graph.Triples.Where(static triple => triple.Predicate is IUriNode predicateNode && predicateNode.Uri == RdfTypeUri))
+        {
+            if (triple.Subject is IUriNode subjectNode &&
+                triple.Object is IUriNode objectNode &&
+                objectNode.Uri == typeUri)
+            {
+                subjects.Add(subjectNode.Uri);
+            }
+        }
+
+        return subjects;
     }
 
     private static void CollectReferencedConceptUris(Graph graph, ISet<Uri> conceptUris, Uri predicateUri)
@@ -289,11 +304,13 @@ private static IEnumerable<string> ReadFrontMatterValues(IReadOnlyDictionary<str
         }
     }
 
-    private static void AssertConceptLabels(Graph graph, IUriNode conceptNode, IReadOnlyDictionary<Uri, string> aboutLabels)
+    private static void AssertConceptLabels(
+        Graph graph,
+        IUriNode conceptNode,
+        IReadOnlyDictionary<Uri, string> conceptLabels,
+        IReadOnlyDictionary<Uri, string> aboutLabels)
     {
-        var existingLabel = TryGetLiteral(graph, conceptNode, SchemaNameUri)
-                            ?? TryGetLiteral(graph, conceptNode, SkosPrefLabelUri)
-                            ?? TryGetLiteral(graph, conceptNode, RdfsLabelUri);
+        var existingLabel = conceptLabels.GetValueOrDefault(conceptNode.Uri);
         if (existingLabel is not null)
         {
             graph.Assert(new Triple(conceptNode, graph.CreateUriNode(SkosPrefLabelUri), graph.CreateLiteralNode(existingLabel)));
@@ -308,25 +325,86 @@ private static void AssertConceptLabels(Graph graph, IUriNode conceptNode, IRead
         }
     }
 
-    private static string? TryGetLiteral(Graph graph, IUriNode subject, Uri predicateUri)
+    private static Dictionary<Uri, string> CollectConceptLabels(Graph graph)
     {
-        return graph.Triples
-            .Where(triple => triple.Subject.Equals(subject) && triple.Predicate is IUriNode predicateNode && predicateNode.Uri == predicateUri && triple.Object is ILiteralNode)
-            .Select(triple => ((ILiteralNode)triple.Object).Value)
-            .FirstOrDefault();
+        var labels = new Dictionary<Uri, LabelCandidate>();
+        foreach (var triple in graph.Triples)
+        {
+            if (triple.Subject is not IUriNode subjectNode ||
+                triple.Predicate is not IUriNode predicateNode ||
+                triple.Object is not ILiteralNode literalNode)
+            {
+                continue;
+            }
+
+            var priority = GetLabelPriority(predicateNode.Uri);
+            if (priority == 0)
+            {
+                continue;
+            }
+
+            var candidate = new LabelCandidate(literalNode.Value, priority);
+            if (!labels.TryGetValue(subjectNode.Uri, out var existing) || candidate.Priority > existing.Priority)
+            {
+                labels[subjectNode.Uri] = candidate;
+            }
+        }
+
+        return labels.ToDictionary(static pair => pair.Key, static pair => pair.Value.Value);
     }
 
-    private static void MirrorSchemaSameAsAsSkosExactMatch(Graph graph, IUriNode conceptNode)
+    private static int GetLabelPriority(Uri predicateUri)
     {
-        var sameAsTriples = graph.Triples
-            .Where(triple => triple.Subject.Equals(conceptNode) &&
-                             triple.Predicate is IUriNode predicateNode &&
-                             predicateNode.Uri == SchemaSameAsUri &&
-                             triple.Object is IUriNode)
-            .ToArray();
-        foreach (var triple in sameAsTriples)
+        if (predicateUri == SchemaNameUri)
+        {
+            return 3;
+        }
+
+        if (predicateUri == SkosPrefLabelUri)
+        {
+            return 2;
+        }
+
+        return predicateUri == RdfsLabelUri ? 1 : 0;
+    }
+
+    private static Dictionary<Uri, IReadOnlyList<IUriNode>> CollectUriTargets(Graph graph, Uri predicateUri)
+    {
+        var targets = new Dictionary<Uri, List<IUriNode>>();
+        foreach (var triple in graph.Triples.Where(triple => triple.Predicate is IUriNode predicateNode && predicateNode.Uri == predicateUri))
+        {
+            if (triple.Subject is not IUriNode subjectNode || triple.Object is not IUriNode objectNode)
+            {
+                continue;
+            }
+
+            if (!targets.TryGetValue(subjectNode.Uri, out var subjectTargets))
+            {
+                subjectTargets = [];
+                targets[subjectNode.Uri] = subjectTargets;
+            }
+
+            subjectTargets.Add(objectNode);
+        }
+
+        return targets.ToDictionary(
+            static pair => pair.Key,
+            static pair => (IReadOnlyList<IUriNode>)pair.Value);
+    }
+
+    private static void MirrorSchemaSameAsAsSkosExactMatch(
+        Graph graph,
+        IUriNode conceptNode,
+        IReadOnlyDictionary<Uri, IReadOnlyList<IUriNode>> sameAsTargets)
+    {
+        if (!sameAsTargets.TryGetValue(conceptNode.Uri, out var targets))
+        {
+            return;
+        }
+
+        foreach (var target in targets)
         {
-            graph.Assert(new Triple(conceptNode, graph.CreateUriNode(SkosExactMatchUri), triple.Object));
+            graph.Assert(new Triple(conceptNode, graph.CreateUriNode(SkosExactMatchUri), target));
         }
     }
 
@@ -348,4 +426,6 @@ private static string GetResourceLabel(Uri resourceUri)
             ? resourceUri.AbsoluteUri
             : lastSegment;
     }
+
+    private readonly record struct LabelCandidate(string Value, int Priority);
 }