Documentation
¶
Overview ¶
Package kpi turns declared KPIs on §10 units and §13 tools (SPEC-ADDITIONS §16/§18) into gated improvement proposals: it measures a subject against the log of how it actually behaved — the failure-record log for units, the tool-run log for tools — and when a KPI's threshold is breached across enough independent time strata to trust it (§18.2), proposes a change to that subject. It never adopts one — the proposal is a human's to act on. Every function is pure; the command supplies the loaded inputs.
Index ¶
Constants ¶
const ( SubjectUnit = "unit" SubjectTool = "tool" )
Subject kinds, so a proposal names what it concerns (§16/§18).
const ( // MetricGroundedMiss is the per-unit error KPI: how many times an arc failed // *despite* the unit's scope being routed (a grounded miss, §19.2) — the unit's // guidance was present yet did not prevent the failure. MetricGroundedMiss = "grounded_miss" // MetricRunFailure is the per-tool error KPI: how many times a declared tool ran // and exited non-zero (§16/§18). MetricRunFailure = "run_failure" // MetricRunDuration is the per-tool latency KPI: a tool's mean run duration in // milliseconds, over the runs that started (§16/§18). MetricRunDuration = "run_duration_ms" )
Metric names the observation sources measure.
const MinStrata = 2
MinStrata is how many distinct time strata a breach must span before it is proposed (§18.2): the same "never adopt on one signal" replication axis as the routing-miss and lesson-promotion gates.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Observation ¶
Observation is a subject's measured value for one metric and the count of distinct time strata it was seen across — the replication axis a proposal gates on (§18.2).
type Proposal ¶
type Proposal struct {
Subject string `json:"subject"`
Kind string `json:"kind"`
Metric string `json:"metric"`
Observed float64 `json:"observed"`
Threshold float64 `json:"threshold"`
Strata int `json:"strata"`
}
Proposal is a degradation a crossed KPI earned (§16/§18): the subject (its id and kind) and metric, the observed value against the threshold, and the strata it replicated across. It is a proposed change, never an applied one.
func Propose ¶
Propose returns a proposal for each subject KPI whose matching observation breached its threshold across at least minStrata distinct strata (§18.2). A KPI with no matching observation is skipped — a declared indicator no source measures never fires. Pure; sorted by subject then metric.
type Subject ¶
type Subject struct {
ID string
Kind string
KPIs []adh.KPI
Observations []Observation
}
Subject bundles a tool or unit id, its Kind, the KPIs it declares, and the observations measured for it, so Propose can match each KPI to its metric's observation.
func ObserveTools ¶
ObserveTools measures each KPI-declaring tool from the tool-run log: a run_failure observation (the count of runs that ran and exited non-zero) and a run_duration_ms observation (the mean duration of runs that started), each with the distinct strata it spanned. A tool that declares no KPI is skipped, and a KPI naming neither metric simply never fires. Pure — the caller loads the registry and the run log.
func ObserveUnits ¶
func ObserveUnits(units []contextstore.Unit, records []failures.Record) []Subject
ObserveUnits measures each KPI-declaring unit's grounded_miss value from the failure-record log: the count of grounded-miss records whose scope (a label or path) overlaps the unit's, and the distinct strata among them. A unit that declares no KPI is skipped. Pure — the caller loads the units and records.
Source Files