trace

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 NewCollector() *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
  • func (e Emission) RenderValue() string
• type EmissionStatus
• type Sensitivity

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 NewCollector

func NewCollector() *Collector

NewCollector returns an initialized Collector.

func (*Collector) All

func (c *Collector) All() []Emission

All returns all emissions in emission order.

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

func (c *Collector) Emit(e Emission) error

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

func (c *Collector) ForDomain(domain string) []Emission

ForDomain returns all emissions for the given domain, in emission order.

func (*Collector) HasFailure

func (c *Collector) HasFailure(domain string) bool

HasFailure returns true if any emission in the given domain has StatusFail.

func (*Collector) MarkAllRendered

func (c *Collector) MarkAllRendered(domain string)

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

func (c *Collector) MarkRendered(e Emission)

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

func (c *Collector) Unrendered() []Emission

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

func (e Emission) RenderValue() string

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"
)