Documentation
¶
Overview ¶
Package trace implements the truth emission model for StageFreight.
Every input, decision, mutation, and side effect must emit a structured Emission. Panels only render collected emissions — direct writes to output are forbidden for anything that affects operator truth.
Security contract: secrets must never enter the emission system as raw values. Use the safe helpers (SecretPresent, Public, Masked, Decision) instead of constructing Emission{} directly. Collectors validate sensitivity at emit time.
Enforcement layer: at end of run, Unrendered() detects contract violations. The Contract panel surfaces these — panels must call MarkRendered for each emission they surface, or the run is marked contract:incomplete.
Index ¶
- type Category
- type Collector
- func (c *Collector) All() []Emission
- func (c *Collector) Decision(domain, key, value, detail, source string, status EmissionStatus)
- func (c *Collector) DomainStatus(domain string) EmissionStatus
- func (c *Collector) Emit(e Emission) error
- func (c *Collector) ForDomain(domain string) []Emission
- func (c *Collector) HasFailure(domain string) bool
- func (c *Collector) MarkAllRendered(domain string)
- func (c *Collector) MarkRendered(e Emission)
- func (c *Collector) Public(domain string, cat Category, key, value, source string, status EmissionStatus)
- func (c *Collector) PublicDetail(domain string, cat Category, key, value, detail, source string, ...)
- func (c *Collector) SecretPresent(domain, key, displayValue, source string, status EmissionStatus)
- func (c *Collector) SideEffect(domain, key, value, detail, source string, status EmissionStatus)
- func (c *Collector) Unrendered() []Emission
- type Emission
- type EmissionStatus
- type Sensitivity
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Category ¶
type Category string
Category classifies what kind of influence point an emission represents.
const ( // CategoryInput covers config values, CLI flags, env vars, presets, defaults. CategoryInput Category = "input" // CategoryDecision covers branching logic, fallbacks, skips, mode switches. CategoryDecision Category = "decision" // CategoryMutation covers normalization, overrides, derived values, cache key resolution. CategoryMutation Category = "mutation" // CategorySideEffect covers builds, pushes, commits, releases, syncs — external mutations. CategorySideEffect Category = "side_effect" )
type Collector ¶
type Collector struct {
// contains filtered or unexported fields
}
Collector accumulates emissions for a single execution run. Thread-safe for concurrent phase execution. Index-based tracking prevents key-collision false-positives in MarkRendered.
func (*Collector) Decision ¶
func (c *Collector) Decision(domain, key, value, detail, source string, status EmissionStatus)
Decision emits a branching decision (skip, fallback, mode switch). Value is the decision outcome (e.g. "skipped", "fallback", "ci-mode").
func (*Collector) DomainStatus ¶
func (c *Collector) DomainStatus(domain string) EmissionStatus
DomainStatus returns the aggregate status for all emissions in a domain. fail > warn > ok > info > skipped.
func (*Collector) Emit ¶
Emit records a structured emission after security validation. Panics in development on contract violations (secret in Value, pattern match). Returns error to allow graceful handling in production paths.
func (*Collector) ForDomain ¶
ForDomain returns all emissions for the given domain, in emission order.
func (*Collector) HasFailure ¶
HasFailure returns true if any emission in the given domain has StatusFail.
func (*Collector) MarkAllRendered ¶
MarkAllRendered marks all emissions for a domain as rendered. Use when a panel renders all emissions for its domain in a loop.
func (*Collector) MarkRendered ¶
MarkRendered records that an emission was surfaced in a panel. Uses index-based tracking — no key collision possible. Panels must call this for every emission they render. Accepts the Emission value directly so idx (unexported) is accessible without exposing it as a public field.
func (*Collector) Public ¶
func (c *Collector) Public(domain string, cat Category, key, value, source string, status EmissionStatus)
Public emits a public fact. Value is displayed as-is. Use for non-sensitive data.
func (*Collector) PublicDetail ¶
func (c *Collector) PublicDetail(domain string, cat Category, key, value, detail, source string, status EmissionStatus)
PublicDetail emits a public fact with detail text (for warn/fail states).
func (*Collector) SecretPresent ¶
func (c *Collector) SecretPresent(domain, key, displayValue, source string, status EmissionStatus)
SecretPresent emits only the presence/absence of a secret — never its value. displayValue is the safe operator-facing representation (e.g. "configured", "missing").
func (*Collector) SideEffect ¶
func (c *Collector) SideEffect(domain, key, value, detail, source string, status EmissionStatus)
SideEffect emits the outcome of an external mutation (commit, push, sync, release).
func (*Collector) Unrendered ¶
Unrendered returns emissions that were collected but never marked rendered. A non-empty result at end of run is a contract violation. info-severity emissions are excluded — they inform formatting, not rendering contract.
type Emission ¶
type Emission struct {
Domain string // PanelDomain string — which panel owns this
Category Category // input / decision / mutation / side_effect
Key string // logical name: "docker_readme", "build_date", "cosign_key"
Value string // raw value — MUST be empty for Secret sensitivity
DisplayValue string // safe render representation (required for Masked/Secret)
Status EmissionStatus // ok | warn | fail | info | skipped
Detail string // human-readable detail for degraded/failed states
Source string // provenance: "env:VAR" | "config" | "default" | "inferred" | "cistate"
Sensitivity Sensitivity // public | masked | secret | opaque
// contains filtered or unexported fields
}
Emission is a structured signal from any influence point in the execution.
Security rules:
- Sensitivity=Secret: Value must be empty; use DisplayValue for safe repr.
- Sensitivity=Public: Value must not match secretPatterns.
- Callers should use the safe helper methods instead of constructing this directly.
func (Emission) RenderValue ¶
RenderValue returns the safe value for panel rendering. For Secret/Opaque: returns DisplayValue. For Masked: returns DisplayValue if set. For Public: returns Value.
type EmissionStatus ¶
type EmissionStatus string
EmissionStatus is the outcome of the emitted fact.
const ( StatusOK EmissionStatus = "ok" StatusWarn EmissionStatus = "warn" StatusFail EmissionStatus = "fail" StatusInfo EmissionStatus = "info" StatusSkipped EmissionStatus = "skipped" )
type Sensitivity ¶
type Sensitivity string
Sensitivity classifies whether an emission's value may be rendered/stored raw. Sanitization must happen BEFORE collection — never rely on render-time masking as the primary defense.
const ( // Public: safe to display exactly as emitted. Public Sensitivity = "public" // Masked: safe to display only through a masking function (e.g. partial hash). Masked Sensitivity = "masked" // Secret: must never store or display raw. Only presence/status is surfaced. // Value field MUST be empty. DisplayValue is the safe representation. Secret Sensitivity = "secret" // Opaque: do not display at all; only existence may be acknowledged. Opaque Sensitivity = "opaque" )
Source Files