gatecore

package
v0.6.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 21, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package gatecore holds the pure logic of the seven-day aggregate release gate (#202): configuration, parsers, threshold evaluation, the projection fit, the result schema, and the Markdown renderer.

Nothing here talks to a process, a socket, or a clock it did not receive as an argument. The orchestrator (../main.go, build tag `gate`) drives the protocol and fills these structures in; CI compiles and unit-tests this package on the normal build so the calculations and the renderer are covered without running the three-hour protocol.

JSON is the source of truth. The Markdown report is rendered from the same Result value that is serialized to JSON, so the two cannot disagree.

Index

Constants

View Source 
const (
	TierMain        = "main"
	TierAggregate   = "aggregate"
	TierDLQ         = "dlq"
	TierWALTempTLS  = "wal_temp_tls"
	TierUnclassifid = "unclassified"
)

Tier names. These are the partitions the frozen contract assigns budgets to.

View Source 
const (
	CgroupNote = "cgroup-v2 transient scope with CPUQuota and MemoryMax enforced by the kernel; " +
		"cpu.max, memory.max, memory.peak and memory.events read back from the scope's cgroup files. " +
		"The load generator ran outside the scope."
	TasksetNote = "taskset-fallback: delegated cgroup control was unavailable, so the server was pinned " +
		"to dedicated cores with GOMAXPROCS matched. This run validates dedicated-core behavior, " +
		"NOT Kubernetes-style CPU quota throttling, and no kernel memory bound was applied — " +
		"the memory evidence is /proc VmHWM, not cgroup memory.peak."
)

CgroupNote and TasksetNote are the fixed statements each mode carries into the report. They are constants so no run can soften the fallback wording.

View Source 
const (
	MiB int64 = 1 << 20
	GiB int64 = 1 << 30
)

Byte-size helpers, spelled out so the numbers in DefaultThresholds read the way the contract does.

View Source 
const DropCounterWitness = "otelcontext_aggregate_input_points_total"

DropCounterWitness is a metric registered in the same place as the aggregate drop counters and always non-empty under load. Its presence is what lets the gate argue that an absent drop counter is an empty vector rather than a metric that was renamed out from under it.

View Source 
const HorizonWindows = 576

HorizonWindows is the two-day main-tier horizon, in completed five-minute windows: 2 days * 24 h * 12 windows/h.

View Source 
const LedgerSchema = "otelcontext.ack-ledger/v1"

LedgerSchema is the on-disk schema marker.

View Source 
const RecoveryLogMarker = "Aggregate store recovered"

RecoveryLogMarker is the message aggregate.LogRecovery emits.

View Source 
const Schema = "otelcontext.aggregate-7day-gate/v1"

Schema is the identifier stamped into every emitted report. Bump it when a field changes meaning, never when one is added.

View Source 
const WindowSecs int64 = 300

WindowSecs is the aggregate window width the whole platform is built on.

Variables

View Source 
var ErrTooFewSamples = errors.New("gatecore: too few samples to fit")

ErrTooFewSamples is returned by every fit that was not given enough data to answer honestly. The gate turns it into a FAILED assertion, never a blank report cell.

Functions

func Count 

func Count(v int64) string

Count renders an integer count.

func DefaultMetrics 

func DefaultMetrics() []string

DefaultMetrics is the series the gate records on every scrape. Anything the assertions read must be listed here.

func DefaultRequiredMetrics 

func DefaultRequiredMetrics() []string

DefaultRequiredMetrics is the subset whose absence fails the gate.

func DefaultServerEnv 

func DefaultServerEnv() map[string]string

DefaultServerEnv is the environment the server under test runs with.

AGGREGATE_SYNCHRONOUS is recorded in the report because it is exactly the knob that decides what the durability claim may say. NORMAL survives process and container kill on a surviving volume; it does not claim host power loss.

func Dur 

func Dur(d time.Duration) string

Dur renders a duration compactly.

func FindStringField 

func FindStringField(v any, key string) (string, bool)

FindStringField returns the first value of a named string key anywhere in a decoded document.

func Float 

func Float(v float64) string

Float renders a float with two decimals.

func HumanBytes 

func HumanBytes(b int64) string

HumanBytes renders a byte count with a binary unit.

func MainTierPhysicalBytes 

func MainTierPhysicalBytes(entries []FileEntry, spec ClassifySpec) int64

MainTierPhysicalBytes is the projection's measure of the main tier (Q4): the main database file plus its own -wal and -shm sidecars, which together hold the tables, the indexes, the FTS shadow tables and the free pages.

This deliberately overlaps the wal_temp_tls disk tier, because Q3 and Q4 draw the line in different places: Q3 budgets sidecars as their own partition, Q4 counts them as part of the physical footprint whose growth is projected. The report states both, and neither number is derived from the other.

func MetricDelta 

func MetricDelta(samples []MetricSample, phase, key string) (float64, bool)

MetricDelta returns last-minus-first for one flattened metric key across the samples of one phase.

func MetricDeltaPrefix 

func MetricDeltaPrefix(samples []MetricSample, phase, name string) (float64, bool)

MetricDeltaPrefix answers the same question as MetricDelta for a labelled metric family: keys are rendered as `name{...}`, so an exact lookup misses.

func MetricLast 

func MetricLast(samples []MetricSample, phase, key string) (float64, bool)

MetricLast returns the last observed value of a key within a phase.

func Ms 

func Ms(v float64) string

Ms renders a millisecond figure.

func ParseCgroupProcs 

func ParseCgroupProcs(s string) ([]int, error)

ParseCgroupProcs parses a cgroup.procs file into PIDs.

func ParseMemTotal 

func ParseMemTotal(meminfo string) (int64, error)

ParseMemTotal pulls MemTotal out of /proc/meminfo, in bytes.

func ParseMemoryEvents 

func ParseMemoryEvents(s string) (map[string]int64, error)

ParseMemoryEvents parses memory.events into its key/count pairs. The gate reads oom_kill out of it; a missing key is reported as absent, never as 0.

func ParseMemoryMax 

func ParseMemoryMax(s string) (bytes int64, bounded bool, err error)

ParseMemoryMax parses memory.max. "max" returns (-1, false, nil): unbounded, which the gate treats as a failed confinement rather than a huge limit.

func ParseMemoryPeak 

func ParseMemoryPeak(s string) (int64, error)

ParseMemoryPeak parses memory.peak, the high-water mark of the cgroup.

func ParseProcSelfCgroup 

func ParseProcSelfCgroup(s string) (string, error)

ParseProcSelfCgroup returns the unified-hierarchy path from a /proc/<pid>/cgroup body. On cgroup-v2 the line is "0::/some/path".

func ParseVmHWM 

func ParseVmHWM(status string) (int64, error)

ParseVmHWM pulls the peak resident set size out of /proc/<pid>/status and returns it in bytes. The kernel reports it in kB.

func Pct 

func Pct(v float64) string

Pct renders a ratio as a percentage with enough digits to see 99.9%.

func Rate 

func Rate(v float64) string

Rate renders a points-per-second figure.

func RenderMarkdown 

func RenderMarkdown(r *Result, jsonName string) string

RenderMarkdown renders the report.

func ReportBaseName 

func ReportBaseName(day time.Time) string

ReportBaseName is the file stem both artefacts share.

func ScanTruncated 

func ScanTruncated(v any) (found bool, isTrue bool)

ScanTruncated walks a decoded JSON document for `truncated` keys.

func Secs 

func Secs(v float64) string

Secs renders a duration in seconds.

func TopLevelScalars 

func TopLevelScalars(v any, keys []string) map[string]float64

TopLevelScalars pulls the requested numeric fields out of an object response. Missing keys are simply absent from the result, so the caller can tell "zero" from "not reported".

func WindowCoverage 

func WindowCoverage(pts []WindowPoint, expected []int64, windowSecs int64) (returned, missing, extra int)

WindowCoverage compares the window starts a surface returned against the window starts that were expected. Returned windows outside the expected set are counted as extra rather than silently ignored.

func WindowStartFor 

func WindowStartFor(t time.Time, windowSecs int64) int64

WindowStartFor aligns t down to the containing window.

func WindowTotals 

func WindowTotals(pts []WindowPoint, field string, windowSecs int64) map[int64]int64

WindowTotals indexes per-window points by aligned window start, summing any duplicates the surface happens to emit for one window.

func WriteLedger 

func WriteLedger(path string, l AckLedger) error

WriteLedger writes the document atomically and fsyncs both the file and its directory, so a copy that predates the kill is genuinely on the platter.

func WriteReports 

func WriteReports(dir string, day time.Time, r *Result) (jsonPath, mdPath string, err error)

WriteReports writes <dir>/<date>-aggregate-7day-gate.{json,md} and returns the two paths.

Types

type APICheck 

type APICheck struct {
	Name string `json:"name"`
	Path string `json:"path"`
	// Range selects the time window: "seven_day" spans the prefill plus the
	// live run, "crash_run" spans the crash run, "none" sends no start/end.
	Range string `json:"range"`
	// PerWindow marks a surface that returns one point per aggregate window,
	// which the gate checks for window coverage.
	PerWindow bool `json:"per_window"`
	// ExpectCoverage is the aggregate coverage marker this surface must
	// declare. Empty records whatever arrived without gating on it.
	//
	// It is a string rather than a "must be full" flag because a surface
	// declares whatever coverage its own answer earned, and the honest
	// declaration is not always "full". Encoding the expectation per
	// surface means a handler that legitimately downgrades its marker is
	// a config change here, not a gate that demands a lie.
	ExpectCoverage string `json:"expect_coverage"`
	// ScalarKeys are top-level numeric fields recorded from an object
	// response.
	ScalarKeys []string `json:"scalar_keys"`
}

APICheck is one HTTP query surface.

func DefaultAPIChecks 

func DefaultAPIChecks() []APICheck

DefaultAPIChecks is the HTTP completeness surface.

type AckLedger 

type AckLedger struct {
	Schema     string    `json:"schema"`
	StartedAt  time.Time `json:"started_at"`
	FlushedAt  time.Time `json:"flushed_at"`
	Final      bool      `json:"final"`
	WindowSecs int64     `json:"window_secs"`
	// FlushIntervalSec is how stale a non-final ledger can be. The gate needs
	// it to reason about a ledger recovered after a client-side crash.
	FlushIntervalSec float64                 `json:"flush_interval_sec"`
	Windows          []LedgerWindow          `json:"windows"`
	Totals           LedgerCounts            `json:"totals"`
	TotalsBySignal   map[string]LedgerCounts `json:"totals_by_signal"`
}

AckLedger is the on-disk document.

func LoadLedger 

func LoadLedger(path string) (AckLedger, error)

LoadLedger reads a ledger document.

func (*AckLedger) Summary 

func (l *AckLedger) Summary(path string) LedgerSummary

Summary reduces the ledger to what the report carries.

func (*AckLedger) Window 

func (l *AckLedger) Window(start int64) (LedgerWindow, bool)

Window returns the accounting for one window start, and whether it exists.

func (*AckLedger) WindowsIn 

func (l *AckLedger) WindowsIn(from, to int64) []LedgerWindow

WindowsIn returns the windows whose start lies in [from, to), sorted.

type Assertion 

type Assertion struct {
	ID          string `json:"id"`
	Category    string `json:"category"`
	Description string `json:"description"`
	Comparator  string `json:"comparator"`
	Threshold   string `json:"threshold"`
	Actual      string `json:"actual"`
	Pass        bool   `json:"pass"`
	// Basis names the evidence source. A basis that is not the contract's
	// primary source (a taskset-fallback memory number, say) sets Degraded.
	Basis    string `json:"basis"`
	Degraded bool   `json:"degraded"`
	Detail   string `json:"detail,omitempty"`
}

Assertion is one threshold decision. Every threshold in the frozen contract produces exactly one of these, pass or fail, never absent.

func Evaluate 

func Evaluate(r *Result) []Assertion

Evaluate scores a filled-in Result and returns the assertion table.

type BacklogTrend 

type BacklogTrend struct {
	Metric         string  `json:"metric"`
	Samples        int     `json:"samples"`
	First          float64 `json:"first"`
	Last           float64 `json:"last"`
	Min            float64 `json:"min"`
	Max            float64 `json:"max"`
	SlopePerMinute float64 `json:"slope_rows_per_minute"`
	SpanMinutes    float64 `json:"span_minutes"`
	// FittedGrowth is SlopePerMinute * SpanMinutes: what the trend says the
	// backlog grew by across the phase.
	FittedGrowth float64 `json:"fitted_growth_rows"`
	// EndpointGrowth is Last - First.
	EndpointGrowth float64 `json:"endpoint_growth_rows"`
	AllowanceRows  float64 `json:"allowance_rows"`
	R2             float64 `json:"r2"`
	Evaluated      bool    `json:"evaluated"`
	Flat           bool    `json:"flat"`
	Error          string  `json:"error,omitempty"`
}

BacklogTrend is the writer-backlog growth verdict over the sustained phase.

"No sustained backlog growth" cannot mean "the gauge never moved" — the delta log fills between finalize ticks by design. It means the trend over the phase does not walk upward: the fitted growth across the whole phase stays inside an allowance, and the last sample is not above the first by more than that allowance.

func EvaluateBacklog 

func EvaluateBacklog(metric string, samples []TimedValue, allowanceFraction, allowanceFloor float64, minSamples int) BacklogTrend

EvaluateBacklog fits the backlog series and decides flatness.

allowanceFraction is taken against the maximum observed value, floored at allowanceFloor rows, so the rule scales with whatever steady state the deployment actually runs at instead of a number someone remembered.

type Binaries 

type Binaries struct {
	Server  string `json:"server"`
	Loadsim string `json:"loadsim"`
	Prefill string `json:"prefill"`
}

Binaries are the three executables the protocol drives.

type CPUMax 

type CPUMax struct {
	Raw string `json:"raw"`
	// QuotaUsec is -1 when the quota is "max" (unbounded).
	QuotaUsec  int64   `json:"quota_usec"`
	PeriodUsec int64   `json:"period_usec"`
	Unbounded  bool    `json:"unbounded"`
	CPUs       float64 `json:"effective_cpus"`
}

CPUMax is a parsed cpu.max.

func ParseCPUMax 

func ParseCPUMax(s string) (CPUMax, error)

ParseCPUMax parses the contents of cpu.max: "<quota|max> <period>".

type CertificationConfig 

type CertificationConfig struct {
	Required bool `json:"required"`
}

CertificationConfig switches the historical diagnostic protocol into the strict release-candidate contract. Candidate paths and expected digests are supplied by the workflow flags because they do not exist until the signed draft release has been downloaded and verified.

type Classification 

type Classification struct {
	Bytes             map[string]int64
	Files             map[string][]string
	Total             int64
	Unclassified      int64
	UnclassifiedFiles []string
}

Classification is the walk reduced to tiers.

func Classify 

func Classify(entries []FileEntry, spec ClassifySpec) Classification

Classify partitions a data-directory walk into the contract's tiers.

Anything the spec does not account for lands in the unclassified bucket: it still counts toward the data-directory total (the volume pays for it either way) but it is named in the report instead of being quietly folded into a tier that happens to have headroom.

type ClassifySpec 

type ClassifySpec struct {
	// MainDBFile and AggregateDBFile are base names, e.g. "otelcontext.db".
	MainDBFile      string
	AggregateDBFile string
	// DLQDir and TLSDir are directory names relative to the data root.
	DLQDir string
	TLSDir string
}

ClassifySpec names the files and directories that anchor the tiers.

func DefaultClassifySpec 

func DefaultClassifySpec() ClassifySpec

DefaultClassifySpec matches the layout the gate configures the server with.

type Command 

type Command struct {
	Phase       string    `json:"phase"`
	Argv        []string  `json:"argv"`
	Dir         string    `json:"dir,omitempty"`
	StartedAt   time.Time `json:"started_at"`
	DurationSec float64   `json:"duration_sec"`
	ExitCode    int       `json:"exit_code"`
	LogPath     string    `json:"log_path,omitempty"`
	Error       string    `json:"error,omitempty"`
}

Command is one external invocation, recorded verbatim.

type Config 

type Config struct {
	RunID     string `json:"run_id"`
	RepoRoot  string `json:"repo_root"`
	WorkDir   string `json:"work_dir"`
	DataDir   string `json:"data_dir"`
	ReportDir string `json:"report_dir"`

	Binaries      Binaries            `json:"binaries"`
	Certification CertificationConfig `json:"certification"`
	HTTPAddr      string              `json:"http_addr"`
	GRPCAddr      string              `json:"grpc_addr"`
	MCPPath       string              `json:"mcp_path"`
	APIKey        string              `json:"api_key"`
	Confinement   ConfinementConfig   `json:"confinement"`
	Prefill       PrefillConfig       `json:"prefill"`
	Load          LoadConfig          `json:"load"`
	Sampling      SamplingConfig      `json:"sampling"`
	Queries       QueryConfig         `json:"queries"`
	Thresholds    Thresholds          `json:"thresholds"`

	// ServerEnv is the environment the server under test is started with. It
	// is recorded in full; AGGREGATE_SYNCHRONOUS in particular is a durability
	// claim and the report quotes it.
	ServerEnv map[string]string `json:"server_env"`

	ReadyTimeoutSec    float64        `json:"ready_timeout_sec"`
	ShutdownTimeoutSec float64        `json:"shutdown_timeout_sec"`
	Classify           TierSpecConfig `json:"tier_spec"`
}

Config is the gate's complete effective configuration. It is recorded verbatim in the report, so a run is reproducible from its own output.

LoadConfigFile unmarshals an operator's JSON on top of DefaultConfig(), so a config file states only what it changes and every unstated field is the frozen default rather than a zero value.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns the frozen protocol.

func LoadConfigFile 

func LoadConfigFile(path string) (Config, error)

LoadConfigFile overlays an operator's JSON on top of the defaults.

func (Config) Validate 

func (c Config) Validate() error

Validate refuses a configuration that cannot produce a scoreable run.

type Confinement 

type Confinement struct {
	Mode          ConfinementMode `json:"mode"`
	Unit          string          `json:"unit,omitempty"`
	ScopePath     string          `json:"scope_path,omitempty"`
	CPUMaxRaw     string          `json:"cpu_max_raw,omitempty"`
	CPUQuotaUsec  int64           `json:"cpu_quota_usec,omitempty"`
	CPUPeriodUsec int64           `json:"cpu_period_usec,omitempty"`
	EffectiveCPUs float64         `json:"effective_cpus"`
	MemoryMaxRaw  string          `json:"memory_max_raw,omitempty"`
	MemoryMaxByte int64           `json:"memory_max_bytes,omitempty"`
	TasksetCPUs   string          `json:"taskset_cpus,omitempty"`
	GOMAXPROCS    int             `json:"gomaxprocs,omitempty"`
	// Note states what this mode does and does not validate. Always present.
	Note string `json:"note"`
}

Confinement records the boundary the server actually ran inside.

type ConfinementConfig 

type ConfinementConfig struct {
	// Enabled false skips confinement entirely. The gate refuses to certify
	// such a run; it exists for dry runs of the plumbing.
	Enabled bool `json:"enabled"`
	// AllowFallback permits the taskset path when delegated cgroup control is
	// unavailable. The run is then marked taskset-fallback.
	AllowFallback   bool   `json:"allow_fallback"`
	CPUQuotaPercent int    `json:"cpu_quota_percent"`
	MemoryMax       string `json:"memory_max"`
	// FallbackCPUs is the taskset -c argument.
	FallbackCPUs       string `json:"fallback_cpus"`
	FallbackGOMAXPROCS int    `json:"fallback_gomaxprocs"`
	UnitPrefix         string `json:"unit_prefix"`
}

ConfinementConfig configures Q2.

type ConfinementMode 

type ConfinementMode string

ConfinementMode names how the server was bounded. 

const (
	// ConfinementCgroup is the sanctioned mode: a cgroup-v2 transient scope
	// with CPUQuota and MemoryMax, verified from the cgroup files.
	ConfinementCgroup ConfinementMode = "cgroup-scope"
	// ConfinementTaskset is the fallback: dedicated cores, no quota
	// throttling and no memory bound. It validates a different thing and the
	// report says so.
	ConfinementTaskset ConfinementMode = "taskset-fallback"
)

type Contribution 

type Contribution map[int64]int64

Contribution is one Export's point counts, keyed by the aligned window the DATA falls in. A single batch legitimately straddles two windows.

func (Contribution) Add 

func (c Contribution) Add(t time.Time, windowSecs int64)

Add records one point landing in the window containing t.

func (Contribution) Points 

func (c Contribution) Points() int64

Points is the total across every window.

type CrashBoundReport 

type CrashBoundReport struct {
	Evaluated  bool   `json:"evaluated"`
	Error      string `json:"error,omitempty"`
	Signal     string `json:"signal"`
	WindowSecs int64  `json:"window_secs"`

	CrashStartUnix int64 `json:"crash_start_unix"`
	CrashEndUnix   int64 `json:"crash_end_unix"`

	CompareFromUnix int64 `json:"compare_from_unix"`
	CompareToUnix   int64 `json:"compare_to_unix"`

	Windows              []WindowBound `json:"windows"`
	WindowsCompared      int           `json:"windows_compared"`
	WindowsExact         int           `json:"windows_exact"`
	WindowsCrashAffected int           `json:"windows_crash_affected"`
	WindowsFailed        int           `json:"windows_failed"`
	// WindowsBelowLower and WindowsAboveUpper split the failures by which
	// side of the permitted interval they fell out of. Below the lower bound
	// is acknowledged loss; above the upper bound is contributions that were
	// never sent.
	WindowsBelowLower int `json:"windows_below_lower"`
	WindowsAboveUpper int `json:"windows_above_upper"`
	// WindowsMissing counts windows the query surface returned no point for.
	WindowsMissing int `json:"windows_missing"`

	TotalAttempted int64 `json:"total_attempted"`
	TotalAcked     int64 `json:"total_acked"`
	TotalObserved  int64 `json:"total_observed"`
	// AmbiguityPoints is attempted - acked across the crash-affected windows:
	// the width of the interval the contract permits.
	AmbiguityPoints int64 `json:"ambiguity_points"`
	// AckedLossPoints is how far below the lower bound the observation fell.
	// Anything above zero is acknowledged loss and fails the gate.
	AckedLossPoints int64 `json:"acknowledged_loss_points"`

	Pass bool `json:"pass"`
}

CrashBoundReport is the whole per-window comparison.

func EvaluateCrashBounds 

func EvaluateCrashBounds(l *AckLedger, signal string, observed map[int64]int64,
	crashStart, crashEnd, compareFrom, compareTo int64) CrashBoundReport

EvaluateCrashBounds compares observed per-window totals against the ledger.

observed maps an aligned window start to the total the query surface reported for that window. Only windows in [compareFrom, compareTo) are compared — the orchestrator excludes the boundary windows a neighbouring phase could have contributed to.

type DiskResult 

type DiskResult struct {
	DataDir        string     `json:"data_dir"`
	MeasuredAt     time.Time  `json:"measured_at"`
	Tiers          []DiskTier `json:"tiers"`
	TotalBytes     int64      `json:"total_bytes"`
	TotalLimit     int64      `json:"total_limit_bytes"`
	FreeBytes      int64      `json:"free_bytes"`
	FreeMinBytes   int64      `json:"free_bytes_required"`
	UnclassifiedB  int64      `json:"unclassified_bytes"`
	UnclassifiedFs []string   `json:"unclassified_files,omitempty"`
	// GaugeBytes is the server's own attribution, read from
	// otelcontext_disk_component_bytes. It corroborates the filesystem walk;
	// the walk is what the gate asserts on.
	GaugeBytes     map[string]float64 `json:"gauge_component_bytes"`
	GaugeHighWater map[string]float64 `json:"gauge_component_high_water_bytes"`
}

DiskResult is the measured data-directory footprint, by tier.

type DiskSample 

type DiskSample struct {
	At time.Time `json:"at"`
	// PhysicalBytes is the allocated size of every file in the tier: main DB
	// plus its -wal and -shm sidecars. Free pages inside the file count,
	// because the operator's volume pays for them.
	PhysicalBytes int64 `json:"physical_bytes"`
	// ChargedBytes is the logical byte count the server says it wrote, if a
	// counter for it was configured. Optional; report-only.
	ChargedBytes int64 `json:"charged_bytes,omitempty"`
	// Windows is completed five-minute windows since the steady portion began.
	Windows float64 `json:"windows"`
}

DiskSample is one main-tier measurement taken during the steady portion.

type DiskTier 

type DiskTier struct {
	Name       string   `json:"name"`
	Bytes      int64    `json:"bytes"`
	LimitBytes int64    `json:"limit_bytes"`
	Files      []string `json:"files,omitempty"`
	// Projected marks a tier whose limit is checked against the projection
	// rather than against the demonstrated bytes.
	Projected bool `json:"projected"`
}

DiskTier is one asserted partition of the data directory.

type FileEntry 

type FileEntry struct {
	// RelPath is slash-separated and relative to the data directory root.
	RelPath string `json:"rel_path"`
	Bytes   int64  `json:"bytes"`
}

FileEntry is one file found under the data directory.

type Fit 

type Fit struct {
	N         int     `json:"n"`
	Slope     float64 `json:"slope"`
	Intercept float64 `json:"intercept"`
	// SlopeStdErr is the standard error of the slope estimate. Zero when the
	// fit is exact or when n == 2 (no residual degrees of freedom).
	SlopeStdErr float64 `json:"slope_std_err"`
	// R2 is the coefficient of determination. A projection quoted off a poor
	// fit is a guess wearing a number, so the report shows it.
	R2    float64 `json:"r2"`
	XSpan float64 `json:"x_span"`
	YMin  float64 `json:"y_min"`
	YMax  float64 `json:"y_max"`
}

Fit is an ordinary-least-squares line plus the uncertainty of its slope.

func FitLine 

func FitLine(pts []Point, minSamples int) (Fit, error)

FitLine performs an ordinary-least-squares fit of y on x.

It is the single implementation behind both the main-tier projection and the backlog-growth trend, so the two cannot drift apart.

func (Fit) UpperSlope 

func (f Fit) UpperSlope(z float64) float64

UpperSlope is the conservative slope the gate projects on: the point estimate pushed out by z standard errors. Never below the point estimate.

type HostInfo 

type HostInfo struct {
	Hostname       string `json:"hostname"`
	Kernel         string `json:"kernel"`
	OS             string `json:"os"`
	Arch           string `json:"arch"`
	NumCPU         int    `json:"num_cpu"`
	TotalMemBytes  int64  `json:"total_mem_bytes"`
	DataDir        string `json:"data_dir"`
	DataDirFSType  string `json:"data_dir_fs_type"`
	DataDirDevice  string `json:"data_dir_device"`
	DataDirMount   string `json:"data_dir_mountpoint"`
	DataDirTotal   int64  `json:"data_dir_total_bytes"`
	DataDirFreeMin int64  `json:"data_dir_free_bytes_min"`
	CgroupV2       bool   `json:"cgroup_v2"`
}

HostInfo is the machine the numbers came off.

type LatencySentinelProof 

type LatencySentinelProof struct {
	Service   string           `json:"service"`
	LowCount  int              `json:"low_count"`
	LowMS     float64          `json:"low_ms"`
	TailCount int              `json:"tail_count"`
	TailMS    float64          `json:"tail_ms"`
	Surfaces  []LatencySurface `json:"surfaces"`
}

LatencySentinelProof carries the contradictory 989x10ms + 11x1000ms fixture through every aggregate consumer named by the release contract.

type LatencySurface 

type LatencySurface struct {
	Name               string  `json:"name"`
	ValueMS            float64 `json:"value_ms"`
	Status             string  `json:"status"`
	Method             string  `json:"method"`
	SampleCount        uint64  `json:"sample_count"`
	SketchScale        uint8   `json:"sketch_scale"`
	RelativeErrorBound float64 `json:"relative_error_bound"`
	Degraded           bool    `json:"degraded"`
	Collapsed          bool    `json:"collapsed"`
	Saturations        uint64  `json:"saturations"`
	Error              string  `json:"error,omitempty"`
}

LatencySurface is one consumer's value and the provenance that bounds it.

type LedgerCounts 

type LedgerCounts struct {
	AttemptedPoints   int64 `json:"attempted_points"`
	AckedPoints       int64 `json:"acked_points"`
	AttemptedRequests int64 `json:"attempted_requests"`
	AckedRequests     int64 `json:"acked_requests"`
}

LedgerCounts is one bucket of contribution accounting.

Attempted is incremented before the Export call leaves; Acked only after it returns nil. Attempted >= Acked always, and the difference is exactly the ambiguity the at-least-once contract permits.

func (*LedgerCounts) Add 

func (c *LedgerCounts) Add(o LedgerCounts)

Add folds o into c.

func (LedgerCounts) Exact 

func (c LedgerCounts) Exact() bool

Exact reports whether the bucket carries no ambiguity: every attempted contribution was acknowledged, so the expected total is a single number rather than a range.

type LedgerRecorder 

type LedgerRecorder struct {
	// contains filtered or unexported fields
}

LedgerRecorder accumulates the ledger in memory. It is safe for concurrent use by every emitter goroutine.

func NewLedgerRecorder 

func NewLedgerRecorder(windowSecs int64, flushInterval time.Duration, now time.Time) *LedgerRecorder

NewLedgerRecorder returns a recorder aligned to windowSecs (0 means the platform default of 300).

func (*LedgerRecorder) Ack 

func (r *LedgerRecorder) Ack(c Contribution, signal string)

Ack records the points of an Export that returned nil. The caller passes the same Contribution it passed to Attempt, so the two sides of the bound can never land in different windows.

func (*LedgerRecorder) Attempt 

func (r *LedgerRecorder) Attempt(c Contribution, signal string)

Attempt records the points of an Export that is about to be sent.

The request counter is incremented in every window the batch contributed to, so "requests" here means "requests that touched this window", not a partition of the call count.

func (*LedgerRecorder) Snapshot 

func (r *LedgerRecorder) Snapshot(now time.Time, final bool) AckLedger

Snapshot renders the current accounting as an on-disk document.

type LedgerSummary 

type LedgerSummary struct {
	Present          bool         `json:"present"`
	Schema           string       `json:"schema,omitempty"`
	Final            bool         `json:"final"`
	FlushedAt        time.Time    `json:"flushed_at"`
	FlushIntervalSec float64      `json:"flush_interval_sec"`
	WindowSecs       int64        `json:"window_secs"`
	Windows          int          `json:"window_count"`
	FirstWindow      int64        `json:"first_window"`
	LastWindow       int64        `json:"last_window"`
	Totals           LedgerCounts `json:"totals"`

	// PreKillCopyAt and PreKillCopyPath record the snapshot the orchestrator
	// took of the on-disk ledger immediately before sending SIGKILL. Its
	// existence is the evidence that the ledger was persisted before the
	// crash rather than reconstructed after it.
	PreKillCopyAt    time.Time `json:"pre_kill_copy_at"`
	PreKillCopyPath  string    `json:"pre_kill_copy_path,omitempty"`
	PreKillCopyBytes int64     `json:"pre_kill_copy_bytes"`
}

LedgerSummary is the digest of the ACK ledger carried into the report.

type LedgerWindow 

type LedgerWindow struct {
	WindowStart int64                   `json:"window_start"`
	Counts      LedgerCounts            `json:"counts"`
	BySignal    map[string]LedgerCounts `json:"by_signal"`
}

LedgerWindow is one aggregate window's accounting.

func (LedgerWindow) SignalCounts 

func (w LedgerWindow) SignalCounts(signal string) LedgerCounts

SignalCounts returns one signal's accounting for one window.

type LoadConfig 

type LoadConfig struct {
	// Profile owns the service count and per-signal rates when set; Services
	// applies only when Profile is empty.
	Profile         string  `json:"profile"`
	Services        int     `json:"services"`
	SettleSec       float64 `json:"settle_sec"`
	SustainedSec    float64 `json:"sustained_sec"`
	BurstSpec       string  `json:"burst_spec"`
	BatchIntervalMs int     `json:"batch_interval_ms"`
	CallTimeoutSec  float64 `json:"call_timeout_sec"`
	TenantID        string  `json:"tenant_id"`

	// PostBurstAllowanceSec is the interval the contract allows the system to
	// recover in after the burst. The recovery probe spends it in loadsim's
	// settle phase, so its latencies are recorded as evidence but excluded
	// from the graded percentile.
	PostBurstAllowanceSec float64 `json:"post_burst_allowance_sec"`
	// PostBurstProofSec is the graded window that begins once the allowance
	// has elapsed.
	PostBurstProofSec float64 `json:"post_burst_proof_sec"`

	// QuietGapSec separates two load runs so no aggregate window carries
	// contributions from both. It must exceed one window.
	QuietGapSec float64 `json:"quiet_gap_sec"`

	// CrashRunSec is the length of the run during which the server is killed;
	// CrashAtSec is how far into its sustained phase the kill lands.
	CrashRunSec       float64 `json:"crash_run_sec"`
	CrashRunSettleSec float64 `json:"crash_run_settle_sec"`
	CrashAtSec        float64 `json:"crash_at_sec"`
	// LedgerFlushSec is how often the load generator fsyncs the ACK ledger,
	// so a copy predating the kill always exists on disk.
	LedgerFlushSec float64 `json:"ledger_flush_sec"`
}

LoadConfig configures every loadsim invocation.

type LoadPhase 

type LoadPhase struct {
	Present      bool    `json:"present"`
	Source       string  `json:"source,omitempty"`
	Phase        string  `json:"phase,omitempty"`
	DurationSec  float64 `json:"duration_sec"`
	Samples      int64   `json:"ack_samples"`
	P50Ms        float64 `json:"ack_p50_ms"`
	P90Ms        float64 `json:"ack_p90_ms"`
	P99Ms        float64 `json:"ack_p99_ms"`
	P999Ms       float64 `json:"ack_p999_ms"`
	MaxMs        float64 `json:"ack_max_ms"`
	PointsSent   int64   `json:"points_sent"`
	PointsAcked  int64   `json:"points_acked"`
	PointsPerSec float64 `json:"points_acked_per_sec"`
	RequestsOK   int64   `json:"requests_ok"`
	RequestsErr  int64   `json:"requests_err"`
	Exhausted    int64   `json:"resource_exhausted"`
	Unavailable  int64   `json:"unavailable"`
	OtherErrors  int64   `json:"other_errors"`
	FirstErr     string  `json:"first_error,omitempty"`
}

LoadPhase is one measured phase pulled out of a loadsim report.

func (LoadPhase) AckRatio 

func (p LoadPhase) AckRatio() float64

AckRatio is acked/sent. Zero sent is reported as 0, never as 1: a phase that sent nothing did not achieve 100% delivery.

type LoadResults 

type LoadResults struct {
	// Sustained and Burst come from the main run (settle -> sustained ->
	// burst). PostBurst* come from the recovery probe whose settle window IS
	// the two-minute recovery allowance.
	Sustained LoadPhase `json:"sustained"`
	Burst     LoadPhase `json:"burst"`
	// PostBurstAllowance is the 0-120s window after burst end. Reported as
	// evidence, deliberately NOT gated: it is the interval the contract
	// allows the system to still be recovering in.
	PostBurstAllowance LoadPhase `json:"post_burst_allowance"`
	// PostBurstProof is the 120-240s window after burst end. Gated against
	// the sustained bounds.
	PostBurstProof LoadPhase `json:"post_burst_proof"`
	// CrashRun is the run during which the server is killed. Its latency
	// numbers are not gated; its ACK ledger is the recovery evidence.
	CrashRun LoadPhase `json:"crash_run"`

	ReportPaths map[string]string `json:"report_paths"`
	LedgerPath  string            `json:"ack_ledger_path"`
	Ledger      LedgerSummary     `json:"ack_ledger_summary"`
}

LoadResults collects every loadsim invocation the protocol makes.

type LoadsimLatency 

type LoadsimLatency struct {
	Samples int64   `json:"samples"`
	MinMs   float64 `json:"min_ms"`
	P50Ms   float64 `json:"p50_ms"`
	P90Ms   float64 `json:"p90_ms"`
	P95Ms   float64 `json:"p95_ms"`
	P99Ms   float64 `json:"p99_ms"`
	P999Ms  float64 `json:"p999_ms"`
	MaxMs   float64 `json:"max_ms"`
	MeanMs  float64 `json:"mean_ms"`
}

LoadsimLatency is one (phase, signal) latency summary.

type LoadsimPhase 

type LoadsimPhase struct {
	Phase        string                    `json:"phase"`
	DurationSec  float64                   `json:"duration_sec"`
	All          LoadsimLatency            `json:"ack_latency_all_signals"`
	BySignal     map[string]LoadsimLatency `json:"ack_latency_by_signal"`
	PointsSent   int64                     `json:"points_sent"`
	PointsAcked  int64                     `json:"points_acked"`
	PointsPerSec float64                   `json:"points_acked_per_sec"`
	RequestsOK   int64                     `json:"requests_ok"`
	RequestsErr  int64                     `json:"requests_err"`
	Exhausted    int64                     `json:"resource_exhausted"`
	Unavailable  int64                     `json:"unavailable"`
	OtherErrors  int64                     `json:"other_errors"`
}

LoadsimPhase is one phase's accounting.

type LoadsimReport 

type LoadsimReport struct {
	StartedAt string         `json:"started_at"`
	EndedAt   string         `json:"ended_at"`
	Config    map[string]any `json:"config"`
	Phases    []LoadsimPhase `json:"phases"`
	FirstErr  string         `json:"first_error"`
}

LoadsimReport is the whole document.

func LoadLoadsimReport 

func LoadLoadsimReport(path string) (LoadsimReport, error)

LoadLoadsimReport reads a loadsim report from disk.

func (LoadsimReport) PhaseNamed 

func (rep LoadsimReport) PhaseNamed(source, phase string) LoadPhase

PhaseNamed extracts one phase as the report's LoadPhase shape. A phase that recorded no ACK samples is treated as absent: it measured nothing.

type MCPToolCall 

type MCPToolCall struct {
	Tool           string  `json:"tool"`
	Arguments      string  `json:"arguments"`
	Status         int     `json:"status"`
	DurationSec    float64 `json:"duration_sec"`
	RPCError       string  `json:"rpc_error,omitempty"`
	TruncatedFound bool    `json:"truncated_flag_found"`
	TruncatedTrue  bool    `json:"truncated_true"`
	ResultBytes    int     `json:"result_bytes"`
	Error          string  `json:"error,omitempty"`
	PrimaryText    string  `json:"-"`
}

MCPToolCall is one aggregate-backed MCP tool answered over the full range.

type MCPToolSpec 

type MCPToolSpec struct {
	Name      string         `json:"name"`
	Arguments map[string]any `json:"arguments"`
	// RangeArgs, when set, injects the seven-day range into these argument
	// keys at call time (start/end style tools).
	StartArg string `json:"start_arg,omitempty"`
	EndArg   string `json:"end_arg,omitempty"`
	// SinceArg, when set, receives an RFC3339 timestamp seven days back.
	SinceArg string `json:"since_arg,omitempty"`
}

MCPToolSpec is one explicitly named aggregate-backed MCP tool.

func AggregateMCPTools 

func AggregateMCPTools() []MCPToolSpec

AggregateMCPTools is the explicit list of aggregate-backed MCP tools the gate exercises over the full seven-day range. Named, not counted.

type MemoryIncarnate 

type MemoryIncarnate struct {
	Label      string `json:"label"`
	PID        int    `json:"pid"`
	PeakBytes  int64  `json:"peak_bytes"`
	VmHWMBytes int64  `json:"vmhwm_bytes"`
	OOMKills   int64  `json:"oom_kills"`
	ScopePath  string `json:"scope_path,omitempty"`
}

MemoryIncarnate is one server process lifetime's memory evidence. The gate restarts the server once (after the kill), so there are two of these.

type MemoryResult 

type MemoryResult struct {
	Basis          string            `json:"basis"`
	PeakBytes      int64             `json:"peak_bytes"`
	PeakSource     string            `json:"peak_source"`
	LimitBytes     int64             `json:"limit_bytes"`
	OOMKills       int64             `json:"oom_kills"`
	OOMSource      string            `json:"oom_source"`
	OOMObserved    bool              `json:"oom_counter_observed"`
	VmHWMBytes     int64             `json:"vmhwm_bytes"`
	PerIncarnation []MemoryIncarnate `json:"per_incarnation"`
}

MemoryResult is the memory evidence. Basis names which number is load bearing in this confinement mode.

type MetricSample 

type MetricSample struct {
	At     time.Time          `json:"t"`
	Phase  string             `json:"phase"`
	Values map[string]float64 `json:"v"`
}

MetricSample is one Prometheus scrape, reduced to the metrics the gate asserts on.

type MetricVerdict 

type MetricVerdict int

MetricVerdict says how a metric key was found, or why it was not. 

const (
	// MetricPresent means at least one sample carried the key.
	MetricPresent MetricVerdict = iota
	// MetricEmptyVector means the key was absent but its witness was present:
	// a registered counter vector with no children, i.e. one that never fired.
	MetricEmptyVector
	// MetricAbsent means neither the key nor its witness was found. The gate
	// cannot reason about it and must fail.
	MetricAbsent
)

func MetricDeltaWitnessed 

func MetricDeltaWitnessed(samples []MetricSample, phase, key, witness string) (float64, MetricVerdict)

MetricDeltaWitnessed is MetricDelta with the empty-vector argument attached.

client_golang emits nothing at all — not even HELP or TYPE — for a CounterVec with no child series. A drop counter that correctly never fired is therefore indistinguishable from one that was deleted, unless something else proves the family is still registered. The witness is that something.

type Phase 

type Phase struct {
	Name        string    `json:"name"`
	StartedAt   time.Time `json:"started_at"`
	EndedAt     time.Time `json:"ended_at"`
	DurationSec float64   `json:"duration_sec"`
	Completed   bool      `json:"completed"`
	Detail      string    `json:"detail,omitempty"`
	Error       string    `json:"error,omitempty"`
}

Phase is one step of the protocol.

type Point 

type Point struct {
	X float64
	Y float64
}

Point is one (x, y) observation for the shared least-squares fit.

type PrefillConfig 

type PrefillConfig struct {
	Enabled bool   `json:"enabled"`
	Windows int    `json:"windows"`
	Workers int    `json:"workers"`
	DBPath  string `json:"db_path"`
}

PrefillConfig configures the deterministic seven-day store-level prefill.

type Projection 

type Projection struct {
	Evaluated  bool   `json:"evaluated"`
	Label      string `json:"label"`
	Error      string `json:"error,omitempty"`
	MetricNote string `json:"metric_note,omitempty"`

	Samples      []DiskSample `json:"samples"`
	SampleCount  int          `json:"sample_count"`
	FirstAt      time.Time    `json:"first_sample_at"`
	LastAt       time.Time    `json:"last_sample_at"`
	ObservedMin  int64        `json:"observed_min_bytes"`
	ObservedMax  int64        `json:"observed_max_bytes"`
	WindowsSpan  float64      `json:"windows_observed"`
	HorizonWinds int          `json:"horizon_windows"`

	Fit                Fit     `json:"fit"`
	BytesPerWindow     float64 `json:"physical_bytes_per_window"`
	UpperBytesPerWinds float64 `json:"physical_bytes_per_window_upper"`
	ZScore             float64 `json:"upper_estimate_z"`

	ProjectedBytes      int64 `json:"projected_bytes"`
	ProjectedUpperBytes int64 `json:"projected_upper_bytes"`

	// AmplificationFactor is physical growth / charged growth over the same
	// samples. Report-only: it is NEVER multiplied into the projection.
	AmplificationMeasured bool    `json:"amplification_measured"`
	ChargedBytesPerWindow float64 `json:"charged_bytes_per_window,omitempty"`
	AmplificationFactor   float64 `json:"amplification_factor,omitempty"`
}

Projection is the labelled two-day main-tier estimate.

func FitProjection 

func FitProjection(samples []DiskSample, horizonWindows int, z float64, minSamples int) Projection

FitProjection turns steady-portion samples into the labelled projection.

horizonWindows is the retention horizon of the tier in completed windows (576 for the two-day main tier). z is how many slope standard errors the conservative upper estimate is pushed out by.

type PromSample 

type PromSample struct {
	Name   string            `json:"name"`
	Labels map[string]string `json:"labels,omitempty"`
	Value  float64           `json:"value"`
}

PromSample is one exposed series.

func (PromSample) Key 

func (s PromSample) Key() string

Key renders the sample's stable identity.

type PromSamples 

type PromSamples []PromSample

PromSamples is a scrape.

func ParsePrometheusText 

func ParsePrometheusText(body string) (PromSamples, error)

ParsePrometheusText parses an exposition-format body.

Malformed lines are an error, not a shrug: a scrape the gate cannot read is a scrape the gate must not score.

func (PromSamples) ByLabel 

func (ps PromSamples) ByLabel(name, label string) map[string]float64

ByLabel indexes one metric's series by the value of one label, summing duplicates.

func (PromSamples) Flatten 

func (ps PromSamples) Flatten(names []string) map[string]float64

Flatten renders the scrape as the flat key/value map a MetricSample carries, keeping only the requested metric names. Keys are `name` for unlabelled series and `name{k="v",...}` for labelled ones, with labels sorted so the key is stable across scrapes.

func (PromSamples) Get 

func (ps PromSamples) Get(name string, labels map[string]string) (float64, bool)

Get returns the value of the series matching every supplied label.

func (PromSamples) Sum 

func (ps PromSamples) Sum(name string) (total float64, found bool)

Sum totals every series with the given name. found is false when the metric is absent entirely — which the gate treats as a failure, not as zero.

type Provenance 

type Provenance struct {
	CommitSHA             string            `json:"commit_sha"`
	ExpectedCommitSHA     string            `json:"expected_commit_sha,omitempty"`
	CandidateTag          string            `json:"candidate_tag,omitempty"`
	TagCommitSHA          string            `json:"tag_commit_sha,omitempty"`
	Branch                string            `json:"branch"`
	DirtyTree             bool              `json:"dirty_tree"`
	DirtyFiles            []string          `json:"dirty_files,omitempty"`
	GoVersion             string            `json:"go_version"`
	BinarySHA256          map[string]string `json:"binary_sha256"`
	ExpectedServerSHA256  string            `json:"expected_server_sha256,omitempty"`
	ArchivePath           string            `json:"archive_path,omitempty"`
	ArchiveSHA256         string            `json:"archive_sha256,omitempty"`
	ExpectedArchiveSHA256 string            `json:"expected_archive_sha256,omitempty"`
	ConfigPath            string            `json:"config_path,omitempty"`
	ConfigSHA256          string            `json:"config_sha256,omitempty"`
	ServerVersion         string            `json:"server_version,omitempty"`
	BuiltAt               time.Time         `json:"built_at"`
	OrchestratorPID       int               `json:"orchestrator_pid"`
}

Provenance identifies exactly what was measured.

type QueryCheck 

type QueryCheck struct {
	Name           string  `json:"name"`
	URL            string  `json:"url"`
	Status         int     `json:"status"`
	DurationSec    float64 `json:"duration_sec"`
	Coverage       string  `json:"coverage,omitempty"`
	CoverageSource string  `json:"coverage_source,omitempty"`
	// CoverageExpected is the marker this surface was required to declare.
	// Empty means the marker was recorded but not gated.
	CoverageExpected string `json:"coverage_expected,omitempty"`
	TruncatedFound   bool   `json:"truncated_flag_found"`
	TruncatedTrue    bool   `json:"truncated_true"`
	// WindowsReturned and WindowsExpected apply to the per-window surfaces.
	WindowsReturned int                `json:"windows_returned,omitempty"`
	WindowsExpected int                `json:"windows_expected,omitempty"`
	MissingWindows  int                `json:"missing_windows,omitempty"`
	ExtraWindows    int                `json:"extra_windows,omitempty"`
	Scalars         map[string]float64 `json:"scalars,omitempty"`
	ExpectedScalars map[string]float64 `json:"expected_scalars,omitempty"`
	BodyBytes       int                `json:"body_bytes"`
	Error           string             `json:"error,omitempty"`
}

QueryCheck is one HTTP query surface answered over the seven-day range.

type QueryConfig 

type QueryConfig struct {
	API      []APICheck    `json:"api"`
	MCPTools []MCPToolSpec `json:"mcp_tools"`
	Timeout  float64       `json:"timeout_sec"`
}

QueryConfig names the completeness surfaces. The MCP tools are listed explicitly here rather than implied by a count, so the report can say which five answered.

type QueryLatencyCheck 

type QueryLatencyCheck struct {
	Name          string    `json:"name"`
	URL           string    `json:"url"`
	Status        int       `json:"status"`
	ColdSeconds   float64   `json:"cold_seconds"`
	ColdCache     string    `json:"cold_cache,omitempty"`
	WarmSeconds   []float64 `json:"warm_seconds,omitempty"`
	WarmCacheHits int       `json:"warm_cache_hits,omitempty"`
	WarmP50       float64   `json:"warm_p50_seconds,omitempty"`
	WarmP95       float64   `json:"warm_p95_seconds,omitempty"`
	WarmMax       float64   `json:"warm_max_seconds,omitempty"`
	Error         string    `json:"error,omitempty"`
}

QueryLatencyCheck records the first uncached request and the sequential warm samples for one user-facing surface.

type QueryResults 

type QueryResults struct {
	PrefillRangeStart time.Time            `json:"prefill_range_start"`
	PrefillRangeEnd   time.Time            `json:"prefill_range_end"`
	PrefillWindows    int                  `json:"prefill_windows_expected"`
	PrefillSeries     int                  `json:"prefill_series"`
	PrefillServices   int                  `json:"prefill_services"`
	Checks            []QueryCheck         `json:"checks"`
	MCPTools          []MCPToolCall        `json:"mcp_tools"`
	LatencyChecks     []QueryLatencyCheck  `json:"latency_checks"`
	LatencySentinel   LatencySentinelProof `json:"latency_sentinel"`
}

QueryResults is the completeness evidence.

type RecoveryLogStats 

type RecoveryLogStats struct {
	Found            bool
	Line             string
	Path             string
	FinalizedWindows int
	ReplayedRows     int
	ReplayedSeries   int
	SeededBaselines  int
	SkippedSeries    int
	Duration         time.Duration
}

RecoveryLogStats is what the log line carries.

func ParseRecoveryLog 

func ParseRecoveryLog(body string) (RecoveryLogStats, error)

ParseRecoveryLog scans a slog text-handler stream for the recovery summary and returns the LAST one, so a log that spans several server incarnations yields the most recent recovery.

type RecoveryResult 

type RecoveryResult struct {
	KilledAt         time.Time `json:"killed_at"`
	KillSignal       string    `json:"kill_signal"`
	KilledPID        int       `json:"killed_pid"`
	RestartedAt      time.Time `json:"restarted_at"`
	ReadyAt          time.Time `json:"ready_at"`
	TimeToReadySec   float64   `json:"time_to_ready_sec"`
	ReadyObserved    bool      `json:"ready_observed"`
	CrashIntervalSec float64   `json:"crash_interval_sec"`

	// Stats come from the server's own recovery log line. SkippedSeries has
	// no Prometheus gauge (see Gaps), so the log is the only source.
	StatsSource      string  `json:"stats_source"`
	StatsFound       bool    `json:"stats_found"`
	FinalizedWindows int     `json:"finalized_windows"`
	ReplayedRows     int     `json:"replayed_rows"`
	ReplayedSeries   int     `json:"replayed_series_windows"`
	SeededBaselines  int     `json:"seeded_baselines"`
	SkippedSeries    int     `json:"skipped_series"`
	DurationSec      float64 `json:"recovery_duration_sec"`

	// Bounds is the per-window at-least-once comparison across the whole
	// crash run: exact where the ledger says acked == attempted, a range
	// across the crash interval.
	Bounds CrashBoundReport `json:"crash_bounds"`
}

RecoveryResult is the kill -9 phase outcome.

type Result 

type Result struct {
	Schema      string    `json:"schema"`
	GateVersion string    `json:"gate_version"`
	RunID       string    `json:"run_id"`
	StartedAt   time.Time `json:"started_at"`
	EndedAt     time.Time `json:"ended_at"`
	DurationSec float64   `json:"duration_sec"`

	// Passed is the gate verdict: every assertion passed and every phase
	// completed. It is never true while Failures is non-empty.
	Passed   bool     `json:"passed"`
	Failures []string `json:"failures"`

	Provenance  Provenance        `json:"provenance"`
	Host        HostInfo          `json:"host"`
	Confinement Confinement       `json:"confinement"`
	Config      Config            `json:"effective_config"`
	ServerEnv   map[string]string `json:"server_env"`

	Phases   []Phase   `json:"phases"`
	Commands []Command `json:"commands"`

	Load       LoadResults    `json:"load"`
	Recovery   RecoveryResult `json:"recovery"`
	Memory     MemoryResult   `json:"memory"`
	Disk       DiskResult     `json:"disk"`
	Projection Projection     `json:"main_tier_projection"`
	Queries    QueryResults   `json:"queries"`
	Backlog    BacklogTrend   `json:"backlog_trend"`

	// MetricSeries is the sampled Prometheus evidence behind the trend and
	// projection assertions. Keys are `name` or `name{label="value"}`.
	MetricSeries []MetricSample `json:"metric_series"`

	// Gaps records things the gate needed that the server does not expose.
	// A gap is evidence about the platform, not an excuse: an assertion that
	// depends on a gap fails unless it has a sanctioned degraded basis.
	Gaps []string `json:"metric_gaps"`

	Assertions []Assertion `json:"assertions"`

	// DurabilityClaim is the one sentence this run is allowed to support.
	DurabilityClaim string `json:"durability_claim"`
}

Result is the whole gate run. It is the only thing serialized to JSON and the only thing the Markdown renderer reads.

func (*Result) Finalize 

func (r *Result) Finalize()

Finalize stamps the verdict onto the result from its own assertion table. Passed is true only when every assertion passed and every phase completed.

type SamplingConfig 

type SamplingConfig struct {
	IntervalSec float64 `json:"interval_sec"`
	// SteadyStartOffsetSec excludes the beginning of the sustained phase from
	// the projection fit: page cache, connection ramp and the first finalize
	// tick are not steady state.
	SteadyStartOffsetSec float64 `json:"steady_start_offset_sec"`
	// Metrics are the series recorded in every scrape.
	Metrics []string `json:"metrics"`
	// RequiredMetrics must be present in every scrape. A missing one fails
	// the gate rather than becoming a blank cell.
	RequiredMetrics []string `json:"required_metrics"`
	// BacklogMetric is the writer-backlog series the flatness rule reads.
	BacklogMetric string `json:"backlog_metric"`
	// ChargedBytesMetric is an optional counter of logical bytes charged to
	// the main tier. Used ONLY to report the amplification factor.
	ChargedBytesMetric string `json:"charged_bytes_metric"`
}

SamplingConfig configures the Prometheus and disk sampling loop.

type Thresholds 

type Thresholds struct {
	// --- Sustained phase ---
	SustainedHours        float64 `json:"sustained_hours"`
	SustainedPointsPerSec float64 `json:"sustained_points_per_sec"`
	// SustainedRateTolerance is how far below the offered rate the achieved
	// rate may sit before the phase is judged not to have run at the
	// contracted load. A phase that quietly ran at 4k pts/s must not pass a
	// 10k pts/s gate on the strength of its excellent latency.
	SustainedRateTolerance     float64 `json:"sustained_rate_tolerance"`
	AckP99MaxMs                float64 `json:"ack_p99_max_ms"`
	AckRatioMin                float64 `json:"ack_ratio_min"`
	MaxResourceExhausted       int64   `json:"max_resource_exhausted"`
	MaxLatePointsDelta         float64 `json:"max_late_points_delta"`
	MaxAdmissionRejectedDelta  float64 `json:"max_admission_rejected_delta"`
	MaxIdentityOverflowDelta   float64 `json:"max_identity_overflow_delta"`
	MaxIngestPipelineDropDelta float64 `json:"max_ingest_pipeline_drop_delta"`

	// BacklogAllowanceFraction and BacklogAllowanceFloorRows define "no
	// sustained backlog growth": the fitted growth across the phase and the
	// first-to-last delta must both stay inside
	// max(floor, fraction * peak observed).
	BacklogAllowanceFraction  float64 `json:"backlog_allowance_fraction"`
	BacklogAllowanceFloorRows float64 `json:"backlog_allowance_floor_rows"`
	BacklogMinSamples         int     `json:"backlog_min_samples"`

	// --- Burst phase ---
	BurstPointsPerSec    float64 `json:"burst_points_per_sec"`
	BurstSeconds         float64 `json:"burst_seconds"`
	BurstRecoverySeconds float64 `json:"burst_recovery_seconds"`

	// --- Recovery ---
	ReadySeconds     float64 `json:"ready_seconds"`
	MaxSkippedSeries int     `json:"max_skipped_series"`

	// --- Memory ---
	MemoryPeakMaxBytes int64 `json:"memory_peak_max_bytes"`
	MaxOOMKills        int64 `json:"max_oom_kills"`

	// --- Disk, every partition ---
	DiskMainMaxBytes       int64 `json:"disk_main_max_bytes"`
	DiskAggregateMaxBytes  int64 `json:"disk_aggregate_max_bytes"`
	DiskDLQMaxBytes        int64 `json:"disk_dlq_max_bytes"`
	DiskWALTempTLSMaxBytes int64 `json:"disk_wal_temp_tls_max_bytes"`
	DiskTotalMaxBytes      int64 `json:"disk_total_max_bytes"`
	DiskFreeMinBytes       int64 `json:"disk_free_min_bytes"`

	// --- Main-tier projection ---
	ProjectionMinSamples int `json:"projection_min_samples"`
	// ProjectionMinWindowSpan is how many completed five-minute windows the
	// steady samples must actually span. Samples are cheap and a short span is
	// how a startup transient gets extrapolated across two days.
	ProjectionMinWindowSpan  float64 `json:"projection_min_window_span"`
	ProjectionZ              float64 `json:"projection_upper_estimate_z"`
	ProjectionHorizonWindows int     `json:"projection_horizon_windows"`

	// --- Query completeness ---
	PrefillWindows          int     `json:"prefill_windows"`
	PrefillSeries           int     `json:"prefill_series"`
	PrefillServices         int     `json:"prefill_services"`
	ColdQueryMaxSeconds     float64 `json:"cold_query_max_seconds"`
	WarmQueryP95MaxSeconds  float64 `json:"warm_query_p95_max_seconds"`
	SevenDayQueryMaxSeconds float64 `json:"seven_day_query_max_seconds"`
	MCPQueryMaxSeconds      float64 `json:"mcp_query_max_seconds"`
	ProbeMaxSeconds         float64 `json:"probe_max_seconds"`
	// RequiredCoverage is the marker a fully aggregate-derived surface must
	// declare. Per-surface expectations live in QueryConfig.
	RequiredCoverage string `json:"required_coverage"`
}

Thresholds are the frozen pass criteria from issue #202 Q3, encoded as asserted values rather than as prose in a runbook.

Every field here produces at least one Assertion on every run. Changing a number here changes what the gate certifies, so it is a contract change and belongs in a commit that says so.

func DefaultThresholds 

func DefaultThresholds() Thresholds

DefaultThresholds returns the frozen contract.

type TierSpecConfig 

type TierSpecConfig struct {
	MainDBFile      string `json:"main_db_file"`
	AggregateDBFile string `json:"aggregate_db_file"`
	DLQDir          string `json:"dlq_dir"`
	TLSDir          string `json:"tls_dir"`
}

TierSpecConfig is the serializable form of ClassifySpec.

func (TierSpecConfig) Spec 

func (t TierSpecConfig) Spec() ClassifySpec

Spec converts to the classifier's input.

type TimedValue 

type TimedValue struct {
	OffsetSec float64
	Value     float64
}

TimedValue is one metric sample on the gate's own clock, in seconds since the phase start.

func MetricSeriesIn 

func MetricSeriesIn(samples []MetricSample, phase, key string) []TimedValue

MetricSeriesIn extracts one key's samples within a phase as offsets from the first sample, ready for the trend fit.

type WindowBound 

type WindowBound struct {
	WindowStart   int64  `json:"window_start"`
	CrashAffected bool   `json:"crash_affected"`
	Attempted     int64  `json:"attempted"`
	Acked         int64  `json:"acked"`
	Observed      int64  `json:"observed"`
	ObservedFound bool   `json:"observed_found"`
	Exact         bool   `json:"exact"`
	Pass          bool   `json:"pass"`
	Reason        string `json:"reason,omitempty"`
}

WindowBound is one window's comparison.

type WindowPoint 

type WindowPoint struct {
	Timestamp     time.Time `json:"timestamp"`
	Count         int64     `json:"count"`
	ErrorCount    int64     `json:"error_count"`
	Requests      int64     `json:"requests"`
	RequestErrors int64     `json:"request_errors"`
	Spans         int64     `json:"spans"`
	SpanErrors    int64     `json:"span_errors"`
}

WindowPoint is one entry of a per-window traffic response.

func ParseWindowPoints 

func ParseWindowPoints(body []byte) ([]WindowPoint, error)

ParseWindowPoints decodes the bare-array traffic response.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.