tracker #

tracker is the pure state model for a Git-native issue tracker. A row carries its acceptance checks and, while owned, the worker and instant of its claim. The durable store is a dedicated tracker Git repository, independent of the code repositories it describes. Creating a code branch does not fork issue state or claims; only the designated tracker store ref accepts them. Tracker.Core.claim and Tracker.Core.release return a new row or a refusal; the caller persists the result only after checking that the store still has the row it read. No claim expires with time.

A worker records its dispatcher and whether it has ended. Tracker.Core.end_worker returns a new roster and rows together, ending the worker and releasing every claim it holds. The worker itself or its dispatcher may do this. A more distant ancestor may do it after every intervening dispatcher has ended. The store must commit that result in one operation.

The core is independent of Git and IO. Row.v creates an open row with an explicit filing instant, priority, triage state, acceptance checks, labels and typed edges; Worker.v creates a worker; State.v combines a roster and rows. A caller that needs to inspect a claim can use Row.claim, which returns the worker and timestamp when one exists. Row.claim_holder is for a row known to be claimed and raises on an unclaimed row.

Schema.snapshot checks row kinds, statuses, label families, check kinds and unique row IDs before admitting a set of rows. Schema.rewrite validates every row against a replacement vocabulary while preserving row identity. Row.merge ~ancestor left right combines independent label, check and edge changes with the vendored mrdt three-way set merge. Competing scalar changes are conflicts; a claim or status change must go through the authority.

Row_json.of_string ~schema ~id reads a stored row.json against the schema from its Git tree. The id comes from the row directory. Row_json.to_string ~schema writes validated rows with a fixed member order and final newline, so a Git diff shows the field that changed. Unknown fields are refused.

Schema_toml.of_string reads the store's schema.toml; the writer is Schema_toml.to_string. Its arrays list the admitted kinds, statuses and check kinds. Each [[label_families]] entry gives a name and values; ["*"] admits any value in that family. Each [[scorecard_fields]] entry declares a required field of score.json as text, grade or rows. A scorecard record must include grade and rows; the latter is a list of measured steps with a grade, reading, evidence paths and owning issues. Score_json checks and writes that record in schema order. Unknown keys and duplicate field names are refused.

Schema_candidate.v validates a schema, all its rows and each scorecard's score.json together. Schema_candidate.rewrite applies replacements to all three in memory and returns a candidate only if every result is valid and each row keeps its id. The store writes that candidate as one Git tree.

Store_tree.load ~repo ~commit reads schema.toml, row files and score files from that commit's tree with nox-git-eio. It checks the SHA-256 shard of each row id and returns the source tree id with the validated candidate, so an index can be tied to the exact tree it describes.

Distributed coordination defines the shared machine-local authority, cross-machine convergence and ref decision model.

The package's current test gate is:

dune build @ocaml-tracker/runtest