Versioning, migration and forward compatibility

format is major.minor.patch. Major and minor identify the format; a patch release is editorial and never changes what a document may contain (a 1.0 reader treats 1.0.7 as current). A minor release may add optional fields, node types, paint kinds and features. A major release may change or remove anything. Within 1.x every minor release is backward compatible (§16.4); the 0.x line, which allowed breaking minors, ended with 0.1. Defaults MUST NOT change within a major version.

• A migration is a pure function from one format line (major.minor) to the next, registered in @kimo/core-schema (MIGRATIONS, e.g. migrations/1.0→1.1), tested with fixtures. The 1.0 registry holds one step, 0.1 → 1.0: format 1.0 is format 0.1 declared stable, so every 0.1 document is a valid 1.0 document and the step is the identity; only the format and $schema header lines change (fixtures fixtures/migrations/). A file with any 0.1.x format therefore opens migrated in memory behind the upgrade prompt below.
• Readers open an older file migrated in memory. Autosave of a migrated file goes to a recovery file (~/.kimo/recovery/<hash>), never to the working file, until the user accepts a one-time "Upgrade file format" prompt or saves explicitly. The upgrade then changes the format and $schema header lines, plus whatever the migration itself must rewrite.
• Migrations MUST preserve every property they do not understand.
• A file with no migration path to the reader's version opens read-only.

• A file whose format major or minor is newer than the reader's, or whose features include one the reader does not support, opens read-only: saves are refused with a "newer Kimo needed" message. A validator does not validate a newer document beyond its version (FORMAT_NEWER).
• Readers MUST preserve unknown properties, unknown root members, unknown node fields and unknown node types on round-trip.
• Conformance test (in @kimo/core-schema): a newer file is byte-identical after open and re-serialization, and an edit to one node changes only that node's line.
• A store that failed to load is read-only and cannot be saved. Editors SHOULD also open documents with validation errors read-only unless the user chooses to repair them.

• Appendix A is frozen for the 0.x and 1.x lines: keys introduced by later versions are never ranked, so they sort after all ranked keys by code unit, and everything below them is ordered purely by code unit (§15.2). This is what lets an older reader re-serialize a newer document byte-identically. At the root this holds for every new member (§15.1 rule 2). Below the root, ranking is by name, so later versions MUST NOT introduce a property whose name is already in Appendix A on an object that does not define it in 1.0; they pick an unranked name instead.
• New record-valued properties are opaque to older readers, so their subtrees are ordered purely by code unit in every version.
• New semantics MUST be introduced through new properties, node types, paint kinds or feature flags, never by changing the meaning or default of an existing property within a major version.