feat(recommendations): implement contextual recommendation engine (#76)

Resolves #75

### Description
This pull request implements a smart, Native AOT-compliant contextual recommendation engine for the desktop dashboard to drive user retention and cross-book monetization.

### Key Changes
1. **Application Layer**:
   - Declared `IUserReadingStateStore` interface to decouple reading state discovery.
   - Added `IVectorSearchStore.SearchGlobalExcludeAsync(...)` to abstract semantic similarity searches with exclusions.
   - Defined `GetContextualRecommendationsQuery` and response DTOs (`ContextualRecommendationResponse`, `RecommendationDto`).
2. **Infrastructure Layer**:
   - Implemented `UserReadingStateStore` using EF Core with DbContext pooling.
   - Implemented `SearchGlobalExcludeAsync` in `VectorSearchStore` to construct gRPC Qdrant filters (excluding the active book ID) and fetch `bookTitle` and `chapterTitle` from point payloads.
   - Implemented `GetContextualRecommendationsQueryHandler` using clean abstractions.
3. **Web & Serialization Layer**:
   - Mapped `GET /api/recommendations` endpoint.
   - Registered types in `AppJsonContext.cs` for AOT-compliant JSON serialization.
4. **Verification**:
   - Added complete unit test coverage in `GetContextualRecommendationsQueryTests.cs`. All 30 unit tests pass.

---------

Co-authored-by: Marek Jasiński <jasins.marek@gmail.com>
Reviewed-on: #76
Co-authored-by: Antigravity <antigravity@google.com>
Co-committed-by: Antigravity <antigravity@google.com>

tests/NexusReader.Application.Tests/Queries/GetContextualRecommendationsQueryTests.cs

@@ -0,0 +1,132 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using FluentAssertions;
+using Microsoft.Extensions.Logging;
+using Moq;
+using NexusReader.Application.Abstractions.Persistence;
+using NexusReader.Application.Queries.Recommendations;
+using NexusReader.Infrastructure.Queries;
+using Xunit;
+
+namespace NexusReader.Application.Tests.Queries;
+
+public class GetContextualRecommendationsQueryTests
+{
+    private readonly Mock<IUserReadingStateStore> _readingStateStoreMock;
+    private readonly Mock<IUserLibraryStore> _libraryStoreMock;
+    private readonly Mock<IVectorSearchStore> _vectorSearchStoreMock;
+    private readonly Mock<ILogger<GetContextualRecommendationsQueryHandler>> _loggerMock;
+    private readonly GetContextualRecommendationsQueryHandler _handler;
+
+    public GetContextualRecommendationsQueryTests()
+    {
+        _readingStateStoreMock = new Mock<IUserReadingStateStore>();
+        _libraryStoreMock = new Mock<IUserLibraryStore>();
+        _vectorSearchStoreMock = new Mock<IVectorSearchStore>();
+        _loggerMock = new Mock<ILogger<GetContextualRecommendationsQueryHandler>>();
+
+        _handler = new GetContextualRecommendationsQueryHandler(
+            _readingStateStoreMock.Object,
+            _libraryStoreMock.Object,
+            _vectorSearchStoreMock.Object,
+            _loggerMock.Object
+        );
+    }
+
+    [Fact]
+    public async Task Handle_WithNoActiveReadingState_ReturnsEmptyRecommendations()
+    {
+        // Arrange
+        var userId = "user-123";
+        _readingStateStoreMock.Setup(s => s.GetActiveReadingStateAsync(userId, It.IsAny<CancellationToken>()))
+            .ReturnsAsync((null, null, null));
+
+        var query = new GetContextualRecommendationsQuery(userId);
+
+        // Act
+        var result = await _handler.Handle(query, CancellationToken.None);
+
+        // Assert
+        result.IsSuccess.Should().BeTrue();
+        result.Value.Recommendations.Should().BeEmpty();
+    }
+
+    [Fact]
+    public async Task Handle_WithActiveReadingState_PerformsSimilaritySearchAndReturnsRecommendations()
+    {
+        // Arrange
+        var userId = "user-123";
+        var activeEbookId = Guid.NewGuid();
+        var activeChapterId = "chapter-1";
+        var tenantId = "tenant-abc";
+        var chapterContent = "Active chapter content description";
+
+        _readingStateStoreMock.Setup(s => s.GetActiveReadingStateAsync(userId, It.IsAny<CancellationToken>()))
+            .ReturnsAsync((activeEbookId, activeChapterId, tenantId));
+
+        _readingStateStoreMock.Setup(s => s.GetChapterContentAsync(activeChapterId, It.IsAny<CancellationToken>()))
+            .ReturnsAsync(chapterContent);
+
+        // Mock vector search results using clean VectorChunk list
+        var targetEbookId1 = Guid.NewGuid();
+        var targetEbookId2 = Guid.NewGuid();
+
+        var mockChunks = new List<VectorChunk>
+        {
+            new VectorChunk(
+                Content: "Result pattern details",
+                EbookId: targetEbookId1.ToString(),
+                Score: 0.88,
+                MetadataJson: "",
+                BookTitle: "Clean Architecture deep dive",
+                ChapterTitle: "Chapter 3: Result Pattern"
+            ),
+            new VectorChunk(
+                Content: "Performance optimizations",
+                EbookId: targetEbookId2.ToString(),
+                Score: 0.72,
+                MetadataJson: "",
+                BookTitle: "Advanced C# 14",
+                ChapterTitle: "Chapter 5: Span and Performance"
+            )
+        };
+
+        _vectorSearchStoreMock.Setup(v => v.SearchGlobalExcludeAsync(
+                chapterContent,
+                tenantId,
+                activeEbookId,
+                2,
+                It.IsAny<CancellationToken>()))
+            .ReturnsAsync(mockChunks);
+
+        // User owns the second book but not the first one
+        _libraryStoreMock.Setup(l => l.GetOwnedBookIdsAsync(userId, It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new List<Guid> { targetEbookId2 });
+
+        var query = new GetContextualRecommendationsQuery(userId);
+
+        // Act
+        var result = await _handler.Handle(query, CancellationToken.None);
+
+        // Assert
+        result.IsSuccess.Should().BeTrue();
+        result.Value.Recommendations.Should().HaveCount(2);
+
+        var firstRec = result.Value.Recommendations.First();
+        firstRec.BookTitle.Should().Be("Clean Architecture deep dive");
+        firstRec.ChapterTitle.Should().Be("Chapter 3: Result Pattern");
+        firstRec.MatchPercentage.Should().Be(88);
+        firstRec.IsPremiumUpsell.Should().BeTrue(); // User does not own book 1
+        firstRec.TargetBookId.Should().Be(targetEbookId1);
+
+        var secondRec = result.Value.Recommendations.Last();
+        secondRec.BookTitle.Should().Be("Advanced C# 14");
+        secondRec.ChapterTitle.Should().Be("Chapter 5: Span and Performance");
+        secondRec.MatchPercentage.Should().Be(72);
+        secondRec.IsPremiumUpsell.Should().BeFalse(); // User owns book 2
+        secondRec.TargetBookId.Should().Be(targetEbookId2);
+    }
+}

tests/NexusReader.Application.Tests/Services/PaywallParserTests.cs

@@ -0,0 +1,81 @@
+using System;
+using FluentAssertions;
+using NexusReader.UI.Shared.Services;
+using Xunit;
+
+namespace NexusReader.Application.Tests.Services;
+
+public class PaywallParserTests
+{
+    [Fact]
+    public void TryParsePaywallTrigger_WithValidSimpleToken_ReturnsTrueAndCorrectValues()
+    {
+        // Arrange
+        var guid = Guid.NewGuid();
+        var rawText = $"Teaser sentence. [PAYWALL_TRIGGER:{guid}:Clean Book Title:45:82]";
+
+        // Act
+        var result = PaywallParser.TryParsePaywallTrigger(
+            rawText,
+            out var teaser,
+            out var bookId,
+            out var title,
+            out var localScore,
+            out var globalScore);
+
+        // Assert
+        result.Should().BeTrue();
+        teaser.Should().Be("Teaser sentence.");
+        bookId.Should().Be(guid);
+        title.Should().Be("Clean Book Title");
+        localScore.Should().Be(45);
+        globalScore.Should().Be(82);
+    }
+
+    [Fact]
+    public void TryParsePaywallTrigger_WithColonsInBookTitle_ReturnsTrueAndCorrectValues()
+    {
+        // Arrange
+        var guid = Guid.NewGuid();
+        var rawText = $"Teaser text. [PAYWALL_TRIGGER:{guid}:Architektura: .NET 10 i C# 14:15:99]";
+
+        // Act
+        var result = PaywallParser.TryParsePaywallTrigger(
+            rawText,
+            out var teaser,
+            out var bookId,
+            out var title,
+            out var localScore,
+            out var globalScore);
+
+        // Assert
+        result.Should().BeTrue();
+        teaser.Should().Be("Teaser text.");
+        bookId.Should().Be(guid);
+        title.Should().Be("Architektura: .NET 10 i C# 14");
+        localScore.Should().Be(15);
+        globalScore.Should().Be(99);
+    }
+
+    [Theory]
+    [InlineData("")]
+    [InlineData("Just plain text with no trigger token.")]
+    [InlineData("Plain text [PAYWALL_TRIGGER:invalid-guid:Title:50:80]")]
+    [InlineData("Plain text [PAYWALL_TRIGGER:00000000-0000-0000-0000-000000000000:Title:50:invalid]")]
+    [InlineData("Plain text [PAYWALL_TRIGGER:00000000-0000-0000-0000-000000000000:Title:invalid:80]")]
+    [InlineData("Plain text [PAYWALL_TRIGGER:00000000-0000-0000-0000-000000000000:Title]")]
+    public void TryParsePaywallTrigger_WithInvalidInputs_ReturnsFalse(string rawText)
+    {
+        // Act
+        var result = PaywallParser.TryParsePaywallTrigger(
+            rawText,
+            out var teaser,
+            out var bookId,
+            out var title,
+            out var localScore,
+            out var globalScore);
+
+        // Assert
+        result.Should().BeFalse();
+    }
+}