Documentation
¶
Overview ¶
Package trails renders trails.json — the suggested reading-order artifact (ADR 0016). Each trail is a topologically-valid reading order for one weakly- connected component, rooted at the component's highest-PageRank document and preferring higher-authority docs among the available frontier (the modern realization of Vannevar Bush's associative "trails", "As We May Think", 1945).
It is infrastructure: it reads the frozen emit.View (the domain Trails carried on the GraphMetrics) and never mutates the domain (ADR 0004). Output is deterministic: the trails are sorted by root upstream and the order within each is a deterministic priority topological sort, so the same corpus always yields byte-identical bytes. See docs/schemas/trails.schema.json for the contract.
Index ¶
Constants ¶
const SchemaVersion = 1
SchemaVersion is the trails.json schema version. Additive fields are backward-compatible; renaming/removing a field bumps this. Mirrored by docs/schemas/trails.schema.json (a test validates emitted bytes against it).
const TrailsJSONName = "trails.json"
TrailsJSONName is the conventional trails.json filename.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Document ¶
type Document struct {
SchemaVersion int `json:"schemaVersion"`
Tool string `json:"tool"`
GeneratedNote string `json:"generatedNote"`
Trails []Trail `json:"trails"`
}
Document is the top-level trails.json shape. Field order is the wire order; every slice is sorted/deterministic.
func Build ¶
Build assembles the typed trails.json Document from the frozen View. A View with no trails yields a valid empty-but-stamped document.
trails.json is a consumption surface (ADR 0019: trails exist for onboarding readers): emit-excluded documents are dropped from each trail's order via RenderedTrails — a trail left empty is dropped, an excluded root is re-rooted at the highest-PageRank remaining member. Dropping entries is not a shape change, so SchemaVersion is unchanged.
Source Files