Compatibility and evolution

This page states what stays stable, and where new features come in.

What stays stable

The bytes of an entry

A signed entry stays as it is. Every version of the software reads it under zikaron/1 and reaches the same verdict as today.

Signing domains

Four literals, each with a fixed meaning: zikaron/1, zikaron/1-adoption, zikaron.fpm/1, zikaron.ack/1.

The two forms of anchor

The event form and the self-transfer form.

Verdicts

For the same input, every conforming implementation gives the same output.

Four points of extension

A new entry type

Types are open. Once a new type is agreed, older software lists it under “Unrecognized types”, and the verdict under the law stays as it was; ZIKARON Desk’s ledger status line counts it as a problem.

Extra body members

An entry’s body may carry keys beyond those the law names, and the law treats them as data. for and upstream both came in this way.

A new mode mark

The mark of a record is an open literal. A new fingerprint algorithm or a new kind of content takes a new mark.

A new version of the law

When the rules themselves have to change, start zikaron/2.

The first three are in the tooling layer and usable today. Which to use depends on who has to understand the new thing: for your own app alone, an extra member; for other implementations too, an agreed and published type.

The next version of the law

zikaron/2 means a new spec name, a new signing-domain literal, a new core and a new digest, with signatures under the two versions independent of each other. An old ledger stays valid under zikaron/1; an author who migrates records a handover in the old ledger, naming the key that signs the first entry of the new one.

A key writes ledgers under one law, so the new ledger of a migration takes a new key.

Versions of local files

Every kind of local file carries a format version. When the software is upgraded, it follows these rules:

1. This version’s own forms alone are read and written: local encrypted files in the present envelope, the key store as zikaron-desk/keybox/3, machine.json for the language and appearance. Plain files, other envelopes and other key store forms are left unread and unconverted: the reason is named and the file left as it is.
2. A file that does not read is left as it is: the software names the file and which of six reasons applies; a write to it is refused by name, and once it is moved aside the next write makes it anew.
3. Members this version does not know, in the encrypted machine settings and a data folder’s settings, are carried back as they are.
4. Local encrypted files this version writes are unreadable to 0.1.2 and earlier; 0.1.3 uses the same envelope as this version.
5. A sealed file whose master key is gone, closed for good, is moved byte for byte into set-aside in the machine folder, numbered flat.
6. When a backup comes from a newer version, the software says plainly to update the app first; for any other unreadable file, it names the file.

A change made in bulk (renaming and resealing everything under a new master key, for one) writes its plan and its new files alongside first, reads them back and compares, and switches in one step once they match: after a power cut, the next launch finds either the complete old state or the complete new one; when any comparison fails, it stops and leaves the originals as they are.

A data folder’s label and writer mark are written by the first window that opens it as the writer or writes into it; a reader writes neither.

Upgrading from an earlier version

From 0.1.4 or 0.1.3: install over it; the machine folder and data folders are used as they are, with nothing else to do. This version writes data in the same form as 0.1.4, so 0.1.4 reads what this version writes.

From 0.1.2 or earlier: those versions’ machine folder (key store, identity registry, settings) and data folders are left unread, and this version starts from an empty machine folder. A recorder’s ledger comes across through a ledger mirror, one step by hand:

1. In 0.1.2 (or earlier), “Export ledger mirror” to a folder outside the machine folder, then quit.
2. Move the earlier version’s machine folder aside together with its pointer file (where both are: The machine folder).
3. Start this version, set a passcode and import the identity with the same recovery phrase.
4. When the wizard reaches “Create the ledger”, click “Adopt existing ledger folder”, choose the mirror’s author folder and press “Adopt in place”: every entry is checked again and the ledger is checked against this key’s records on chain, and the step is done. Adoption takes one whole ledger, with exactly one creation entry; a data folder that has its own ledger takes that same ledger alone.
5. Run the ledger check on the Ledger page and see it answer “OK”.

Checking across versions

• From 0.1.4 a folder record’s manifest joins paths with / everywhere. A folder signed on Windows by an earlier version checks out under 0.1.4 and later on every system; a folder signed on Windows by 0.1.4 or later fails to check out under 0.1.3 or earlier on Windows, so the other side should use 0.1.4 or later.
• The encrypted record package is a format 0.1.4 added; 0.1.3 and earlier cannot open it, so its recipient needs 0.1.4 or later.

Command-line output

The output keys and the refusal reasons each form a closed table, and the exit codes are five fixed values; scripts depend on them. So the meanings of keys and exit codes stay stable, and new information comes as new keys; added refusals and changes to what a refusal covers are written into CLI-SCHEMA.md at the same time and listed in the change log; tests check that document against the code item by item. The first line of standard error, <REASON> <subject>, is part of the contract; the lines for people after it follow the system’s language, stay outside the contract, and their wording can improve at any time. zikaron contract prints this contract. The messages of mcp are JSON-RPC and the Model Context Protocol’s own, outside both tables; the protocol versions it speaks are in section 13 of CLI-SCHEMA.md.

Verdict tokens stay as written

GREEN, PARTIAL, FAIL, COMPLETE, GAPS and the like are written by the cores and stay as they are in machine-readable output. The interface renders them for people as “All passed”, “Has gaps” and so on, with the original token under Details.

Time

Deadlines and validity are judged by chain time, or by a moment the caller states explicitly. The interface displays time in the user’s chosen time zone; entries and output always hold seconds.

Retiring a feature

Entries are read by zikaron/1 and record kits by zikaron.kit/1, for good; ledger mirrors and the command line’s ledger folders carry a ledger across versions. Local encrypted files, the machine folder and data folders are read in this version’s own form, and when that form changes, the change log and the manual say how data comes across. Writing features may be retired; when one is, the release notes say so and give users another way to do the same thing.

Keeping the tooling layer light

Tests, gauges, scripts, directory divisions and this document all belong to the tooling layer and serve the law and the user: a fault found is fixed the same day, and what is out of date is replaced. Two things bear the load: the frozen law, and the bytes users have already written.