Login
OCX protocol version 2: verdicts
Login

A verdict is a tag on a check-in that records a judgement of it: audited for one made by a person or an agent, ci for a program's check. Runs of protocol version 2 write them, but a verdict needs no run: anyone may write one.

Writing a verdict

Write it as a raw tag (Fossil's --raw), so it never becomes a name for the check-in, and on that check-in alone, never propagating to its descendants. A reader reads sym-audited and sym-ci tags as verdicts too, as older OCX wrote them, each on the check-in it names alone. Its value is pass: or fail:, then the reason on one line, then (against X), where X names the objective it was judged against: a run's full hash, or the path of a file that states the objective, such as PLAN.md, read as it stands in the check-in judged. X is everything after the value's last (against, up to its final ); a value not of this form is no verdict. Two examples:

Anyone may write an audited verdict, with OCX's audit tool or with Fossil's own fossil tag add; it needs no run. But a verdict on your own check-in never counts: the author of a check-in cannot pass it. OCX writes a ci verdict on the check-in a build took, as the clone's user, against the build's run, when the run asks for it; CI of a branch is a session that sends a build of each check-in it is given.

Reading verdicts

Version 1 verdicts already recorded keep counting. For this purpose only, unaudited reads historical version 1 runs and starts, including the old actor login and clone-prefix match. The question reader also reads version 1 questions, decisions (including response), and the runs and starts needed to identify their confirmers, so open questions stay listed and confirmations remain effective. These readers never act on historical messages. No other version 1 kind is read; actors continue to read version 2 alone.

A verdict counts only if its sender (Fossil, senders and clones) neither sent the check-in nor is the user named in it. An audited verdict counts only if a user who holds check-in (i) when it is read sent it, and no clone's user: one named as the to of a run that an admin or setup sent; capabilities are taken when it is read, so a revoked reviewer's verdicts stop counting. A ci verdict counts only if the to of the run it names sent it, that run has a started that counts (protocol version 2), and the check-in is the one that started names: a build that holds no credential is judged by the acting clone, as its verdict asks (protocol version 2), never by a run's own program, which may run the change under test. A run named in an audited verdict must be about the check-in: the check-in its counted started.values.checkin names, or one on a branch in its checkins, by the check-in's branch as Fossil's timeline shows it: the branch tag it carries, which a branch's first check-in sets and the check-ins after it inherit. An X that is a hash in full is read as a run's, so a verdict against one that names no run counts for nothing.

Fossil shows only a tag's latest value on a check-in, but keeps every tag change in its event table (type g). So a reader takes the tag changes from there and counts, for each user who sent a verdict, that user's latest for each tag and each objective (X), by the server's receipt order, which a reader on a clone learns from receipt: the times written in tag changes are their writers' clocks, and decide nothing. Cancelling a tag (fossil tag cancel) writes no verdict, and leaves the verdicts before it standing: nothing is retracted.

How to combine the verdicts that count is the reader's choice: any fail fails, a majority, one named reviewer. OCX's unaudited, CI checks and merge gates are all readers. A reader on the server counts by its receipts, and a reader on a clone asks the server with OCX's receipt tool, as OCX does, or asks the server's own reader, as unaudited does.

The proposed rule in the draft allowing a process's user to supply ci is wider than this watcher implements: it writes only as to. This tree has no general ci tally tool; unaudited reads audited alone. A counted started also requires a run sent by a different user holding admin, setup or R, as acting and counting says. Publication follows ended. Completion and republication are built; see the publication rules.

The implemented unaudited reader accepts a matching subscribed branch without requiring a started; the draft's blanket counted-start requirement is not applied to that branch case.