Documentation
¶
Overview ¶
Package provision is StageFreight's shared environment-realization surface: the single, honest way every subsystem communicates what tools and native capabilities it pulled in, where from, and how (if at all) it verified them.
It is a trust LEDGER, not decoration. One fixed-column table — tool, version, via, verified, purpose — rendered in its own box, separate from whatever the subsystem went on to DO with those tools. Columns never change meaning row-to-row; a cell is its column's datum or blank.
── Staged Tools ─────────────────────────────────── │ tool version via verified purpose │ go 1.26.1 go.dev checksum │ cargo-llvm-cov 0.8.7 github tofu coverage instrumentation │ build-base 0.5-r4 apk delegated C compiler for the race detector (cgo) └───────────────────────────────────────────────────────
Index ¶
- Constants
- func Record(ctx context.Context, e Entry)
- func RecordCtxAll(ctx context.Context, es []Entry)
- func Render(w io.Writer, entries []Entry, color bool)
- func Resolve(ctx context.Context, rootDir, tool, version, purpose string) (toolchain.Result, error)
- func StageBox(ctx context.Context, w io.Writer, color bool)
- func WithLedger(ctx context.Context) context.Context
- type Entry
Constants ¶
const (
VerifiedDelegated = "delegated"
)
Verified vocabulary. checksum/tofu/pinned/signed are things WE did; delegated means we verified nothing ourselves and rely on the package manager's own chain (apk).
Variables ¶
This section is empty.
Functions ¶
func Record ¶
Record adds an already-built Entry to the ctx collector — for tools acquired outside Resolve (ResolvePinned, EnsureRustLlvmTools) or native substrate rows.
func RecordCtxAll ¶
RecordCtxAll records a batch (e.g. FromSubstrate output) into the ctx collector.
func Render ¶
Render writes the "Staged Tools" box: a fixed-column ledger of the given entries. A no-op when empty. This is the LOW-LEVEL box; phases go through StageBox (which drains the ctx delta and calls this). Direct callers are the exception — a subsystem rendering its own one-off row (see dependency) — guarded by the render-boundary ratchet so the phase path stays the norm.
func Resolve ¶
Resolve is the sensible provisioning call: it resolves a tool via the toolchain engine AND records it (with trust from Result.Trust + purpose) in the ctx collector, if one is present. Use this instead of toolchain.Resolve so a tool lands in the next "Staged Tools" box by construction — no per-caller result plumbing. Safe with a bare ctx (no ledger): it just resolves. toolchain.Resolve stays pure; this is the seam.
func StageBox ¶
StageBox is THE way a phase presents the tools it prepared: it drains the phase's provisioning delta from the run ledger and renders a "Staged Tools" box to w. The convention — followed identically by every phase — is to call it ONCE, immediately before opening the phase's work section (output.NewSection), so the box lands in front of the work it enabled. No-op when the phase pulled nothing (or no ledger).
This is the single, discoverable entry point; phases never touch the ledger's flush or call Render directly. Adding a new tool-using phase means one line — StageBox(ctx, w, color) — ahead of its work box, nothing else.
Types ¶
type Entry ¶
type Entry struct {
Tool string // what was realized (go, cargo-llvm-cov, build-base, git)
Version string // exact resolved version
Via string // the resolution path we took (github, go.dev, rust-lang, apk, https)
Verified string // how WE verified it (checksum|tofu|pinned|signed|delegated); "" = unknown
Purpose string // why it was pulled; blank for the base toolchain
}
Entry is one realized dependency — a single row of the trust ledger.
func Collected ¶
Collected returns a copy of everything recorded in this ctx's collector — the whole run's tools. The terminal shows them per-phase (FlushCollected); Collected is for the structured CI artifact, the one place the full ledger is summarized.
func FromSubstrate ¶
FromSubstrate maps realized native capabilities into ledger rows — one per installed package. Substrate comes from apk (via=apk), which we do not verify ourselves (verified=delegated); the honest label makes that non-verification visible.
func FromToolchain ¶
FromToolchain maps a resolved toolchain into a ledger row. verified comes straight from Result.Trust (already pinned|checksum|tofu). purpose is blank for a base toolchain, or a short reason when pulled for something specific (e.g. coverage).
Source Files