Compatibility policy

Это содержимое пока не доступно на вашем языке.

Operator-facing summary of Chronacta compatibility guarantees. Technical details: Compatibility architecture.

Supported versions

Track	Status	Support
`v1.x`	stable	current minor + previous minor (2-minor window)

Current stable release: v1.0.0.

Upgrade procedures for future major releases will be documented in their release notes.

What we guarantee

Within the same minor release

gRPC stream.v1 RPCs remain callable with the same semantics.
Existing data/ directories open without migration.
Backup archives produced by N restore on N and patch upgrades.
Export files import into the same or newer minor.
CLI flags and SDK types for documented operations stay stable.

Patch releases

Bug fixes only.
No format_version increment.
Safe to roll single-node or rolling HA upgrade patch-to-patch.

Minor releases

Additive proto fields and RPCs allowed.
New optional config/env vars allowed with defaults preserving old behavior.
Deprecations announced in release notes; old paths work for at least one minor.

Recent additive API (same minor): SubscribeResponse.control, LeaveConsumerGroup, GetConsumerGroup, consumer group member index/count fields. Clients must ignore unknown fields.

Major releases

May require migration tool, export/import, or projection rebuild.
May introduce stream.v2 while stream.v1 remains for a deprecation window.
Documented in upgrade guide with explicit checklist.

What we do not guarantee

Undocumented RPCs or internal packages (internal/).
Direct file copy between different format_version without compatibility statement.
Mixing CLI built from tag A with server from tag B across major versions.
Follower reads with zero lag during leader failure.
Downgrade after a disk format bump without restore from backup.

Version matrix (on-disk)

Current on-disk format versions:

Artifact	Version	Cross-version import
Event record (WAL/segment)	1	Same engine major only
Backup manifest	1	Restore same or newer server
Export JSONL / binary	1	Import same or newer server
Cluster metadata	1	Same cluster mode major
Projection checkpoint	1	Rebuild if incompatible

When importing a backup or export, use tools from the target server version. Downgrading data to an older format is unsupported.

gRPC client guidance

Pin client to release tag or same minor as server.
Use idempotency keys for append retries after timeout.
Treat Aborted (version mismatch) as client state error, not server bug.
Treat FailedPrecondition on cluster as wrong leader — refresh cluster status.
Ignore unknown proto fields; do not depend on unset optional fields without defaults.

Schema evolution (application events)

Separate from server versioning:

Register schemas with explicit compatibility mode (schema operations).
New schema version ≠ server upgrade; both can happen independently.
Append validates against registered schema when schema_name / schema_version set on event.

Reporting compatibility issues

Include in the report:

Server tag or commit, CLI/SDK version
chronacta storage-status, cluster status if HA
Whether issue is wire, disk, or schema-level
Steps to reproduce with minimal stream