Documentation
¶
Overview ¶
Package core provides a deterministic TOC constraint analyzer.
The analyzer classifies pipeline stages from observation data and identifies the system constraint (drum) via hysteresis. It has no goroutines, no channels, no time.Now() — same inputs produce same outputs, enabling deterministic simulation replay.
Consumers call Analyzer.Step once per analysis window with StageObservation values for all stages. The analyzer returns a Diagnosis with per-stage classification and constraint identity.
Observations use abstract Work units (nanoseconds for runtime pipelines, ticks for simulations). The classifier only uses ratios (BusyWork/CapacityWork) so the unit doesn't matter for classification. All observations fed to a single Analyzer must use the same unit.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultThresholds = Thresholds{
BrokenError: 0.2,
StarvedIdle: 0.5,
BlockedBlocked: 0.3,
SaturatedBusy: 0.7,
SaturatedIdle: 0.3,
SaturatedBlock: 0.2,
HysteresisWindows: 3,
ConfidenceMin: 10,
}
Default classification thresholds (from Goldratt/TameFlow conventions).
Functions ¶
This section is empty.
Types ¶
type Analyzer ¶
type Analyzer struct {
// contains filtered or unexported fields
}
Analyzer is the deterministic constraint identifier. No goroutines, no time.Now(), no channels. Same inputs → same outputs.
Call Analyzer.Step once per analysis window with observations for all stages. The analyzer maintains hysteresis state between calls.
func NewAnalyzer ¶
NewAnalyzer creates a deterministic constraint analyzer.
func (*Analyzer) SetDrum ¶
SetDrum sets or clears the manual constraint override. Pass empty string to revert to automatic identification.
func (*Analyzer) Step ¶
func (a *Analyzer) Step(observations []StageObservation) Diagnosis
Step processes one analysis window. Returns classification for each stage and the current constraint identity.
Deterministic: same sequence of inputs produces the same sequence of outputs. No wall-clock dependency.
type Diagnosis ¶
type Diagnosis struct {
Constraint string // empty if none identified
Confidence float64 // 0.0-1.0
Stages []StageDiagnosis // ordered by input order
StarvationCount int // consecutive windows constraint was starved
}
Diagnosis is the output of one Analyzer.Step call. Contains per-stage classification and constraint identity.
type ObservationMask ¶
type ObservationMask uint32
ObservationMask distinguishes "not observed" from "observed zero." The classifier degrades gracefully when signals are missing — it skips checks that depend on absent data.
const ( HasIdle ObservationMask = 1 << iota // IdleWork is valid HasBlocked // BlockedWork is valid HasCompleted // Completions is valid HasFailed // Failures is valid HasQueue // QueueDepth is valid )
type Option ¶
type Option func(*Analyzer)
Option configures an Analyzer.
func WithDrum ¶
WithDrum sets a manual constraint override. Bypasses automatic identification — the analyzer will report this stage with confidence 1.0 on every Step.
func WithThresholds ¶
func WithThresholds(t Thresholds) Option
WithThresholds sets custom classification thresholds.
type StageDiagnosis ¶
type StageDiagnosis struct {
Stage string
State StageState
Utilization float64 // BusyWork / CapacityWork
IdleRatio float64 // IdleWork / CapacityWork (0 if !HasIdleRatio)
BlockedRatio float64 // BlockedWork / CapacityWork (0 if !HasBlockedRatio)
HasIdleRatio bool // false when observation lacked idle data
HasBlockedRatio bool // false when observation lacked blocked data
ErrorRate float64 // Failures / Completions, bounded [0,1]
QueueGrowth int64 // currQueueDepth - prevQueueDepth (count delta)
// Passthrough counts for consumer rate computation.
Completions int64
Failures int64
Arrivals int64
}
StageDiagnosis holds the classification for one stage. Contains ratios and counts, NOT rates. The caller converts to rates using their own time model (wall-clock or ticks).
type StageObservation ¶
type StageObservation struct {
Stage string // stage identifier
Mask ObservationMask // which optional fields are valid
// Work accounting over the analysis window.
// All in the same unit. Ratios are unit-independent.
BusyWork Work // time workers spent executing (service time)
IdleWork Work // time workers spent waiting for input
BlockedWork Work // time workers spent blocked on output
CapacityWork Work // total worker-capacity over the window
// Item counters over the window.
Arrivals int64 // items entering the stage
Completions int64 // items where processing finished (includes failures)
Failures int64 // subset of Completions that errored
// Point-in-time gauges (end of window).
QueueDepth int64 // items buffered at observation time
Workers int32 // active workers at observation time
}
StageObservation is the canonical input to the analyzer. One per stage per analysis window. Produced by runtime adapters (from cumulative counter deltas), simulation engines (from tick state), or network adapters (from protobuf).
Invariant: BusyWork + IdleWork + BlockedWork <= CapacityWork. Equality holds when all worker time is accounted for. Inequality when some time is untracked (e.g., scheduling overhead). Adapters should aim for equality; the analyzer tolerates inequality.
Failures is a subset of Completions. A completion that errors is still a completion.
type StageState ¶
type StageState int
StageState classifies a stage's operational state from one analysis window.
const ( StateUnknown StageState = iota // insufficient data StateHealthy // normal operation StateStarved // high idle, waiting for input StateBlocked // high output-blocked StateSaturated // high busy — constraint candidate StateBroken // elevated errors )
func (StageState) String ¶
func (s StageState) String() string
type Thresholds ¶
type Thresholds struct {
BrokenError float64 // error rate above this → Broken
StarvedIdle float64 // idle ratio above this → Starved
BlockedBlocked float64 // blocked ratio above this → Blocked
SaturatedBusy float64 // utilization above this → Saturated candidate
SaturatedIdle float64 // idle must be below this for Saturated
SaturatedBlock float64 // blocked must be below this for Saturated
HysteresisWindows int // consecutive windows before constraint confirmed
ConfidenceMin int64 // minimum completions for confident classification
}
Thresholds configures classification sensitivity.
type Work ¶
type Work uint64
Work represents abstract worker-time units. The actual unit (nanoseconds, ticks, etc.) is defined by the adapter producing observations. The classifier only uses ratios so the unit doesn't matter for classification. All observations fed to a single Analyzer must use the same unit.
Source Files