Documentation
¶
Overview ¶
Package toolrun owns the append-only tool-run outcome log (SPEC-ADDITIONS §16/§18): one record per `adh tool run`, stamped so a §13 tool's declared KPIs can be measured against how it actually behaves over time. Load and Append are the thin I/O shell around a JSON array; a missing file reads as empty. Writes are atomic.
Index ¶
Constants ¶
const RunFile = ".adh/tool-runs.json"
RunFile is the tool-run outcome log path (§16/§18): a JSON array of records `adh tool run` appends to, read by `adh kpi` to observe per-tool KPIs.
Variables ¶
This section is empty.
Functions ¶
func Append ¶
Append adds records to the log at path, creating it and its directory if absent, and rewrites the file atomically. Appending nothing is a no-op, so it never creates an empty log.
func AppendOutcome ¶
func AppendOutcome( path, tool, stratum string, ran, failed bool, durationMS int, unrunnable string, ) error
AppendOutcome records one tool run to the log at path: it builds the stratum-stamped record from the run's outcome and appends it. It is the single owner of the Record field mapping, so every tool-run site — `adh tool run`, `context verify`, adjudication — turns its result into telemetry the same way. Best-effort at the call site: the returned error is for surfacing, never for failing the run.
Types ¶
type Record ¶
type Record struct {
Tool string `json:"tool"`
Stratum string `json:"stratum,omitempty"`
Ran bool `json:"ran"`
Failed bool `json:"failed"`
DurationMS int `json:"duration_ms,omitempty"`
// Unrunnable is why the check did not run, meaningful only when Ran is false.
//
// **Ran:false alone is a count, not a signal.** A log that records how often the
// deterministic path missed and never why cannot say whether the misses are a
// broken environment, a critic naming artifacts that do not exist, or findings
// naming nothing at all — and those three call for entirely different responses.
// The reason is computed at adjudication (adh.Unrunnable) and used to be discarded
// once the verdict was reported.
//
// The load-bearing analogue is a surveyed router's `KeywordsNotFound`: what makes
// its miss log actionable rather than a tally is that it records *which*
// deterministic layer missed and on what.
Unrunnable string `json:"unrunnable,omitempty"`
}
Record is one tool invocation's outcome: the tool id, the year-month Stratum it ran in (the §18.2 replication axis), whether it Ran at all (a startable command), whether it Failed (ran and exited non-zero), and how long it took (DurationMS, 0 when it did not run). A run that could not start is Ran=false.
Source Files