# Versioning Strategy

## Product version

Semantic Versioning:

`MAJOR.MINOR.PATCH`

Examples:

- `0.1.0` — Foundation
- `0.2.0` — identity/notification expansion
- `0.2.1` — backwards-compatible bug fix
- `1.0.0` — first production-launch baseline

Before 1.0, the project remains pre-GA even though individual phases may be
production-quality inside their declared scope.

## Rules

### PATCH
- bug fixes;
- UI corrections;
- security fixes with no new public behavior;
- compatible migrations.

### MINOR
- new backward-compatible feature/domain capability;
- new tables/columns through migrations;
- new adapters or reports.

### MAJOR
- incompatible contract/schema/deployment change requiring coordinated
  migration or operator action.

## Version sources

- `VERSION` file: filesystem fallback/current release marker;
- `system_versions`: authoritative installed-version history after DB boot;
- `CHANGELOG.md`: repository changelog;
- Update Center: install history and migration execution log.

## Database migrations

Every schema change is an ordered migration. The framework migration
repository determines which migrations already ran; an executed migration is
not manually re-run.

## Asset versioning

Production CSS/JS uses Vite-style content hashes. Old HTML therefore cannot
silently point to a newly overwritten file with different bytes.

Navigation documents/HTML are not intended for long immutable caching.
`sw.js` is explicitly served with `no-cache`.

## Service Worker

- service worker itself is always revalidated;
- navigations are network-first;
- immutable hashed `/build/assets/*` are cache-first;
- old application static caches are pruned during activation;
- users should never need to manually clear browser cache after a normal
  release.