# The riVer Specification v1_draft_20260331T082800Z

riVer (revision identifier versioning) is a standard for a simple and strict versioning scheme for textual content.

It is designed for agentic environments where AI agents both read and write versioned textual content, possibly under human supervision.

The standard draws inspiration from incremental revision numbers used in classic version control systems or word processors, book editions, and [[CalVer]](https://calver.org/). It deliberately creates an alternative to [[SemVer]](https://semver.org/) to avoid the ambiguities around change significance.

The riVer specification is versioned according to the versioning scheme it defines.

## Definitions

### Revisions

A **`text`** is a (possibly empty) sequence of characters forming a connected piece of work (e.g. a file, webpage). The unique *text* consisting of the empty sequence of characters is called the **`empty text`**.

An **`edit`** is the fundamental and atomic action changing a *text* by either
* inserting a non-empty, contiguous sequence of characters into it,
* removing a non-empty, contiguous sequence of characters from it,
* replacing a non-empty, contiguous sequence of characters from it with an unequal, non-empty contiguous sequence of characters.

A **`revision`** is the result of **`applying`** an *edit* to a *text* (i.e. a *revision* is a *text*). A new *text* is **`created`** by *applying* an *edit* (called the **`initial edit`**) to the *empty text* resulting in the so-called **`initial revision`**.

### Revision Identifiers

A **`revision number`** is a non-zero natural number.

A **`revision status`** is a value from the *enumeration*
1. `draft`
2. `ready`
3. `final`

A **`timestamp`** is a [[ISO 8601]](https://en.wikipedia.org/wiki/ISO_8601)-compliant string in the format `YYYYMMDDThhmmssZ` (date and time with second precision in UTC using the basic format to maximize usability in filenames, URLs etc.).

*Timestamps* are *totally ordered* using their natural alphanumerical ordering. A *timestamp* is called **`later`** than another *timestamp* if it is greater, and **`earlier`** if it is smaller than the other *timestamp*.

A **`revision timestamp`** is either
* a *timestamp*, or
* the literal string `now`.

A *revision timestamp* is called **`indefinite`** if it is equal to `now`, and **`definite`** otherwise.

*Revision timestamps* are *totally ordered* by defining `now` to be smaller than any *definite revision timestamp* and use the *total order* of *definite revision timestamps* otherwise.

A **`revision tag`** is a string of the format `v[REVISION_NUMBER]_[REVISION_STATUS]_[REVISION_TIMESTAMP]`.

A *revision tag* is called **`fixed`** if it has a *definite revision_timestamp*, and **`floating`** otherwise.

*Revision tags* are *totally ordered* by the *lexicographical order* of their constituents in order of appearance in the *revision tag* string, where *revision numbers* are ordered naturally (i.e. by numeric value), *revision statuses* are ordered by their enumeration ordinal, and *revision timestamps* are ordered as defined above.

A *revision* is called **`tagged`** (or a **`tagged revision`**) if it has an associated *revision tag* (called the **`revision identifier`** or simply **`identifier`**) which is contained in the *revision's* character sequence. In case the *revision's* character sequence contains more than one *revision tag*, the *revision identifier* must be the first occurence of a *revision tag* in the *revision's* character sequence.

### Documents

A **`modification`** is a triple consisting of
* an *edit*,
* a *revision*,
* a *timestamp*.

The *edit* contained in a *modification* is called the **`modification edit`**, the contained *revision* is called the **`modification revision`**, and the contained *timestamp* is called the **`modification timestamp`**. A *modification* is called **`later`** than another *modification* if its *modification timestamp* is *later* than the other *modification's timestamp* and **`earlier`** if its *modification timestamp* is *earlier* than the other *modification's timestamp*.

A **`document`** is a non-empty sequence of *modifications* such that
* the sequence of *modification timestamps* is strictly increasing,
* the first *modification* contains an *initial edit* and the resulting *initial revision*,
* for any two consecutive *modifications* the *later modification's revision* is the result of *applying* the *later modification's edit* to the *earlier modification's revision*.

For two consecutive *modifications* of a *document* the *later modification* is said to be **`right after`** the *earlier modification*.

The first *modification* is also called the **`initial modification`**. For a given point in time the last *modification* of a *document* is called the **`current modification`**.

A new *document* is **`created`** by *creating* a *text* and using the resulting *initial edit* and *initial revision* together with the current point in time *timestamp* to form the *document's initial modification*.

A *document* is **`modified`** by adding a new *modification* as its *current modification* to it with the current point in time *timestamp* as the *modification timestamp*.

A *document* is called **`tracked`** (or a **`tracked document`**) if
* all its *modification revisions* are *tagged*,
* the sequence of *modification revision identifiers* is increasing.

For a *tracked document*, its *current modification revision identifier* is called the **`document's revision identifier`**.

A *tracked document* is called **`floating`** if its *revision identifier* is *floating*.

A *tracked document* is called **`fixed`** if its *revision identifier* is *fixed*.

A *floating tracked document* is (or gets) **`stamped`** if it is *modified* such that the new *modification edit* replaces the *document's identifier timestamp* (`now`) with the new *modification timestamp* (i.e. changing it to a *fixed tracked document*).

### Resources

A *document* is called a **`copy`** of another *document* (called the **`source document`**) if its *initial edit* adds the entire character sequence of the *source document's* *current modification revision* to its *initial revision* at the point of time given by its *initial event timestamp*. In this case the *source document*, the *source document's current modification*, and the *source document's current modification revision* are called **`copied`**.

A **`resource`** is a non-empty collection of *documents* consisting of exactly one distinguished *document* called the **`golden source`** and a (possibly empty) collection of *documents* which are all *copies* of the *golden source* such that each *golden source modification* is *copied* at most once.

A new *resource* is **`created`** by *creating* its golden source, i.e. a newly *created resource* consists exactly of its *golden source*, and the *golden source* consists exactly of its *initial modification*.

A *resource* is called **`tracked`** (or a **`tracked resource`**) if
* all contained *documents* are *tracked*,
* all *modification revision identifiers* of the *golden source* are *floating*,
* every new *copy* of the *golden source* gets *stamped* *right after* its *initial modification* and does not get *modified* anymore afterwards.

A new *tracked resource* *should* be created with its *golden source initial modification revision identifier* set to `v1_draft_now`.

## Terminology

A *tracked resource* is said to be (or to get) **`bumped`** if a *modification* of its *golden source* results in a strictly larger *golden source revision identifier*. In case this increase results from an increase of the *identifier's *revision status* alone (i.e. the *identifier's revision number* stays the same), the *tracked resource* is said to be (or to get) **`advanced`**. In case this increase results from an increase of the *identifier's revision number*, the *tracked resource* is said to be (or to get) **`promoted`**.

A *tracked resource* is said to be (or to get) **`stamped`** if a new *copy* of its *golden source* is created and subsequently *stamped*.

Every *copy* contained in a *tracked resource* is called a **`resource publication`** (or **`publication`** for short). If the *revision status* of the *revision identifier* of such a *copy* equals *draft*, *ready*, or *final* respectively, the publication is called an **`intermediate`**, a **`candidate`**, or a **`release`** respectively (or **`resource intermediate`**, **`resource candidate`**, or **`resource relase`** respectively).

To **`publish a resource`** means to optionally *bump* and then *stamp* the *resource* to create a new *resource publication*. To **`publish an intermediate, a candidate, or a release`** respectively means to *`publish the resource`** such that the resulting *resource publication* is an *intermediate*, a *candidate*, or a *release* respectively.

For a *resource*, its *publication*, *intermediate*, *candidate*, or *release* respectively with the largest *revision identifier* of all its *publications*, *intermediates*, *candidates*, or *releases* respectively is called its **`latest (or current) publication, intermediate, candidate, or release`** respectively.

The **`latest (or current) version`** of a *resource* (also called the **`latest (or current) resource version`**) is the *revision number* of the *revision identifier* of its *latest release* (if it exists).

If the *latest resource version* does not change when a new *resource release* is published, this *resource release* is called an **`errata`**. To **`publish an errata`** means to *publish a release* that is an *errata*.