explain

Documentation

Overview

Package explain produces user-facing "why did this fire" explanations for tln decisions. Tier 1 surfaces the rendered label, the conditions that satisfied the rule, and the observed fact values behind each one.

Persistence, temporal replay, and counter-factual queries are out of scope at this tier — see docs/design/0003-explainability.md for the roadmap.

Index

• func Render(d Decision) string
• func RenderAll(ds []Decision) string
• type Decision
• type Fact

Functions

func Render

func Render(d Decision) string

Render formats a Decision in the Tier-1 end-user view.

─────────────────────────────────────────────────────────────────
ACTION    Order 100 bags of Portland Cement 50kg
ITEM      Portland Cement 50kg  (stock item #808)
WHEN      Recommended 2026-05-27 09:14 UTC

WHY
  • Stock is critically low — 12 bags on hand, minimum is 50.
  • …

EVIDENCE
  Observed 2026-05-27 08:00  current_stock = 12
  …

CONFIDENCE  High
─────────────────────────────────────────────────────────────────

func RenderAll

func RenderAll(ds []Decision) string

RenderAll concatenates the Tier-1 view of every decision, with a trailing newline between blocks.

Types

type Decision

type Decision struct {
	// Identity
	BlockName  string    `json:"block"`
	BlockKind  string    `json:"kind"`           // "detect", "recommend", "forecast", "rule", …
	BlockFile  string    `json:"file,omitempty"` // source location for audit view
	BlockLine  int       `json:"line,omitempty"`
	EntityID   int       `json:"entity_id"`
	EntityName string    `json:"entity_name,omitempty"`
	FiredAt    time.Time `json:"fired_at"`

	// What the user sees
	Action   string   `json:"action,omitempty"`   // rendered label / suggest
	Why      []string `json:"why,omitempty"`      // bullet reasons, one per fired condition
	Evidence []Fact   `json:"evidence,omitempty"` // (attr, value, observed_at)

	// Cross-block chain
	TriggeredBy []Decision `json:"triggered_by,omitempty"` // upstream decisions
	Confidence  string     `json:"confidence,omitempty"`   // "High", "Medium", "Low", or ""
	Priority    string     `json:"priority,omitempty"`     // CRITICAL/HIGH/MEDIUM/LOW

	// Provenance — populated from the block's `confidence N` /
	// `source "..."` annotations (issue #3 layer-3). Score is the
	// rule's self-asserted confidence in [0, 1]; Source is opaque
	// metadata, typically describing how the rule was discovered
	// (e.g. "mined from 14 months of data, 47 matching cases").
	Score  *float64 `json:"score,omitempty"`
	Source string   `json:"source,omitempty"`
}

Decision is one block's firing — what happened, why, and on what evidence. Tier-1 explanations are constructed from values already in memory at evaluation time; no FactStore time-travel is required.

type Fact

type Fact struct {
	Attribute  string    `json:"attribute"`
	Value      any       `json:"value"`
	ObservedAt time.Time `json:"observed_at,omitempty"`
	Source     string    `json:"source,omitempty"`
}

Fact is one piece of evidence cited in a decision. ObservedAt is the time the planner *read* the value — until talon-db exposes per-datom transaction times, this is wall-clock at evaluation, not true fact observation time. The Source field is similarly best-effort.