Product-neutral Billing financial domain and persistence library for financial transactions, occurrences, invoices, payments, allocations, reversals, refunds, and settlement calculations.
DreamConsistency.Billing.Core is an independently versioned, reusable .NET library that
centralizes Billing financial domain behavior and database transaction execution. It uses
DreamConsistency.EntityManager and the generated DreamConsistency.BillingTables
entities to operate against the approved BillingDB schema.
| Property | Current Decision |
|---|---|
| Package ID | DreamConsistency.Billing.Core |
| First NuGet Release | 1.0.0 — 21 October 2026 |
| Latest Documented Release | 1.0.0 |
| Target Framework | .NET 10 / net10.0 |
| NuGet Feed | https://nuget.dreamconsistency.com/v3/index.json |
| Package Hosting | BaGetter |
| Release Pipeline | DreamConsistency.Billing.Core - NuGet Release |
| Jenkins Folder | DreamConsistency - Packages |
| Source Repository | git@bitbucket.org:skyrocket_novisad/dreamconsistency.billing.core.git |
| Release Branch | master |
| Versioning | Semantic Versioning: MAJOR.MINOR.PATCH |
| Visibility | Internal Dream Consistency package. |
The package provides one shared implementation of Billing financial persistence and invariants, instead of duplicating transaction and financial domain logic between an API host and background workers.
| Area | Responsibility |
|---|---|
| Transaction Execution | BillingTransactionExecutor controls transaction lifetime, commit/rollback, disposal, and bounded retries of classified identity conflicts. |
| Billing Customers | BillingCustomer source relationships and related financial identity checks. |
| Financial Occurrences | Financial occurrence identity, persistence, and idempotency. |
| Invoices | Draft creation, issuance, immutable financial snapshots, and applicable lifecycle validations. |
| Payments | Payment handling, capacity calculations, and financial validations. |
| Allocations & Reversals | Allocation state, source identities, reversals, and related integrity invariants. |
| Refunds | Refund registration, transitions, source identities, and payment-capacity consistency. |
| Credit Notes & Settlement | Credit-note-related settlement and derived invoice/payment settlement reads. |
| Catalogs & Errors | Catalog resolution, financial rules, row builders, and database error classification/sanitization. |
Core is responsible for shared domain and persistence behavior. The host is responsible for application composition, runtime credentials, authentication, API endpoints, jobs, and scheduling. The diagram describes intended integration boundaries, not a claim that Api and Worker have already completed their package migrations.
| Rule | Meaning |
|---|---|
| Single Transaction Owner | BillingTransactionExecutor owns each attempt and its transaction lifetime. |
| Fresh Attempt Context | Each retry uses a new context; transactions are not reused across attempts. |
| Commit / Rollback | One verified commit on success; rollback before disposal when an attempt fails. |
| Bounded Retry | Retry only specifically classified source-identity races, not arbitrary failures. |
| Persistence Framework | DreamConsistency.EntityManager only; no EF Core or DbContext. |
| Connection Ownership | BillingDB connection information is supplied by the consuming host as a runtime secret. |
| Financial Integrity | Preserve unique financial identities, authoritative source keys, foreign keys, and invoice provenance. |
| Contract | Approved Version |
|---|---|
| BillingDB SchemaVersion / ContractVersion | 1.3.0 |
DreamConsistency.BillingTables | 1.3.0 |
DreamConsistency.BillingCatalogs | 1.2.0 |
| Physical Schema Authority | Product Owner-approved BillingDB 1.3.0 MySQL Workbench model |
| Validation Baseline | 27 tables, 34 foreign keys; 41/41 catalog identities verified for the test environment |
Version 1.0.0 validates the BillingDB 1.3.0 physical contract, including financial
authority/source uniqueness and InitiatingOperation_RefID_UNIQUE invoice provenance.
The three installed standard columns — IsDeleted, CreationTimestamp,
and ModificationTimestamp — are handled according to the approved installation conventions;
their position must not be guessed from the generated C# model's declaration order.
| Package | Approved Direct Version | Purpose |
|---|---|---|
DreamConsistency.EntityManager | 1.0.3 | Persistence and transaction infrastructure. |
DreamConsistency.BillingTables | 1.3.0 | Generated BillingDB entity definitions. |
DreamConsistency.BillingCatalogs | 1.2.0 | Versioned Billing system catalogs. |
DreamConsistency.Extensions | 1.1.0 | Shared backend utilities. |
System.Security.Cryptography.Pkcs | 10.0.13 | Explicit security version pin. |
MySqlConnector 2.6.2 is resolved transitively through EntityManager.
Dependency upgrades require review because consuming projects inherit the package dependency graph.
Configure the internal package source in the consuming solution's NuGet.config:
Install the first stable release:
Or reference it directly:
Consumers integrate the public DreamConsistency.Billing.Core.* namespaces and
provide the necessary runtime transaction and database dependencies through their composition layer.
Core itself does not create HTTP endpoints, register background jobs, read application settings,
or determine tenant-to-database routing.
| Owned by Billing.Core | Not Owned by Billing.Core |
|---|---|
| Shared financial domain services and invariants | HTTP controllers, Swagger or API hosting |
| Transaction execution and database error classification | Host dependency-injection composition or ServiceAuth |
| Financial occurrences, invoices and their lifecycle rules | Commercial subscription/Realm billability decisions |
| Payment, allocation, reversal and refund rules | BillingRun scheduling, registration, execution, leasing or recovery |
| Derived settlement and payment-capacity logic | Product-specific endpoints, deployment or operational monitoring |
| BillingDB-oriented financial persistence | Database migrations or schema ownership |
| Catalog-backed financial validations | Host credentials, secret storage or environment configuration |
Version 1.0.0 passed Product Owner-executed real MariaDB regression on 21 October 2026, accepted by Hestino Master Control. This is verification of the initial release baseline, not an automatic guarantee for subsequent commits or future versions.
| Test Group | Passed | Failed | Skipped |
|---|---|---|---|
| DB-independent tests | 1,589 | 0 | 0 |
| MariaDB integration tests | 242 | 0 | 0 |
| Full Release regression | 1,831 | 0 | 0 |
| Corrected physical-contract assertions (subset) | 5 | 0 | 0 |
Database integration tests use [BillingIntegrationFact] and are enabled only
when BILLING_INTEGRATION_DB_CONNECTION targets an explicitly approved disposable
BillingDB. Without it, the 242 integration tests are skipped by design.
Publishing is performed only by the Product Owner through the approved Jenkins pipeline.
Manual local dotnet nuget push is not the accepted release path.
| Setting | Value |
|---|---|
| Jenkins Folder | DreamConsistency - Packages |
| Job Name | DreamConsistency.Billing.Core - NuGet Release |
| Repository | git@bitbucket.org:skyrocket_novisad/dreamconsistency.billing.core.git |
| Branch | master |
| Jenkinsfile | Jenkinsfile |
| Build Agent | mcr.microsoft.com/dotnet/sdk:10.0 |
| Feed | https://nuget.dreamconsistency.com/v3/index.json |
| BaGetter Credential | dreamconsistency-nuget-api-key |
| Version Parameter | PACKAGE_VERSION (must match project version when publishing) |
| Publish Parameter | PUBLISH_PACKAGE (explicit opt-in) |
| Initial Publication | Build #4 — 21 October 2026 |
| Initial Publication Commit | 93f54bbcaf829983b0f9b28f1564781240d78c2a |
| Version Type | Example | Meaning |
|---|---|---|
| Patch | 1.0.1 | Backward-compatible fixes without changing the public contract. |
| Minor | 1.1.0 | Backward-compatible new functionality. |
| Major | 2.0.0 | Breaking public contract changes. |
BillingDB schema, BillingTables, BillingCatalogs and Billing.Core NuGet versions are separate contracts and must not be assumed to share identical version numbers.
| Risk / Note | Decision |
|---|---|
| Financial identity regressions | Preserve source/authority uniqueness, invoice provenance, foreign keys, idempotency and real DB integration tests. |
| Schema drift | Reconcile changes with the approved Workbench physical contract; generated model order alone is not physical DDL authority. |
| Unapproved database access | Use only Product Owner-confirmed disposable integration targets, never DEV/LIVE. |
| Dependency and vulnerability risk | Review transitive dependencies and security advisories before each release. |
| Duplicate package publication | Published version 1.0.0 must not be replaced; increment SemVer for new changes. |
| Cross-product coupling | Keep Hestino, Legislator, Realm commercial policy and host operations out of Core. |
| Release vs. deployment | NuGet publication does not imply Api/Worker migration or DEV/LIVE deployment. |
Detailed developer guidance is maintained in the Core repository README.md,
docs/architecture/core-ownership.md, and the public-contract tests.
This Wiki page records stable package ownership, dependency and database contracts,
published release details, operational rules, and the approved Jenkins publication path.
| Date | Change | Author |
|---|---|---|
| 2026-10-21 | Published DreamConsistency.Billing.Core 1.0.0 to the internal BaGetter feed through Jenkins Build #4. | Dream Consistency |
| 2026-10-21 | Accepted BillingDB 1.3.0 physical-contract reconciliation and completed 1,831/1,831 Release tests, including 242/242 MariaDB integration tests. | Dream Consistency |
| 2026-10-20 | Prepared the independent Billing.Core repository, public package contract and Jenkins validation foundation. | Dream Consistency |