Module annot 

Annotations as per-author append-only logs.

There is no central authority here, so the three things one would normally provide — a total order, an identity, and a notification — are replaced rather than reproduced.

The order is not reproduced at all: it is made unnecessary. Every log has exactly one writer, so merging is a set union of lines, which is commutative, idempotent and associative. The order the logs are read in cannot change the result, and nobody has to agree on anything.

The identity is the SSH account, which is what the log’s filename says. A record’s id carries its author too, so a log that tries to touch someone else’s record is ignored rather than obeyed — and “you cannot delete someone else’s annotation” stops being a rule anyone has to enforce and becomes a fact about the shape of the data.

Notification is not this module’s problem; it is a readdir of one directory, which returns every log’s mtime and size in a single round trip.

Structs

Annotation

What a reader sees after the logs are folded together.

AuthorLog

Loaded

What load found, including what it could not read.

Record

One line of one author’s log.

Store

Enums

Attribution

Whether the filesystem agrees with what a log’s filename claims about its author.

Op

Constants

SIDECAR

The directory that holds a document’s sidecar data.

Functions

ann_dir

Where a document’s annotation logs live.

attribution

Judge one log’s filename against the owner a listing reported.

merge

Fold every author’s log into the annotations that survive.

new_id

Mint an id for a new record.

parse

Parse a log, reporting how many lines could not be read.