Versioned, validated, and repeatable installation of shared Realm, Management, Billing, and future Dream Consistency system catalogs.
Database schema deployment creates tables, columns, indexes, and constraints. It does not by itself install the stable system catalog rows required by platform APIs and provisioning workflows. Dream Consistency therefore treats system catalogs as versioned deployable content with explicit package identity, compatibility, dependencies, validation, installation, and audit behavior.
DreamConsistency.SystemCatalogInstaller.Cnsl executable installs and upgrades
all shared Dream Consistency system catalogs. Each execution targets one physical database and one local transaction.
Shared catalog values such as environments, operational statuses, currencies, subscription statuses, invoice statuses, and payment statuses must have stable identities across product instances and environments. They must not be created independently by API startup code or manual SQL.
| Category | Examples | Owner | Installer / Workflow |
|---|---|---|---|
| Schema contracts | RealmTables, ManagementTables, BillingTables. | Corresponding Tables NuGet project. | DB Push or schema migration/deployment process. |
| Shared system catalogs | Environments, operational statuses, currencies, invoice/payment statuses. | DreamConsistency.*Catalogs |
DreamConsistency.SystemCatalogInstaller.Cnsl |
| Runtime / registry data | Self Realm, tenants, subscriptions, service instances, application versions. | Dedicated runtime service or provisioning flow. | Bootstrap, API, or dedicated provisioning tool. |
| Product catalog packages | Hestino allergens/defaults; Legislator legal catalogs and role sets. | Hestino or Legislator product package project. | Product Management package registry and deployment workflow. |
| Customer data imports | Menus, client records, CSV/Excel/JSON customer content. | Specific tenant/customer. | Product Management import workflow. |
Catalog libraries contain content and validation. They do not connect to databases and do not use EntityManager. The single installer contains database-specific mapping, comparison, update rules, transactions, locks, and history.
Each shared catalog library is a .NET Standard 2.1 class library and immutable NuGet distribution. It contains logical package manifests, embedded JSON catalogs, strongly typed models, a provider, package validation, and deterministic content hashing.
A catalog library can contain multiple logical packages. A logical package groups catalogs with a common lifecycle, compatibility requirement, and dependency order.
| Field | Meaning |
|---|---|
FormatVersion |
Version of the package manifest format itself. |
PackageUUID |
Stable logical package identity across all future versions. |
Name |
Machine-readable package name used by code and installation history. |
Version |
Semantic version of this logical package content. |
Database |
Realm, Management, or Billing target database guard. |
MinimumSchemaPackageVersion |
Oldest supported target database schema version. |
Dependencies |
Required packages and minimum versions that must be installed first. |
Catalogs |
Embedded JSON resources, model types, stable catalog identities, and update modes. |
Catalog JSON contains stable item UUID values and package-managed business fields. It does not contain database-local RefID values, timestamps, connection settings, or environment-specific secrets. The installer generates a new database RefID only during the first insert.
The NuGet version is an immutable distribution of one or more logical package versions. When any embedded manifest or JSON resource changes, a new logical package version and a new NuGet release are published. Existing package versions are never overwritten.
Catalog providers calculate a deterministic SHA-256 hash from the manifest and catalog resources. The hash is used for integrity checks and installation audit. It is not a password hash.
DreamConsistency.SystemCatalogInstaller.Cnsl is the only shared system catalog executable.
It references all supported Catalogs, Tables, EntityManager, and common Dream Consistency infrastructure packages.
It contains all database-specific mapping classes inside one console application.
| Operation | Purpose |
|---|---|
list-packages |
Lists embedded packages, logical versions, target database, and dependencies. |
validate |
Validates package content, dependencies, and compatibility without database writes. |
plan / dry-run |
Compares package content with database state and shows inserts, updates, unchanged rows, and conflicts. |
install |
Installs or upgrades one package together with required dependencies. |
install --all |
Installs or upgrades all supported packages for one target database. |
show-status |
Shows installed, available, current, and upgrade-available package versions and hashes. |
| Database State | Installer Action |
|---|---|
| UUID does not exist. | Insert a new row with a new database RefID and package-managed values. |
| UUID exists and all managed values match. | Unchanged; no database write. |
| UUID exists and an allowed package-managed field changed. | Update only explicitly mapped managed fields. |
| The same name exists with a different UUID. | Conflict; hard failure and rollback. |
| UUID exists but the row is soft-deleted. | Hard failure by default; no automatic recovery. |
| An item disappeared from a newer package. | No automatic deletion; requires explicit deprecation policy. |
| Database package version is newer than the installer version. | Reject downgrade. |
| The same package version has a different hash. | Integrity failure; reject installation. |
Generic reflection-based updates of every database column are not allowed. Each catalog mapping explicitly defines which fields are package-managed.
The installer validates the full dependency graph and calculates a topological installation order. A package is installed only when its required dependency versions already exist in the database or are included in the same execution plan.
RealmBootstrap.Cnsl Does |
RealmBootstrap.Cnsl Does Not Do |
|---|---|
| Validates Realm schema and Realm.Foundation presence. | Does not install or upgrade all shared system catalogs. |
| Validates that no self Realm or Core account already exists. | Does not manage Catalogs NuGet releases. |
| Creates the self Realm as REGISTERED. | Does not create Management or Billing data. |
| Creates the first active Core operator. | Does not register services or product catalog packages. |
| Uses one Realm transaction. | Does not serve as a regular catalog upgrade tool. |
| Property | Shared System Catalog | Product / Tenant Package |
|---|---|---|
| Example | Realm.Foundation, Billing.Payments. | Hestino.Serbia.Foundation, Legislator legal catalogs. |
| Target | One physical platform database. | Specific TenantApplication or product database. |
| Installer | SystemCatalogInstaller.Cnsl |
Hestino or Legislator Management deployment workflow. |
| UI | System status and read-only operational visibility. | Catalog Packages import and deployment screens. |
| Frequency | Environment provisioning and platform upgrades. | Tenant provisioning and product releases. |
Each target database must have an installation history model inside its own database boundary. Jenkins history is useful operational evidence but is not the authoritative database source of truth.
| Field | Purpose |
|---|---|
| InstallationID | GUID primary key of one installation attempt or result. |
| PackageUUID / PackageName | Stable logical package identity. |
| PackageVersion | Applied logical package version. |
| ContentHash | Proof of the exact embedded content. |
| InstallerVersion | Version of the executable or image. |
| AppliedTimestampUtc | UTC timestamp of the successful commit. |
| AppliedByServiceUUID | Installer service identity. |
| Status / FailureCode | Machine-readable outcome without secrets. |
Catalog content is not secret, but its integrity is protected by versioning and content hash. Database credentials and Vault material remain outside source code, package content, CLI arguments, images, and logs.
| Privilege | Default Policy |
|---|---|
| SELECT on schema, version, catalog, and history tables | Required |
| INSERT / UPDATE on target catalog tables | Required |
| INSERT on installation history | Required |
| Transaction and lock operations | Required |
| DELETE / hard delete | Not granted by default |
| ALTER / DROP / CREATE TABLE | Not granted |
| Access to unrelated databases | Not granted |
| Decision | Status |
|---|---|
| One SystemCatalogInstaller executable. | Locked |
| No three additional database-specific installer NuGet projects. | Locked |
| Catalog content remains in separate .NET Standard 2.1 libraries. | Locked |
| Jenkins pulls a versioned installer release or image. | Locked |
| One target database per transaction. | Locked |
| RealmBootstrap is not the regular system catalog upgrade tool. | Locked |
| Hestino and Legislator product packages remain in product Management workflows. | Locked |
Production never blindly uses an unrestricted latest tag. |
Locked |
| Date | Change | Author |
|---|---|---|
| 2026-08-01 | Initial system catalog architecture and single-installer decision documented. | Branko |