Release safety
Release safety is the set of practices that make Volodyslav safe to install, upgrade, synchronize, migrate, and recover.
The central concern is not only whether the code builds or tests pass. A release can still be unsafe if it can corrupt durable state, lose data, make synchronization ambiguous, apply a migration incorrectly, publish a half-written database state, or make forward recovery difficult. Release safety exists to prevent these outcomes, detect them early, and preserve a path forward to a known-good state.
Failure modes
Volodyslav treats the following as release-safety concerns:
- data loss;
- database corruption;
- incorrect migrations;
- incompatible persisted formats;
- synchronization conflicts;
- partial writes becoming observable;
- generated state diverging from durable state;
- installation of code with known unresolved correctness blockers;
- inability to recover forward after a bad deployment.
A release is safe only when these failure modes have been considered and the relevant safeguards are in place.
Durable checkpoints and forward-only release recovery
Volodyslav keeps checkpoints of its most important database state. Checkpoints support diagnosis and data inspection: they let a operator or developer observe what state existed at an earlier moment without making that state authoritative again.
Release recovery is forward-only. Replacing an existing local database with an older checkpoint, or rewinding its remote publication to an earlier state, is not a supported recovery path: either operation can make already-published writer coordinates disappear and later be re-authored while an older copy may still re-enter supported history, violating record-id uniqueness. A checkpoint is therefore never replacement authority for an existing Journal database and never permission to rewind remote publication.
Recovery after a bad release moves retained history forward. A corrected release uses ordinary supported operations and, when a database-version transition is required, a new canonical Journal-aware migration step. When version/schema remain compatible, resetTo() may re-establish a known-good source projection while retaining all history already observed by the receiver; that is semantic rebaselining, not database rollback.
This changes the release model: the system is allowed to evolve its storage format and computation engine, but those changes must preserve forward recoverability. A failed release is recovered from, not reversed.
Atomicity in the database
Volodyslav tries to avoid exposing half-applied durable state.
Many operations update several records that only make sense together. In the incremental graph, for example, values, freshness, validity sets, timestamps, and semantic-key-to-identifier mappings together describe one logical graph state. Publishing only some of those records can create a database that is syntactically readable but semantically inconsistent.
Release-safe persistence code should therefore preserve atomicity at the level of the logical operation, not merely at the level of an individual key-value write.
For incremental graph persistence, this means durable writes are committed before the corresponding volatile identifier lookup is published. The important invariant is that observable memory should not claim a persisted fact that the database does not yet contain.
For synchronization and migration, this means incoming or transformed state should be prepared in staging storage or an inactive replica. The active state should change only after the candidate state has been checked and written successfully.
Versioned storage and explicit migrations
Volodyslav stores version metadata with database state. Code that opens a database can check whether the persisted format is the format it expects.
Format transitions should be explicit. A migration should be a deliberate operation with a known source format and target format. Silent best-effort repair is avoided when the system cannot prove what it is repairing.
When old snapshots require a special conversion path, that path should be owned by a specific migration or conversion script rather than hidden inside unrelated runtime code.
Synchronization safety
Synchronization is release-sensitive because it combines state from multiple places.
Journal 3 synchronization validates the held source's version, graph scheme, and committed Journal frontier, imports compatible immutable foreign-writer suffixes, checks causal closure and record well-formedness, and deterministically replays the retained Journal. It stages the derived graph and Journal together in an inactive replica and publishes that pair atomically. It does not merge materialized graph records, identifiers, timestamps, or stored validity edges as independent authorities.
Known synchronization correctness gaps must block release. Examples include a writer fork, a missing committed writer prefix, incompatible Journal history, an invalid proof, or a failure that exposes a partial graph/Journal cutover. Different hosts normally have different fingerprint-scoped storage identifiers; such differences do not invoke the retired graph-record merge algorithm.
Release-blocker markers
Some unsafe states are useful to keep in the repository temporarily while a larger change is being developed. For those cases, Volodyslav uses explicit release-blocker markers.
A release-blocker marker is a unique string placed next to a known unresolved release-safety issue:
THIS-MARKER-BLOCKS-VOLODYSLAV-RELEASE-XXXXX
The link-targeted step in the install path scans tracked files for this marker.
If the marker is present, installation fails and reports the matching locations.
This covers make install, scripts/install, and any path that eventually links
installed files — the shared final step for all install entry points.
This is intentionally stronger than a comment. A comment informs a reader; a release-blocker marker changes program behavior. It turns a known unsafe repository state into an executable guardrail.
For non-release CI or installation tests, the blocker may be bypassed explicitly with an environment variable. The bypass is explicit because “running on CI” does not by itself mean “safe to ignore release blockers.”
Build, test, and static checks
Builds, tests, linting, and type checking are part of release safety, but they are not the whole policy.
They help catch implementation errors before installation. They are especially important for persistence code, migration code, synchronization code, and filesystem rendering code, where small regressions can affect durable state.
However, passing tests does not automatically mean a release is safe. Known unresolved correctness issues still require release blockers, and durable-state changes still require forward-recovery and migration planning.
Policy
A change that affects durable state, synchronization, migration, installation, or generated graph state should answer these questions:
- What persisted state can this change read or write?
- Can a failure leave active state partially updated?
- Is there a forward recovery path?
- Does the stored format have version metadata?
- Are migrations explicit?
- Is incoming synchronized state staged before publication?
- Are metadata invariants validated?
- Are known unresolved correctness issues marked as release blockers?
- Can installation accidentally proceed while a blocker remains?
Release safety is not one mechanism. It is the combination of forward-only recovery, explicit formats, atomic database publication, staging, validation, tests, and install-time guards.