Compatibility architecture

Chronacta persists committed events for years. Operators upgrade binaries, expand clusters, and integrate via gRPC/SDK. Without explicit compatibility rules, any storage tweak or proto field rename can corrupt data or break clients silently.

Cluster metadata, replication, export/import, and idempotency are part of the current product. Each persisted subsystem carries a format_version or equivalent constant.

Two compatibility surfaces

Surface	Contract	Version carrier
Wire API	gRPC/protobuf `stream.v1`	Protobuf package + generated stubs
On-disk formats	Engine durability, backups, auxiliary stores	Per-file `format_version` / magic

Wire and disk versions are independent. A server release may bump backup manifest version without changing gRPC package.

SemVer for product releases

v1.x — supported stable release line starting with v1.0.0.
A future major line may introduce breaking wire or disk changes.
MAJOR — breaking wire or breaking disk (without backward read).
MINOR — additive API, new optional features, backward-compatible disk.
PATCH — bug fixes only; no format version bump.

Support window (v1.x): we support the current minor and one previous minor.

Git tag = release artifact identity. Binaries do not embed version yet; operators use tag + go build from tag (see release process).

gRPC / protobuf rules

All public RPCs live in api/proto/stream/v1/.
Additive changes (new fields, new RPCs, new enum values with unknown handling) — allowed in v1 minor releases.
Breaking changes (rename/remove field, change semantics, delete RPC) — require new package stream.v2 and parallel registration period; v1 deprecated for ≥1 minor.
Clients MUST ignore unknown proto fields (protobuf default).
Error codes and messages are part of the contract; changing FailedPrecondition → InvalidArgument for the same condition is breaking.

On-disk format inventory (current)

Component	Path / artifact	Version const	Bump policy
Event record	WAL / segments	`record.FormatVersion = 1`	New engine major; migration tool required
Backup archive	`*.tar.gz` manifest	`backup.FormatVersion = 1`	Restore rejects unknown; export from old supported
Export JSONL	`format_version` field	`JSONLFormatVersion = 1`	Import accepts N and N-1
Export binary	header magic + version	`BinaryFormatVersion = 1`	Same as JSONL
Idempotency store	`data/idempotency/keys.json`	`idempotencyStoreVersion = 1`	Rebuild or migrate offline
Schema registry	`data/schemas/schemas.json`	`registryVersion = 1`	Forward-compatible JSON
Subscriptions	`data/subscriptions/`	`storeVersion = 1`	Offline migration
Projections	checkpoint envelope	`StoreFormatVersion = 1`	Rebuild path always available
Auth store	`data/auth/`	`storeVersion = 1`	Export users or migrate tool
Cluster metadata	`data/cluster/cluster.json`	`cluster.StoreVersion = 1`	HA rolling upgrade doc
NATS checkpoint	bridge state file	`checkpointVersion = 1`	Replay from position

Rule: bump version const → implement read path for previous version or document one-way migration + test.

Migration strategy

Prefer backward-compatible reads — engine opens old segments if record layout unchanged.
Offline migration — use the migration command and documented manual steps when a release requires it; never auto-delete WAL on startup.
Projection rebuild — acceptable fallback for projection checkpoint format changes.
Export/import — universal escape hatch between environments and major versions.
Cluster — upgrade followers first; see HA rolling upgrade.

The server does not automatically rewrite data/ on startup.

Schema registry vs event store

Schema compatibility modes (none, backward, forward, full) govern registration of new schema versions, not retroactive mutation of committed events. Committed payloads remain immutable.

SDK and CLI

CLI/SDK in repo track server main / release tag.
Supported skew: same minor required for production; patch skew tolerated (client older patch → server newer patch).
Idempotency keys and expected-version semantics are stable across patch releases.