MongoDbRepositoryCore 6.3.1

📖 MongoDbRepository v6.3 (.NET 10 & C# 13)

Welcome to the production runtime engine for MongoDbRepository v6.3. Fully optimized for .NET 10 and C# 13, this core framework provides an explicit, high-performance data access layer built directly on top of the official MongoDB C# Driver v3.10.0.

Version 6.3 introduces native BSON binary vectors for Atlas Vector Search, hybrid search reranking via $rankFusion, first-class .NET 10 DateOnly/TimeOnly BSON serialization, automatic Time-Series collection provisioning, and fine-grained tagged cache invalidations.

🌟 Core Pillars of Enterprise Hardening

1. Hardened Domain Immutability

Domain entity definitions enforce strict data integrity constraints. Primary identifier properties utilize native C# init accessors, completely eliminating downstream key mutations and ensuring client-side domain models align with database-level primary key immutability rules.

2. Thread-Safe Ambient Transactions

Multi-document mutations share database execution contexts across async stack continuations safely using an AsyncLocal session handle. Internal modifications are protected by a localized coordination gate (LockObject), ensuring thread-safe processing inside parent transaction contexts. Furthermore, an explicit fallback boundary timeout (maxCommitTime) prevents long-running pipeline locks from stalling connection pools.

3. Single-Roundtrip Atomic Upserts ($setOnInsert, $set, $inc)

The repository's UpsertAsync method is fully optimized to eliminate TOCTOU race conditions in a single atomic database roundtrip.

• IAuditableEntity: Sets CreatedAt on insertion via $setOnInsert without overwriting existing timestamps on updates, and $set: UpdatedAt.
• IVersionedEntity: Uses $inc: { Version: 1 } to atomically initialize versioning to 1 on insertion and increment on update while enforcing optimistic concurrency version checks.
• In-Memory Sync: Automatically updates document.CreatedAt, document.UpdatedAt, and document.Version on the caller's in-memory instance post-upsert.

4. Native BSON Binary Vector Search

ISemanticSearchRepository encodes vector embeddings as compact BsonBinaryData using BsonBinarySubType.Vector (Dense Float32). This reduces vector payload size by 4x compared to BSON double arrays and accelerates Atlas Vector Search queries.

5. Hybrid Search Reranking ($rankFusion)

Combines text search ($search) and vector search ($vectorSearch) in a single pipeline using the MongoDB 9.0 / Driver 3.10.0 $rankFusion aggregation stage for state-of-the-art Reciprocal Rank Fusion (RRF) reranking.

6. First-Class .NET 10 DateOnly & TimeOnly Support

Includes DateOnlyBsonSerializer and TimeOnlyBsonSerializer registered globally in CoreDomainMappingProfile, seamlessly mapping .NET 10 DateOnly ("yyyy-MM-dd") and TimeOnly ("HH:mm:ss.fffffff") primitives to BSON.

7. Time-Series Collection Provisioning (ITimeSeriesEntity)

Entities implementing ITimeSeriesEntity and decorated with [BsonTimeSeries(TimeField = ..., MetaField = ..., Granularity = ...)] are automatically created as native MongoDB Time-Series collections on application boot via AddAutomatedIndexes.

8. Binary SHA256 & Tagged Cache Invalidation

• Query Cache: Uses binary SHA256 hashing (CacheKeyBuilder.ComputeQueryHash) to bypass JSON stringification overhead.
• Tagged Eviction: Supports fine-grained tagged cache invalidation (InvalidateTagCache(tag)), avoiding collection-wide flushes when invalidating specific category subsets.

🚀 Quick Setup & Registration

1. Update Core Configurations (appsettings.json)

{
  "MongoDb": {
    "ConnectionString": "mongodb://username:password@localhost:27017/?replicaSet=rs0",
    "DatabaseName": "CorporateFintechDb",
    "DefaultTransactionTimeout": "00:00:05",
    "SystemCollections": {
      "Outbox": "System_Outbox",
      "AuditLogs": "System_AuditLogs"
    }
  }
}

2. Bootstrap Dependencies (Program.cs)

var builder = WebApplication.CreateBuilder(args);

// 1. Register core Mongo connections, transaction handlers, open-generic repositories, and channel eviction queues
builder.Services.AddMongoDbRepositoryCore(builder.Configuration.GetSection("MongoDb"));

// 2. Scans specific domain assemblies, provisions Time-Series collections, and attaches index verification workers
builder.Services.AddAutomatedIndexes(typeof(CreditFacilityIndexProvider).Assembly);

3. Initialize Mappings on Boot

var app = builder.Build();

// Run domain class profiles and DateOnly/TimeOnly serializers safely
app.Services.InitializeMongoMappings();

app.Run();

🛠 Core Coding Blueprints

1. Creating Time-Series & Auditable Entities

using System;
using MongoDB.Bson;
using MongoDbRepository.Attributes;
using MongoDbRepository.Core.Models;
using MongoDbRepository.Interfaces;

namespace CorporateLending.Domain.Models;

[BsonTimeSeries(TimeField = nameof(Timestamp), MetaField = nameof(SensorId))]
public class TelemetryMetric : BaseDocument<ObjectId>, ITimeSeriesEntity, IAuditableEntity
{
    public DateTime Timestamp { get; set; }
    public string SensorId { get; set; } = string.Empty;
    public double Value { get; set; }
    public DateOnly ReadingDate { get; set; }
    public TimeOnly ReadingTime { get; set; }

    public DateTime CreatedAt { get; set; }
    public DateTime? UpdatedAt { get; set; }
}

2. Hybrid AI Search ($rankFusion)

public class AIPortfolioSearchService(ISemanticSearchRepository<InvestmentProfile, string> searchRepo)
{
    public async Task<IReadOnlyList<InvestmentProfile>> SearchPortfoliosAsync(
        string userQuery, 
        ReadOnlyMemory<float> queryEmbedding, 
        CancellationToken cancellationToken)
    {
        var options = new HybridSearchOptions(
            textFieldPath: "OverviewText",
            vectorFieldPath: "Embedding",
            vectorDefinition: new VectorFieldDefinition(1536, VectorSimilarityMetric.Cosine, "portfolio_vector_idx"));

        return await searchRepo.SearchHybridAsync(userQuery, queryEmbedding, options, limit: 10, cancellationToken: cancellationToken);
    }
}

🔒 Automated Testing & Mockless Verification

[Fact]
public async Task CalculateTotalExposure_ShouldFilterSoftDeletedRecords()
{
    var fakeRepo = new InMemoryRepository<CreditFacility, ObjectId>();
    
    var activeId = ObjectId.GenerateNewId();
    var deletedId = ObjectId.GenerateNewId();

    fakeRepo.Seed([
        new CreditFacility { Id = activeId, ApprovedLimit = 5000000, IsDeleted = false },
        new CreditFacility { Id = deletedId, ApprovedLimit = 2000000, IsDeleted = true }
    ]);

    var service = new ExposureCalculator(fakeRepo);

    decimal totalExposure = await service.GetActiveExposureAsync();

    Assert.Equal(5000000, totalExposure);
}