Cohesive.Adapters.Cosmos 0.1.0-alpha.121

Cohesive.Adapters.Cosmos

Cohesive.Adapters.Cosmos provides Azure Cosmos DB interpretations for Cohesive entity storage, Relations, materialization sources, Process Transition receipts, domain-event inboxes, outbox records, and vector storage.

Install

dotnet add package Cohesive.Adapters.Cosmos

Collect Cosmos operation telemetry

CosmosClientFactory enables the Cosmos SDK's native Azure.Cosmos.Operation activities by default. Query text remains suppressed, telemetry upload to Microsoft remains disabled, and the SDK's slow-operation diagnostic thresholds are unchanged. Register the published source name with the host's existing OpenTelemetry tracer provider:

services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource(CosmosClientFactory.OperationActivitySourceName));

The resulting operation activities are children of the current ASP.NET request activity and provide database-client duration for direct comparison with API request duration. Cosmos attributes and slow-request diagnostics can also expose request charge, status/substatus, retry or throttling evidence, response size, and the SDK's internal request timeline, subject to the SDK version and exporter.

Callers can replace the configuration with the SDK type directly. CosmosClientFactory snapshots the public configuration before caching, so an existing client cannot be mutated indirectly and clients with incompatible telemetry settings are not reused:

var client = CosmosClientFactory.Shared.CreateCosmosClient(new CosmosClientFactoryOptions
{
    Endpoint = endpoint,
    TelemetryOptions = new CosmosClientTelemetryOptions
    {
        DisableDistributedTracing = false,
        DisableSendingMetricsToService = true,
        QueryTextMode = QueryTextMode.None,
        CosmosThresholdOptions = new CosmosThresholdOptions
        {
            PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500),
            NonPointOperationLatencyThreshold = TimeSpan.FromSeconds(2)
        }
    }
});

The current stable Cosmos SDK exposes operation/network meter constants in generated documentation but keeps their enablement and dimension options internal. Cohesive does not use reflection or a preview SDK to bypass that boundary; native client metrics remain deferred until Microsoft publishes a stable public configuration API.

Build a safe Cosmos query

The standalone builder validates property paths and operators, creates deterministic parameters, and never accepts raw SQL fragments:

var id = CosmosSqlExpression.Property("c", FieldPath.FromField("Id"));
var status = CosmosSqlExpression.Property("c", FieldPath.FromField("Status"));

var template = new CosmosSqlBuilder("c")
    .Select(id, "id")
    .Select(status, "status")
    .Where(CosmosSqlExpression.Binary(
        CosmosSqlBinaryOperator.Equal,
        status,
        CosmosSqlExpression.RuntimeParameter("status")))
    .OrderBy(id)
    .OffsetLimit(offset: 0, limit: 100)
    .BuildTemplate();

var statement = template.Bind(new Dictionary<string, object?>
{
    ["status"] = "open"
});

Use the canonical compiler when the query must retain Relation semantics, plan affinity, capability evidence, and provenance. Placement and the Cosmos storage binding remain explicit persisted interpretations of that plan.

Implemented interpretations

• Parameterized Cosmos SQL compilation for the supported canonical Relation/query slice.
• Bounded Cosmos SDK source acquisition and materialization change sources.
• Entity repository and embedded aggregate storage realization.
• Atomic Process Transition execution with exact partition-local replay receipts.
• A durable, target-deduplicating canonical domain-event inbox.
• Safe standalone Cosmos SQL construction.
• Outbox persistence and vector storage integrations.

Important boundaries

Cosmos JOIN expands arrays within one document; it is not a cross-document join. Cross-container relationships use bounded reads and local correlation when the physical plan can preserve the requested semantics.

Process Transition receipt lookup requires exact point-read partition placement. The adapter fails with structured capability evidence when that placement cannot be resolved and never substitutes a cross-partition scan for atomic subject authority.

Missing values, null, ordering, paging, aggregation, partition scope, and continuation behavior are represented explicitly. Unsupported combinations fail with structured diagnostics rather than inheriting SDK coercions.

Continue

• Internals contains Process Transition receipts, the domain-event inbox, full SQL builder, canonical compilation, semantic envelope, acquisition, materialization, query authority, and storage realization details.
• Relations execution and adapters explains composed PostgreSQL/Cosmos reads.
• Relations capability reference records the generated profile.
• Cohesive.Storage owns the provider-neutral storage contracts.

Experimental atomic storage commits

Create CosmosStorageCommitExecutor with CreateAsync(client, databaseId, containerId, target). It verifies a single observed writable region, /partitionKey container partitioning and disabled TTL, then realizes conditional writes plus a receipt in one transactional batch. Other targets or partitions are rejected; native limits include the receipt. The conservative serialized document budget is 1 MiB. It owns a dedicated document namespace and uses a lossless stream codec independent of the client's serializer. Recreate the executor after topology or consistency changes.

Query-dependent commits require the explicit all-writers guard protocol and a Strong account/read profile. The local vNext emulator's Eventual profile cannot qualify these reads; it still exercises native batch, ETag and exact receipt behavior. Run those integration checks by setting COSMOS_STORAGE_COMMIT_CONNECTION_STRING and filtering CosmosStorageCommitTests. See the commit decision and deferred adoption work.

For commit profiles below Strong, an item conflict or token mismatch followed by an invisible receipt returns Unknown, including Session profiles after restart. Reconcile the exact intent when visibility catches up; do not treat this as a definitive precondition failure. executor.Validate(intent) measures native documents and the receipt before any I/O, using the same encoding and byte budget as execution.