tests and more work

Author: KSemenenko

.editorconfig

@@ -86,15 +86,24 @@ csharp_style_namespace_declarations = file_scoped:warning
 # Brace settings - ALWAYS use braces, even for single-line blocks
 csharp_prefer_braces = true:warning
 
-# Expression-bodied members (modern C#)
-csharp_style_expression_bodied_methods = when_on_single_line:suggestion
-csharp_style_expression_bodied_constructors = false:suggestion
-csharp_style_expression_bodied_operators = when_on_single_line:suggestion
-csharp_style_expression_bodied_properties = true:suggestion
-csharp_style_expression_bodied_indexers = true:suggestion
-csharp_style_expression_bodied_accessors = true:suggestion
-csharp_style_expression_bodied_lambdas = true:suggestion
-csharp_style_expression_bodied_local_functions = when_on_single_line:suggestion
+# Expression-bodied members are style-only noise for this library.
+csharp_style_expression_bodied_methods = false:none
+csharp_style_expression_bodied_constructors = false:none
+csharp_style_expression_bodied_operators = false:none
+csharp_style_expression_bodied_properties = false:none
+csharp_style_expression_bodied_indexers = false:none
+csharp_style_expression_bodied_accessors = false:none
+csharp_style_expression_bodied_lambdas = false:none
+csharp_style_expression_bodied_local_functions = false:none
+dotnet_diagnostic.IDE0021.severity = none
+dotnet_diagnostic.IDE0022.severity = none
+dotnet_diagnostic.IDE0023.severity = none
+dotnet_diagnostic.IDE0024.severity = none
+dotnet_diagnostic.IDE0025.severity = none
+dotnet_diagnostic.IDE0026.severity = none
+dotnet_diagnostic.IDE0053.severity = none
+dotnet_diagnostic.IDE0061.severity = none
+resharper_convert_to_expression_body_highlighting = none
 
 # Pattern matching (C# 7+)
 csharp_style_pattern_matching_over_is_with_cast_check = true:warning
@@ -484,3 +493,11 @@ indent_style = unset
 insert_final_newline = false
 tab_width = unset
 trim_trailing_whitespace = false
