Skip to content

Stability and compatibility

WARM follows semantic versioning. The crate is 0.x today: until 1.0 a minor release may break any surface, but the on-disk promise below is already kept (every released store, v0.6.1, opens in the current code; see tests/golden/). The 1.x promises start at 1.0.0.

Surfaces

Surface Versioned as Stable in 1.x Not covered
Rust crate (warm-rust) crate version items reachable without the experimental feature, outside core::format::scan internals experimental feature, doc(hidden), pub(crate)
Python (warm-python wheels, warm-sdk) PyPI version documented classes and functions underscore names; the phase substrate is experimental
Node (writerslogic-warm on npm) npm version the exports in index.d.ts, memory.d.ts, semantic.d.ts undocumented properties
HTTP (warm-server) URL prefix /api/v1 documented endpoints, request and response fields, error codes new optional fields may appear; new endpoints
C ABI writerslogic-warm-c package version and hms1_* ABI major documented v1 symbols, ownership rules and fixed value-struct layouts; size-tagged option structs grow append-only Rust layouts, internal symbols and unversioned convenience macros
Go, Java and .NET binding package version and underlying C ABI major documented wrappers over the versioned C contract private FFI helpers; package availability is recorded in each runtime guide
Swift and Kotlin UniFFI crate and binding package version experimental until a stable binding contract is declared generated UniFFI interfaces, metadata and packaging layouts
WebAssembly WASM crate and npm package version experimental until a stable binding contract is declared generated JavaScript glue, scalar/SIMD artifact layout and experimental APIs
Persisted format per artefact, see below yes caches (below)

WritersLogic maintainers review changes to these contracts. C callers check hms1_abi_version() before using the library; a new ABI major uses a new symbol prefix so old and new majors can coexist. The language-specific runtime guides record supported platforms, build requirements and verification limits.

Additive changes (new optional field, new endpoint, new function) are minor. Removing or changing behaviour is major. Security fixes may break an unsafe behaviour in a patch release and say so in the changelog.

The file-format promise

  1. Backward: a store written by any 1.x opens in every later 1.x, read-write, without a migration step. The same holds for released 0.x stores (v0.6.1 is in tests/golden/).
  2. Never silently converted: the engine keeps writing a store in the format it has. A format change is performed by warm-format upgrade, which writes a new store and leaves the old one untouched.
  3. Forward: an older reader meeting a version it does not know (arena manifest, store.json schema, journal magic) refuses to open and says "newer than supported"; it does not guess. A newer release only produces such a store when a feature that needs it is used, and documents which. Exception, 0.7.0: new stores are created with store.json schema 3, whose journal frames are binary (HMS-TXN-3, file-format/MUTATIONS.md); 0.6.x refuses them. Schema 2 stores keep writing HMS-TXN-2 JSON frames, and 0.7 reads both. Stores created by 0.7.0 are schema 4: schema 3 plus document checkpoints, which replace the journal frames before them (file-format/CHECKPOINT.md); a release that predates checkpoints refuses schema 4 rather than opening it without its checkpointed documents. Schema 2 and 3 stores open, replay their frames and never get a checkpoint. The current development writer creates new stores with schema 5, which additionally permits namespace-scoped durable meaning maintenance. Schemas 2, 3 and 4 remain readable and writable in their original format; governance that needs scoped mutations returns an upgrade error. Run warm-format upgrade <source> <destination> explicitly to enable schema 5 in a new copy. Schema-only upgrades retain the existing arena and checkpoints unchanged; old readers refuse schema 5 rather than misreading scoped deletions.
  4. Breaking the format happens only in a major release, with the old format still readable or an warm-format upgrade step, and a golden store for each side.
  5. Caches (documents.text, indices.json, NSG/IVF files, shard_meta.json aside) may change at any release; the engine discards and rebuilds what it cannot read.
  6. Encoders are permanent: an encoder name always produces the same vectors. Changing output means a new name; stores keep the encoder they were created with.

How this is enforced: tests/format_golden.rs opens every committed golden store and checks contents and searches; it also regenerates the canonical corpus and fails if the journal bytes differ from the newest golden. A format change therefore cannot land without a version bump (src/core/format/mod.rs) and a new golden store, and scripts/format-gate.sh rejects any edit or deletion of an existing golden file.

Standalone persisted vector update directories have their own version 1 contract in file-format/VECTOR-UPDATES.md. Their committed golden checkpoints and logs are read and regenerated by vector_format_golden_and_drift_gate; they are covered by the same append-only golden-file gate. The standalone vertex encoding inside a checkpoint remains WARMVGR01.

Deprecation

A deprecated Rust, Python, Node or HTTP item stays for at least one minor release and six months, whichever is longer, and is marked in docs and (where the language allows) by a deprecation attribute or warning. A deprecated file-format feature is read for the whole major series.

Explicitly unstable

  • the experimental feature and everything it gates: research modules, connection graph and phase graph, the capped-union encoder, connection_graph.log;
  • conversation-memory, private-search, local-models (model stage APIs and model directory layout), provenance* file layouts (provenance_log.jsonl, kel.json) until they get their own specification;
  • the standalone qgraph/IVF cache files, benchmark binaries and their output formats, warm-eval, warm-admin output JSON field order;
  • the NSG/IVF bincode layout and anything else the format documents call a cache.