Why It's Important to Track Platform Kernel Versions

What is the "platform core" and why versions are critical

By "core" we mean domains where mistakes are not forgiven: wallet and ledger, bets/calculation of rounds, cash desk (deposits/payments), identification (KYC/AML/RG), contracts with game providers and billing/reporting.

Any update here affects money, regulation, trust. Therefore, kernel versions are not a "package number. json," and a change and responsibility management tool.

---

Why track versions

1. Money risk management. We clearly know which code paid for which round/payment - removes disputes and speeds up the analysis of incidents.

2. Interoperability of integrations. Game/payment providers are tied to contracts. Version = guarantee that the fields, statuses, and business rules are the same.

3. Compliance and audit. The regulator requires reproducibility: "what build, what scheme, what control." The version is the anchor of the evidence base.

4. Fast releases without downtime. Versioning allows you to release compatible changes and roll canary.

5. Incident-management. Rollback/roll-forward are simple when there are tagged artifacts, migrations, and a compatibility matrix.

6. Transparency for product teams. When the "contract is stable until X.Y," fronts/marketing/analytics plan without surprises.

---

Version Policy (SemVer for Kernel)

We use SemVer'MAJOR. MINOR. PATCH '+ "schema revision" and "event contract version":

• PATCH (x.y. Z) - corrections without changing API/schemes/calculation logic. Rollout is fast, rollback is trivial.
• MINOR (x.Y.z) - compatible extensions: new "nullable" fields, new events, flags. "Expand-only" migrations.
• MAJOR (X.y. z) - breaking changes: removal of fields/events, change of calculation rules, new ledger invariants.

Additionally, we fix:

• 'schemaVer '(DB/ledger/directories),' contractVer '(bus events and webhooks),' calcVer '(calculation/bonus rules engine).

---

Contracts and backward compatibility

Contracts for external and internal consumers

API/webhooks/events: versioning URL ('/v2/... '), header (' X-Contract-Version '),' schemaVer 'field in payload.

Events in the bus: the 'eventVer' field, silent-breaking prohibition (changes in the field type, status meaning).

DB: expand → migrate → contract migrations.

You can add, change - carefully, delete - with a "shadow"

Adding fields - only nullable/default.

The change of meaning is only in MAJOR with the parallel publication of the "old" field ('_ legacy') for the transition period.

Deletion - after deprecate and telemetry "who else reads the old."

---

Schema and data migrations

Expand: add a column/index, enter a new event - without touching existing readers.

Migrate: fill/recalculate the values ​ ​ in the background (batch/online), include a double entry (dual-write) in a new place.

Contract: translate readers, remove the legacy branch in the next MAJOR.

Tools: migrations under feature-flag, shadow tables, online DDL, invariants at the database level (check-constraints) and domain.

---

Settlement versioning: money, bets, bonuses

Separately fix 'calcVer' - the version of the money calculation logic (rate/hold/settle/VOID, bonus and wagering rules).

In every'round. settled`, `payout. completed`, `bonus. issued 'write' calcVer '.

In a dispute, you can reproduce the calculation with exactly the logic that was in effect at the time of the event.

Switch 'calcVer' canary by percentage of traffic/region/category of games.

---

Observability for versioning

Tags in the trace: 'buildId', 'gitSha', 'semver', 'schemaVer', 'contractVer', 'calcVer' in all critical spans (bet, settle, payout).

Dashboards by version: errors, latency, fin deltas by version.

Alerts to "version drift": when some tire consumers read the wrong circuit.

---

Safety and compliance

Versioned artifacts (images, migrations) are signed; are stored in the unchangeable registry/bucket.

DR/audit: you can raise the environment "as it was on date T" (image, migrations to version, database snapshots).

AML/RG/KYT rule revisions are also versions (policyVer) and their application logs.

---

Release Procedures

1. Contract review: list of changes marked 'PATCH/MINOR/MAJOR', impact on external/internal consumers.

2. Backwards-compat tests: checks on old clients/events (contract tests).

3. Canary rollout: 1-5% of traffic; p95 metrics, errors, financial discrepancies.

4. Telemetry of using legacy: who else is listening to 'v1', which fields are readable - a deprecate plan.

5. Comm package: what changes when end-of-life older versions, how to migrate.

---

Sample Compatibility Matrices (Example)

---

Examples of contracts

Bus event with version:

json
{
"event": "round. settled",  "eventVer": "2. 4",  "schemaVer": "ledger-3. 1",  "calcVer": "wallet-7. 2",  "roundId": "R-2025-10-17-PRAGM-12",  "bets": [{"betId":"b_9f2","stake":"5. 00","payout":"180. 00","outcome":"WIN"}],  "ts": "2025-10-17T14:23:12. 031Z",  "traceId": "tr_5f1"
}

REST with contract version:

GET /v2/wallet/balance
X-Contract-Version: 2. 3

---

Anti-patterns

"Quiet" changes: change the types/meanings of fields without MAJOR and deprecate.

Mix data migration and money logic in one release without dual-write.

Global flags instead of versions (cannot be restored, "what acted then").

Lack of contract tests and schema catalog.

Delete legacy without telemetry use - partners/dashboards break.

A single number "somewhere in the wiki" without artifacts/signatures is not reproducible.

---

Core version discipline checklist

Standards

• Version family: 'semver', 'schemaVer', 'contractVer', 'calcVer', 'policyVer'.
• Data catalog with history and owners.

Contracts

• Versioned endpoints/events, header/version field.
• Deviation procedure with dates and telemetry of use.

Migrations

• Expand→Migrate→Contract, dual-write, онлайн-DDL.
• Shadow tables and invariants at the database level.

Releases

• Canary rollout, compatibility matrix, rollback plan.
• Signed images/migrations, unalterable artifacts.

Observability

• Version tags in trace/logs/metrics.
• Error/latency/Fin Delta dashboards by version.

Compliance/DR

• Reproducible rise of the environment "on the date T."
• policyVer application logs (AML/RG/KYT).

---

Core versioning is the "insurance" of money and the pace of product development. With it, the platform evolves predictably: new opportunities come out without breakdowns, finances remain reproducible, integrations are compatible, audits are calm. Make versions part of the process (contracts, migrations, telemetry, releases) - and your backend will withstand years of change without loss to P&L and reputation.