+
+[src/MarkdownLd.Kb/Ai/*.cs]
+# These are public root-namespace AI contracts kept in subfolders for file organization.
+resharper_check_namespace_highlighting = none
+
+[src/MarkdownLd.Kb/Models/*.cs]
+# These are public root-namespace models kept in subfolders for file organization.
+resharper_check_namespace_highlighting = none

.github/workflows/release.yml

@@ -70,10 +70,10 @@ jobs:
       run: dotnet build ${{ env.SOLUTION }} --configuration Release --no-restore
 
     - name: Test
-      run: dotnet test --solution ${{ env.SOLUTION }} --configuration Release --no-build --verbosity normal
+      run: dotnet test --solution ${{ env.SOLUTION }} --configuration Release --verbosity normal
 
     - name: Pack NuGet packages
-      run: dotnet pack ${{ env.SOLUTION }} --configuration Release --no-build -p:IncludeSymbols=false -p:SymbolPackageFormat=snupkg --output ${{ env.ARTIFACTS_DIR }}
+      run: dotnet pack ${{ env.SOLUTION }} --configuration Release -p:IncludeSymbols=false -p:SymbolPackageFormat=snupkg --output ${{ env.ARTIFACTS_DIR }}
 
     - name: Upload artifacts
       uses: actions/upload-artifact@v4

.github/workflows/validation.yml

@@ -39,16 +39,16 @@ jobs:
       run: dotnet build MarkdownLd.Kb.slnx --configuration Release --no-restore
 
     - name: Test with coverage
-      run: dotnet test --solution MarkdownLd.Kb.slnx --configuration Release --no-build --verbosity normal --coverlet --coverlet-output-format cobertura --coverlet-include '[ManagedCode.MarkdownLd.Kb]*' --results-directory TestResults/CoverletMtpFiltered
+      run: dotnet test --solution MarkdownLd.Kb.slnx --configuration Release --verbosity normal -- --coverage --coverage-output-format cobertura --coverage-output "${{ github.workspace }}/TestResults/TUnitCoverage/coverage.cobertura.xml" --coverage-settings "${{ github.workspace }}/CodeCoverage.runsettings"
 
     - name: Pack
-      run: dotnet pack MarkdownLd.Kb.slnx --configuration Release --no-build -p:IncludeSymbols=false -p:SymbolPackageFormat=snupkg --output ./artifacts
+      run: dotnet pack MarkdownLd.Kb.slnx --configuration Release -p:IncludeSymbols=false -p:SymbolPackageFormat=snupkg --output ./artifacts
 
     - name: Upload coverage artifact
       uses: actions/upload-artifact@v4
       with:
         name: coverage
-        path: TestResults/CoverletMtpFiltered/**/coverage.cobertura.xml
+        path: TestResults/TUnitCoverage/coverage.cobertura.xml
         retention-days: 5
 
     - name: Upload package artifact

AGENTS.md

@@ -62,6 +62,8 @@ Target capabilities:
 - Tests must verify the real Markdown -> graph -> query/search flow, including success, malformed input, and empty/no-match paths where relevant.
 - Tests must not use mocks, stubs, or fakes, except one local test implementation of `Microsoft.Extensions.AI.IChatClient` used to prove the LLM extraction boundary without network access.
 - Use TUnit for tests and Shouldly for assertions.
+- Fallbacks are forbidden. Do not silently substitute generic/default behaviour when parsing, extraction, graph building, query execution, or AI extraction fails; fail explicitly or skip the invalid fact with a caller-visible test.
+- Legacy or leftover old code is forbidden. Do not keep deprecated duplicate paths, compatibility shims, or unused old implementations; remove them immediately unless an ADR documents a temporary migration path.
 
 ## Global Skills
 
@@ -85,9 +87,9 @@ List only the skills this solution actually uses.
 
 - `restore`: `dotnet restore MarkdownLd.Kb.slnx`
 - `build`: `dotnet build MarkdownLd.Kb.slnx --no-restore`
-- `test`: `dotnet test MarkdownLd.Kb.slnx --no-build`
+- `test`: `dotnet test MarkdownLd.Kb.slnx --configuration Release`
 - `format`: `dotnet format MarkdownLd.Kb.slnx --verify-no-changes`
-- `coverage`: `dotnet test MarkdownLd.Kb.slnx --no-build --coverlet --coverlet-output-format cobertura --coverlet-include '[ManagedCode.MarkdownLd.Kb]*' --results-directory TestResults/CoverletMtpFiltered`
+- `coverage`: `dotnet test MarkdownLd.Kb.slnx --configuration Release -- --coverage --coverage-output-format cobertura --coverage-output "$PWD/TestResults/TUnitCoverage/coverage.cobertura.xml" --coverage-settings "$PWD/CodeCoverage.runsettings"`
 
 `.NET` runner policy:
 
@@ -96,7 +98,7 @@ List only the skills this solution actually uses.
 - Test framework: TUnit.
 - Assertion library: Shouldly.
 - Test runner model: TUnit through `dotnet test` / Microsoft.Testing.Platform-compatible execution.
-- Coverage: `coverlet.MTP` through `dotnet test --coverlet` with the production assembly include filter.
+- Coverage: `Microsoft.Testing.Extensions.CodeCoverage` through TUnit / Microsoft Testing Platform with `CodeCoverage.runsettings`.
 
 ### Project AGENTS Policy
 

Directory.Packages.props

@@ -4,14 +4,13 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageVersion Include="coverlet.collector" Version="8.0.1" />
-    <PackageVersion Include="coverlet.MTP" Version="8.0.1" />
     <PackageVersion Include="dotNetRdf" 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" />
     <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.4.1" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.4.0" />
+    <PackageVersion Include="Microsoft.Testing.Extensions.CodeCoverage" Version="18.6.2" />
     <PackageVersion Include="Shouldly" Version="4.3.0" />
     <PackageVersion Include="TUnit" Version="1.31.0" />
     <PackageVersion Include="YamlDotNet" Version="17.0.1" />

README.md

@@ -24,9 +24,9 @@ The pipeline extracts:
 
 - article identity, title, summary, dates, tags, authors, and topics from YAML front matter
 - heading sections and document identity from Markdown
-- wikilinks such as `[[RDF]]`
 - Markdown links such as `[SPARQL](https://www.w3.org/TR/sparql11-query/)`
-- assertion arrows such as `article --mentions--> RDF`
+- optional wikilinks such as `[[RDF]]`
+- optional assertion arrows such as `article --mentions--> RDF`
 - optional LLM-produced entities and assertions through `Microsoft.Extensions.AI.IChatClient`
 
 ## Install
@@ -48,11 +48,9 @@ using ManagedCode.MarkdownLd.Kb.Pipeline;
 
 internal static class MinimalGraphDemo
 {
-    private const string BaseUriText = "https://kb.example/";
-    private const string ArticlePath = "content/zero-cost-knowledge-graph.md";
     private const string SearchTerm = "rdf";
-    private const string SubjectKey = "subject";
-    private const string RdfEntityUri = "https://kb.example/id/rdf";
+    private const string NameKey = "name";
+    private const string RdfLabel = "RDF";
 
     private const string ArticleMarkdown = """
 ---
@@ -62,46 +60,38 @@ tags:
   - markdown
   - rdf
 author:
-  - label: Ada Lovelace
-    type: schema:Person
-entity_hints:
-  - label: RDF
-    type: schema:Thing
-    sameAs:
-      - https://www.w3.org/RDF/
+  - Ada Lovelace
 ---
 # Zero Cost Knowledge Graph
 
-Markdown-LD Knowledge Bank links [[RDF]] and [SPARQL](https://www.w3.org/TR/sparql11-query/).
-article --mentions--> RDF
-RDF --sameas--> https://www.w3.org/RDF/
+Markdown-LD Knowledge Bank links [RDF](https://www.w3.org/RDF/) and [SPARQL](https://www.w3.org/TR/sparql11-query/).
 """;
 
-    private const string AskQuery = """
+    private const string SelectFactsQuery = """
 PREFIX schema: <https://schema.org/>
-ASK WHERE {
-  <https://kb.example/zero-cost-knowledge-graph/> schema:name "Zero Cost Knowledge Graph" ;
-                                                    schema:keywords "markdown" ;
-                                                    schema:mentions <https://kb.example/id/rdf> .
-  <https://kb.example/id/rdf> schema:sameAs <https://www.w3.org/RDF/> .
+SELECT ?article ?entity ?name WHERE {
+  ?article a schema:Article ;
+           schema:name "Zero Cost Knowledge Graph" ;
+           schema:keywords "markdown" ;
+           schema:mentions ?entity .
+  ?entity schema:name ?name ;
+          schema:sameAs <https://www.w3.org/RDF/> .
 }
 """;
 
     public static async Task RunAsync()
     {
-        var pipeline = new MarkdownKnowledgePipeline(new Uri(BaseUriText));
+        var pipeline = new MarkdownKnowledgePipeline();
 
-        var result = await pipeline.BuildAsync([
-            new MarkdownSourceDocument(ArticlePath, ArticleMarkdown),
-        ]);
+        var result = await pipeline.BuildFromMarkdownAsync(ArticleMarkdown);
 
-        var graphHasExpectedFacts = await result.Graph.ExecuteAskAsync(AskQuery);
+        var graphRows = await result.Graph.ExecuteSelectAsync(SelectFactsQuery);
         var search = await result.Graph.SearchAsync(SearchTerm);
 
-        Console.WriteLine(graphHasExpectedFacts);
+        Console.WriteLine(graphRows.Rows.Count);
         Console.WriteLine(search.Rows.Any(row =>
-            row.Values.TryGetValue(SubjectKey, out var subject) &&
-            subject == RdfEntityUri));
+            row.Values.TryGetValue(NameKey, out var name) &&
+            name == RdfLabel));
     }
 }
 ```
@@ -113,14 +103,13 @@ using ManagedCode.MarkdownLd.Kb.Pipeline;
 
 internal static class FileGraphDemo
 {
-    private const string BaseUriText = "https://kb.example/";
     private const string FilePath = "/absolute/path/to/content/article.md";
     private const string DirectoryPath = "/absolute/path/to/content";
     private const string MarkdownSearchPattern = "*.md";
 
     public static async Task RunAsync()
     {
-        var pipeline = new MarkdownKnowledgePipeline(new Uri(BaseUriText));
+        var pipeline = new MarkdownKnowledgePipeline();
 
         var singleFile = await pipeline.BuildFromFileAsync(FilePath);
         var directory = await pipeline.BuildFromDirectoryAsync(
@@ -135,17 +124,24 @@ internal static class FileGraphDemo
 
 `KnowledgeSourceDocumentConverter` supports Markdown and other text-like knowledge inputs: `.md`, `.markdown`, `.mdx`, `.txt`, `.text`, `.log`, `.csv`, `.json`, `.jsonl`, `.yaml`, and `.yml`.
 
+You do not need to pass a base URI for normal use. Document identity is resolved in this order:
+
+- `canonicalUrl` or `canonical_url` in Markdown front matter
+- the file path, normalized the same way as the upstream project: `content/notes/rdf.md` becomes a stable document IRI
+- the generated inline document path when `BuildFromMarkdownAsync` is called without a path
+
+The library uses `urn:managedcode:markdown-ld-kb:/` as an internal default base URI only to create valid RDF IRIs when the Markdown does not provide a canonical URL. Pass `new MarkdownKnowledgePipeline(new Uri("https://your-domain/"))` only when you want generated document/entity IRIs to live under your own domain.
+
 ## Optional AI Extraction
 
-The core library depends on `Microsoft.Extensions.AI.IChatClient`, not on a provider-specific SDK. Your host application owns the concrete provider, credentials, model choice, and optional Microsoft Agent Framework orchestration.
+Optional AI extraction enriches the deterministic Markdown graph with entities and assertions returned by an injected `Microsoft.Extensions.AI.IChatClient`. The package stays provider-neutral: it does not reference OpenAI, Azure OpenAI, Anthropic, or any other model-specific SDK. If no chat client is provided, the pipeline still runs fully locally and builds the graph from Markdown/front matter/link extraction only.
 
 ```csharp
 using ManagedCode.MarkdownLd.Kb.Pipeline;
 using Microsoft.Extensions.AI;
 
 internal static class AiGraphDemo
 {
-    private const string BaseUriText = "https://kb.example/";
     private const string ArticlePath = "content/entity-extraction.md";
 
     private const string ArticleMarkdown = """
@@ -160,28 +156,28 @@ The article mentions Markdown-LD Knowledge Bank, SPARQL, RDF, and entity extract
     private const string AskQuery = """
 PREFIX schema: <https://schema.org/>
 ASK WHERE {
-  <https://kb.example/entity-extraction/> schema:mentions ?entity .
+  ?article a schema:Article ;
+           schema:name "Entity Extraction RDF Pipeline" ;
+           schema:mentions ?entity .
   ?entity schema:name ?name .
 }
 """;
 
     public static async Task RunAsync(IChatClient chatClient)
     {
-        var pipeline = new MarkdownKnowledgePipeline(
-            new Uri(BaseUriText),
-            chatClient);
+        var pipeline = new MarkdownKnowledgePipeline(chatClient: chatClient);
 
-        var result = await pipeline.BuildAsync([
-            new MarkdownSourceDocument(ArticlePath, ArticleMarkdown),
-        ]);
+        var result = await pipeline.BuildFromMarkdownAsync(
+            ArticleMarkdown,
+            path: ArticlePath);
 
         var hasAiFacts = await result.Graph.ExecuteAskAsync(AskQuery);
         Console.WriteLine(hasAiFacts);
     }
 }
 ```
 
-The built-in chat extractor requests structured output through `GetResponseAsync<T>()` and normalizes the returned entity/assertion payload before graph construction. Tests use one local non-network `IChatClient` implementation so the full flow is covered without a live model.
+The built-in chat extractor requests structured output through `GetResponseAsync<T>()`, normalizes the returned entity/assertion payload, merges it with deterministic facts, and then builds the same in-memory RDF graph used by search and SPARQL. Tests use one local non-network `IChatClient` implementation so the full extraction-to-graph flow is covered without a live model.
 
 ## Query And Export
 
@@ -195,7 +191,8 @@ PREFIX schema: <https://schema.org/>
 SELECT ?article ?title WHERE {
   ?article a schema:Article ;
            schema:name ?title ;
-           schema:mentions <https://kb.example/id/rdf> .
+           schema:mentions ?entity .
+  ?entity schema:name "RDF" .
 }
 LIMIT 100
 """;
@@ -226,6 +223,20 @@ LIMIT 100
 
 SPARQL execution is intentionally read-only. `SELECT` and `ASK` are allowed; mutation forms such as `INSERT`, `DELETE`, `LOAD`, `CLEAR`, `DROP`, and `CREATE` are rejected before execution.
 
+## Thread Safety
+
+`KnowledgeGraph` is safe for shared in-memory read/write use through its public API. Search, read-only SPARQL, and serialization run under a read lock; `MergeAsync` snapshots a built graph and merges it under a write lock.
+
+Use this when many workers convert Markdown independently and publish their results into one graph:
+
+```csharp
+var shared = await pipeline.BuildFromMarkdownAsync(string.Empty);
+var next = await pipeline.BuildFromMarkdownAsync(markdown, path: "content/note.md");
+
+await shared.Graph.MergeAsync(next.Graph);
+var rows = await shared.Graph.SearchAsync("rdf");
+```
+
 ## Markdown Conventions
 
 ```markdown
@@ -237,25 +248,16 @@ tags:
   - markdown
   - rdf
 author:
-  - label: Ada Lovelace
-    type: schema:Person
+  - Ada Lovelace
 about:
   - Knowledge Graph
-entity_hints:
-  - label: SPARQL
-    type: schema:Thing
-    sameAs:
-      - https://www.w3.org/TR/sparql11-query/
 ---
 # Markdown-LD Knowledge Bank
 
-Use [[RDF]] and [SPARQL](https://www.w3.org/TR/sparql11-query/).
-article --mentions--> RDF
-RDF --sameas--> https://www.w3.org/RDF/
-SPARQL --relatedTo--> RDF
+Use [RDF](https://www.w3.org/RDF/) and [SPARQL](https://www.w3.org/TR/sparql11-query/).
 ```
 
-Useful predicate forms:
+Optional advanced predicate forms:
 
 - `mentions` becomes `schema:mentions`
 - `about` becomes `schema:about`
@@ -294,14 +296,15 @@ The original repository is kept as a read-only submodule under `external/lqdev-m
 ```bash
 dotnet restore MarkdownLd.Kb.slnx
 dotnet build MarkdownLd.Kb.slnx --configuration Release --no-restore
-dotnet test --solution MarkdownLd.Kb.slnx --configuration Release --no-build
+dotnet test --solution MarkdownLd.Kb.slnx --configuration Release
 dotnet format MarkdownLd.Kb.slnx --verify-no-changes
-dotnet test --solution MarkdownLd.Kb.slnx --configuration Release --no-build --coverlet --coverlet-output-format cobertura --coverlet-include '[ManagedCode.MarkdownLd.Kb]*' --results-directory TestResults/CoverletMtpFiltered
+dotnet test --solution MarkdownLd.Kb.slnx --configuration Release -- --coverage --coverage-output-format cobertura --coverage-output "$PWD/TestResults/TUnitCoverage/coverage.cobertura.xml" --coverage-settings "$PWD/CodeCoverage.runsettings"
 ```
 
 Current verification baseline:
 
-- tests: 67 passed, 0 failed
-- line coverage: 95.83%
+- tests: 69 passed, 0 failed
+- line coverage: 96.06%
+- branch coverage: 85.22%
 - target framework: .NET 10
 - package version: 0.0.1

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

@@ -164,9 +164,9 @@ Mitigations:
 ### Test commands
 
 - build: `dotnet build MarkdownLd.Kb.slnx --no-restore`
-- test: `dotnet test MarkdownLd.Kb.slnx --no-build`
+- test: `dotnet test MarkdownLd.Kb.slnx --configuration Release`
 - format: `dotnet format MarkdownLd.Kb.slnx --verify-no-changes`
-- coverage: `dotnet test --solution MarkdownLd.Kb.slnx --no-build --coverlet --coverlet-output-format cobertura --coverlet-include '[ManagedCode.MarkdownLd.Kb]*' --results-directory TestResults/CoverletMtpFiltered`
+- coverage: `dotnet test --solution MarkdownLd.Kb.slnx --configuration Release -- --coverage --coverage-output-format cobertura --coverage-output "$PWD/TestResults/TUnitCoverage/coverage.cobertura.xml" --coverage-settings "$PWD/CodeCoverage.runsettings"`
 
 ### New or changed tests
 

docs/ADR/ADR-0002-llm-extraction-ichatclient.md

@@ -112,9 +112,9 @@ Mitigations:
 ### Test commands
 
 - build: `dotnet build MarkdownLd.Kb.slnx --no-restore`
-- test: `dotnet test MarkdownLd.Kb.slnx --no-build`
+- test: `dotnet test MarkdownLd.Kb.slnx --configuration Release`
 - format: `dotnet format MarkdownLd.Kb.slnx --verify-no-changes`
-- coverage: `dotnet test --solution MarkdownLd.Kb.slnx --no-build --coverlet --coverlet-output-format cobertura --coverlet-include '[ManagedCode.MarkdownLd.Kb]*' --results-directory TestResults/CoverletMtpFiltered`
+- coverage: `dotnet test --solution MarkdownLd.Kb.slnx --configuration Release -- --coverage --coverage-output-format cobertura --coverage-output "$PWD/TestResults/TUnitCoverage/coverage.cobertura.xml" --coverage-settings "$PWD/CodeCoverage.runsettings"`
 
 ## References