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. A new version reads every old format.
2. To rewrite a file in a new format, write it alongside, read it back and compare, and replace the original once they match.
3. When any comparison fails, stop, leave the original as it is, and name the file to the user.
4. 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.
5. 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.

The whole process happens in one step: after a power cut, the next launch finds either the complete old state or the complete new one.

Command-line output

The output keys form a closed table and the exit codes are five fixed values, and scripts depend on them. So the meanings of keys and exit codes stay stable; new information comes as new keys; new subcommands and flags are added to CLI-SCHEMA.md at the same time.

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

Reading features are kept for good: new versions have to read old entries, old record kits and old backups. 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.