RevenueFlow.Stores.Abstractions
0.1.0-alpha.7.2
dotnet add package RevenueFlow.Stores.Abstractions --version 0.1.0-alpha.7.2
NuGet\Install-Package RevenueFlow.Stores.Abstractions -Version 0.1.0-alpha.7.2
<PackageReference Include="RevenueFlow.Stores.Abstractions" Version="0.1.0-alpha.7.2" />
<PackageVersion Include="RevenueFlow.Stores.Abstractions" Version="0.1.0-alpha.7.2" />
<PackageReference Include="RevenueFlow.Stores.Abstractions" />
paket add RevenueFlow.Stores.Abstractions --version 0.1.0-alpha.7.2
#r "nuget: RevenueFlow.Stores.Abstractions, 0.1.0-alpha.7.2"
#:package RevenueFlow.Stores.Abstractions@0.1.0-alpha.7.2
#addin nuget:?package=RevenueFlow.Stores.Abstractions&version=0.1.0-alpha.7.2&prerelease
#tool nuget:?package=RevenueFlow.Stores.Abstractions&version=0.1.0-alpha.7.2&prerelease
RevenueFlow.Stores.Abstractions
IRevenueDocumentStore is the storage boundary for one atomic business command. It accepts immutable data, never an external-I/O callback or a replayable transaction delegate.
var request = JsonSerializer.SerializeToElement(new
{
commandType = "grant-resources",
version = 1,
userId,
resource = "credits",
quantity = 10
});
var fingerprint = StoreRequestFingerprint.Compute(request);
var batch = new AtomicCommitBatch(
scope,
commandId,
fingerprint,
JsonSerializer.SerializeToElement(new { grantId }),
[new AtomicDocumentWrite("grant", grantId, 0, request, [economicPurchaseKey])]);
var result = await store.CommitAsync(batch, cancellationToken);
The sample is storage composition, not a complete fulfillment implementation. A business service must include every required order, subscription, entitlement, ledger, economic deduplication, history and outbox write in the same batch. It must enforce its domain invariants and include all semantic request inputs in the fingerprint. HTTP endpoints and provider requests belong to the application or provider adapter.
Contract
- Document identity is the ordinal
Kindplus nonempty UUID, globally unique across scopes. Reads require the exact tenant/project/environment/app scope and returnnulloutside the owning scope. Scope components must never be flattened with ambiguous delimiters. ExpectedRevision = 0means create only. Incrementable positive revisions mean replace only at that exact current revision and scope; successful writes increment the revision by one. Write construction rejectslong.MaxValuebefore a routed mutation can acquire admission. Stored terminal revisions remain valid for import and reading; updatinglong.MaxValue - 1to the terminal revision and replaying its original receipt remain supported. Missing, stale and cross-scope replacements conflict. Revisions never wrap.- Unique keys are ordinal and unique within the exact scope plus record kind. A replacement supplies the complete new key set. The batch may release or transfer keys atomically; partial transfer is forbidden. A permanent economic deduplication record should be create-only and retain its key.
- Command IDs are ordinal and unique in the exact scope. Prefix them by command type when independent callers share a scope. The receipt stores a lowercase 64-character SHA-256 fingerprint and original JSON result.
- If a receipt already exists, matching fingerprints return
Replayedwith its original result before checking the incoming writes. Changed fingerprints returnCommandConflict. A failed revision or uniqueness check returns its typed conflict with no writes or receipt from that attempt. - A successful receipt and every document write are one atomic commit. A receipt-only batch is permitted. Duplicate document identities within a batch are invalid.
- Documents, writes, results and returned snapshots are immutable and independent of caller-owned JSON documents or collections.
The built-in fingerprint helper recursively sorts object properties using ordinal order. Whitespace and object-property order are insignificant; array order, property-name case, and numeric JSON spellings remain significant. It is a RevenueFlow convention, not an RFC 8785 implementation. Serialize typed commands consistently, include command type and semantic version, and retain that version's encoding for retries. The store validates fingerprint format; it cannot verify that callers hashed every semantic input.
Payloads, command results and fingerprint inputs must be JSON objects up to 65,536 UTF-8 bytes and 32 nested containers. Duplicate property names are rejected at every level. Batches allow at most 256 writes, with at most 32 unique keys per write. Identifiers use Core's nonblank, 256-character, no-control-character rules and preserve exact text.
Production adapter obligations
Adapters must implement the same scoped constraints, revisions, receipt behavior and all-or-nothing effects using one database transaction. Independent repositories that commit separately do not satisfy this contract. An Entity Framework implementation must use one enlisted context/transaction; MongoDB requires transaction-capable topology. External provider calls cannot join this atomic boundary.
A returned conflict is definite and commits no changes from that attempt. An exception, timeout or cancellation after submission may leave a durable commit outcome unknown. Recover by reading the scoped command receipt, or retry the identical command ID and fingerprint. Never infer rollback from a missing response, mint a new command ID after an uncertain response, or call a provider again merely because the local response was lost.
Retain receipts through the documented command replay window. Economic purchase IDs and event IDs require independently sufficient retention, often permanent retention; expiring a receipt must not make an old purchase grant again. Event payloads should contain stable event IDs and aggregate sequence/version data. Consumer acknowledgement, provider delivery and history export are separate from the local commit. The store does not promise global exactly-once delivery.
Use RevenueFlow.StoreContracts.AtomicDocumentStoreContractTests for shared behavioral checks. Durable adapters additionally require restart recovery, lost commit responses, database constraint races, cancellation during submission, process failure, isolation and topology tests. Passing the in-memory checks is insufficient evidence of durability.
IRevenueDocumentQueryStore adds full-scope unique-key lookup and bounded live pages in Guid.CompareTo order. Concurrent inserts before a cursor require a later scan from the beginning. RevenueFlow.Events implements revision-fenced leases and recoverable per-consumer dispatch on top of atomic batches; the generic store itself does not execute handlers.
IRevenueDocumentMetadataQueryStore is an independently optional role for an owned root Metadata JSON object. It accepts the existing RevenueUserQuery contract and preserves its exact typed/ordinal semantics before returned-page pagination, including arbitrary JSON numeric precision and missing versus null. PostgreSQL, MongoDB and verified EF/SQLite supply native predicates over revisioned derived tokens; in-memory filters its scoped partition. Custom stores may omit the capability, and callers retain exact scoped paging. Native adapters provide explicit metadata backfill and selected-path equality index setup; no request creates indexes or backfills data. The original payload remains authoritative, and projection/import maintenance shares the document transaction.
RevenueJson.SerializeObject serializes storage data without HTML-oriented escape expansion and still enforces complete document size/depth. It is not an HTML rendering API. Deletion/tombstones, automatic retention and indexed due-work discovery remain planned.
Independent capabilities
IRevenueDocumentSnapshotStore is an optional read-only capability. Its callback executes once with a reader fixed to the complete scope and one consistent engine view across document/unique-key reads and reference-query pages. It never supplies writes or retries a callback. Keep the callback bounded, sequential and free of external I/O; its reader expires when it returns. RevenueDocumentGuidReference supports exact root UserId, OriginalUserId and AccessUserId equality. Native adapters maintain derived reference indexes atomically with document writes; references aid discovery and never authorize access. Custom stores can omit this capability; features must preserve a documented safe compatibility protocol or fail explicitly.
The Analytics namespace adds typed immutable fact ingestion, database-native reporting/drilldown,
observed progress, source/fact manifests and reconciled generation CAS. Adapters own their physical
schema and may implement any supported role. WriteManyAsync accepts 1–100 same-scope/generation
events, bounded to 256 resource facts and 256 team facts per event and 1,000 combined facts per microbatch. The default preserves
per-event durability; concrete adapters document any stronger whole-microbatch transaction.
Replays preserve first financial recorded time and reject changed immutable semantics. A cursor or
largest observed timestamp is never a completeness watermark.
IRevenueAnalyticsAdmissionStore coordinates engines without atomic unique admission or generation
CAS. Reserve immutable semantics before external insertion, complete only after durable acceptance,
and prevent sealing while reservations remain pending. Namespace every operation by full scope,
stable destination and generation. A coordinator must never manufacture analytical durability.
Commerce.IRevenueCurrentSubscriptionQueryStore reads current operational subscription counts.
It is independent of asynchronous analytical facts; historical subscription metrics belong to the
analytical query role. The composition package describes actual implemented interfaces and permits
separate operational, analytical and inbound queue selections without choosing a concrete engine.
IRevenueAnalyticsTotalsQueryStore is an independently optional native aggregate capability. It
returns Core's RevenueAnalyticsTotals without high-cardinality customer/product/origin/cohort lists.
It has no fallback through the bounded detailed-report interface. Adapters advertise support only
by implementing it; Core's totals reader can then be backed by the selected native engine.
IRevenueTeamAnalyticsQueryStore aggregates immutable team money, resource and actor facts. Its
group bound fails instead of truncating totals; current account/subscription authority remains
operational. RevenueAnalyticsFactBatch.Teams is optional and participates in existing immutable
identity admission, manifests and generation lifecycle. IRevenueAnalyticsTeamFactSource lets a
feature contribute its immutable snapshots to the general projector without an implementation
dependency. See native team analytics.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- RevenueFlow.Core (>= 0.1.0-alpha.7.2)
- RevenueFlow.Users.Abstractions (>= 0.1.0-alpha.7.2)
NuGet packages (20)
Showing the top 5 NuGet packages that depend on RevenueFlow.Stores.Abstractions:
| Package | Downloads |
|---|---|
|
RevenueFlow.Events.Abstractions
Scoped business-event history and atomic outbox preparation contracts. |
|
|
RevenueFlow.Commerce.Abstractions
Provider-neutral scoped commerce building blocks for .NET. |
|
|
RevenueFlow.Commerce
Provider-neutral scoped commerce building blocks for .NET. |
|
|
RevenueFlow.Metering.Abstractions
Provider-neutral scoped commerce building blocks for .NET. |
|
|
RevenueFlow.Catalog
Catalog snapshot behavior and a development-only immutable catalog registry for RevenueFlow. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.1.0-alpha.7.2 | 216 | 11/10/2026 |