3.0 KiB
records
The record, read where it is written (novox/hq ADR 0025, ADR 0153).
A module that keeps a checkout of a repository of decisions, designs and issues — the mesh's own
hq, or any repository of markdown on the forge — and answers questions about it over the bus, so
whoever holds the console sees records_search beside every other tool and a symptom can be looked up
in the design record without knowing it is there.
A checkout, not a copy. The same bytes the repository holds, at a commit every answer names,
brought up to date on every merge the forge announces (git.pull-merged) and every ten minutes
besides. Nothing is indexed, transformed or summarised, so nothing can drift from the source except by
lagging behind it, and the lag is in records_status.
Tools
| tool | answers |
|---|---|
records_search {query, limit?} |
where a phrase appears, as written: document, line, nearest heading, and the commit read |
records_read {path} |
one document, whole |
records_list {folder?} |
what a folder holds |
records_decisions {topic?} |
retired (hq issue 488): refuses, naming the knowledge base's knowledge-base.holds, ask and get. The decision records and research efforts live in the knowledge base (hq ADR 0290), and an index read from an emptied 02-DECISIONS would answer every topic empty as a success |
records_status |
repository, forge, commit and its date, last sync, document count, last error |
records_sync |
bring the checkout up to date now |
Configuring it
The module names no mesh (ADR 0112). It requires the git provision — the forge — and reads the
repository its settings name:
settings set records repository.json # {"repository": "<owner>/<name>"}
Public repositories only: it asks for no credential. Until a repository is set, it serves no tools and says so in its log.
The check ADR 0025 names
Search the mesh, through the console, for a phrase that appears only in one design document here, and
get it back. records_search {"query": "…"} is that search; its test does the same against a
repository it makes.
Where the checkout lives
A Go bundle the node's runtime launches as the operator account (cmd/records). It clones into
repository/ inside the directory the mesh gives it — a directory it makes, and so owns. An earlier
layout cloned into the given directory itself, from a container running as root, and left files the
operator account cannot change; git then refused every sync as "dubious ownership" (hq issue 251). What
that layout left is removed where it is the module's, and named in records_status (leftBehind, with
the one command that deletes it) where it is not.
Files it does not know
Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).
${dir:mesh-state}: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).${dir:checkout}: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).