compatibility

package
v0.1.77 Latest Latest
Warning

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

 Go to latest Published: Aug 31, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package compatibility computes confidence and aggregation views from evidence. Compatibility is always a derived view over Evidence/Receipts, never a property of a Sample (goal.md §2.3).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildClusters 

func BuildClusters(ecosystem, packageName string,
	evidenceByVersion map[string][]serverstore.EvidenceRow,
	regressions []RegressionCandidate, now time.Time) []serverstore.ClusterRow

BuildClusters groups FAIL evidence for one (ecosystem, packageName) across versions by (symbol, stage, error fingerprint) and attaches probabilistic failure hypotheses — never a definitive verdict (goal.md §3.6, §6.4). evidenceByVersion maps version → all evidence rows of that version (every symbol); regressions are the already-detected §10.3 candidates for this package.

func BuildShard 

func BuildShard(key string, packages []ShardPackage, generatedAt time.Time) (shardJSON, etag string)

BuildShard renders the canonical shard JSON and its ETag. The ETag is the sha256 hex of the canonical JSON, so identical inputs (including generatedAt) always produce the identical etag.

func ClassWeight 

func ClassWeight(c domain.EvidenceClass) float64

ClassWeight is the evidence-class weighting from plan contract C7: verification evidence outweighs co-occurrence evidence by an order of magnitude (goal.md §6.1).

func Hypotheses 

func Hypotheses(errorCode string, failEnvs, passEnvs []domain.EnvironmentFingerprint) []domain.FailureHypothesis

Hypotheses derives a probabilistic failure-domain distribution for one cluster. The result is ALWAYS a distribution, never a single confirmed cause: with no signal it is {UNKNOWN: 1.0}.

func PreviousVersion 

func PreviousVersion(versions []string, current string) (string, bool)

PreviousVersion returns the greatest version strictly below current, for the §10.3 regression rule ("V-1").

func StatsJSON 

func StatsJSON(c serverstore.NetworkCounts, adopt serverstore.AdoptionCounts, now time.Time) ([]byte, error)

StatsJSON renders the stats rollup from the network counts and the adoption reports clients have sent back.

postHitSuccessRate is builds that PASSED over builds that were reported either way. A report with no build attached is counted in neither: the agent did not measure, and folding "unknown" into either bucket would turn a gap in the data into a claim about it. With no reports at all the rate stays 0 and PostHitBuildPass keeps saying nothing has been collected — which is what the front page renders as an em dash rather than as "0%".

func SymbolStatsFromEvidence 

func SymbolStatsFromEvidence(rows []serverstore.EvidenceRow) (ShardSymbolStats, []ShardFailure)

SymbolStatsFromEvidence condenses one symbol's evidence rows into the C6 stats block plus its failure list.

Types

type Builder 

type Builder struct {
	Store serverstore.Store
	// Now is a test seam; nil means time.Now.
	Now func() time.Time
	// contains filtered or unexported fields
}

Builder is the server aggregation pipeline: it materializes compatibility snapshots, failure clusters, regression flags, C6 shards, matrix verification jobs and the daily stats rollup from raw evidence + receipts. Web/API reads only ever touch the materialized outputs (§14.5).

func (*Builder) RunLoop 

func (b *Builder) RunLoop(ctx context.Context, interval time.Duration)

RunLoop runs RunOnce immediately, then on every interval tick until ctx is canceled. Failures are logged and retried on the next tick — an outage never kills the loop (goal.md §3.9 resilience posture).

func (*Builder) RunOnce 

func (b *Builder) RunOnce(ctx context.Context) error

RunOnce executes one aggregation pass.

The pass is INCREMENTAL by default. Rebuilding everything on every tick cost 1,603 shard writes and 1,958 snapshot writes every five minutes on a network where zero evidence rows had changed — work that scales with the size of the whole network rather than with what happened, and the first thing that would flatten a small instance as the graph grows.

Every fullPassEvery-th pass rebuilds everything anyway, so a missed change repairs itself rather than leaving a shard permanently stale.

type EstimatedStat 

type EstimatedStat struct {
	Estimated   bool     `json:"estimated"` // always true
	Value       int64    `json:"value"`
	Formula     string   `json:"formula"`
	Assumptions []string `json:"assumptions"`
}

EstimatedStat is an explicitly-labeled estimate: Estimated is ALWAYS true and the assumptions ride along (goal.md dashboard honesty rules).

type FailureSummary 

type FailureSummary struct {
	Stage           string            `json:"stage"`
	ErrorCode       string            `json:"errorCode,omitempty"`
	Fingerprint     string            `json:"fingerprint,omitempty"`
	TerminationKind string            `json:"terminationKind,omitempty"`
	ExitCode        *int              `json:"exitCode,omitempty"`
	Signal          string            `json:"signal,omitempty"`
	TimeoutMillis   int64             `json:"timeoutMillis,omitempty"`
	ErrorSummary    string            `json:"errorSummary,omitempty"`
	EvidenceQuality string            `json:"evidenceQuality"`
	OuterCommand    string            `json:"outerCommand,omitempty"`
	OuterStage      string            `json:"outerStage,omitempty"`
	ActualToolchain string            `json:"actualToolchain,omitempty"`
	StageEvidence   string            `json:"stageEvidence,omitempty"`
	EvidenceGap     string            `json:"evidenceGap,omitempty"`
	Count           int64             `json:"count"`
	EnvSummary      map[string]string `json:"envSummary,omitempty"`
	// Reporters and Projects are how WIDESPREAD the failure is, and they are
	// the honest ranking axis. Count is observations, which one machine
	// building all afternoon inflates without telling anyone anything: a
	// looping local developer outranked a fleet-wide break.
	//
	// Both are peaks within a single epoch and never sums across days -- the
	// dedup ledger is per epoch by design, and adding them would let one
	// machine manufacture a fleet.
	Reporters int `json:"reporters,omitempty"`
	Projects  int `json:"projects,omitempty"`
}

FailureSummary is one failure signature in one environment.

It used to be one signature across ALL environments, with EnvSummary set to the intersection of every failing environment's dimensions -- so the moment windows and linux shared a fingerprint the platform disappeared, and the cell a reader actually wants ("windows / node 20 failed at COMPILE with ERR_REQUIRE_ESM") existed nowhere in the document.

type JDKBoundaryCandidate added in v0.1.12 

type JDKBoundaryCandidate struct {
	Package              string                   `json:"package"`
	ResolvedPackages     []string                 `json:"resolvedPackages"`
	CaseID               string                   `json:"caseId"`
	Symbol               string                   `json:"symbol,omitempty"`
	Stage                string                   `json:"stage"`
	VerifierAdapter      string                   `json:"verifierAdapter"`
	SandboxCapability    domain.SandboxCapability `json:"sandboxCapability"`
	HarnessHash          string                   `json:"harnessHash"`
	LanguageVersion      string                   `json:"languageVersion"`
	LowerRuntimeVersion  string                   `json:"lowerRuntimeVersion"`
	HigherRuntimeVersion string                   `json:"higherRuntimeVersion"`
	LowerResult          string                   `json:"lowerResult"`
	HigherResult         string                   `json:"higherResult"`
	EnvironmentHash      string                   `json:"environmentHash"`
	LowerObservations    int64                    `json:"lowerObservations"`
	HigherObservations   int64                    `json:"higherObservations"`
}

JDKBoundaryCandidate is a receipt-established PASS/FAIL boundary where resolved packages and every non-JDK comparison dimension stayed fixed.

Vendor is not a signed EnvironmentFingerprint field. Consequently this is deliberately a pinned-image-family candidate, not a claim that arbitrary installations of the named JDK vendor behave the same way.

type PlaceholderStat 

type PlaceholderStat struct {
	Value float64 `json:"value"`
	Note  string  `json:"note"`
}

PlaceholderStat is a metric we cannot measure yet, labeled as such.

type ReceiptInfo 

type ReceiptInfo struct {
	PeerID            string
	CaseID            string
	Env               domain.EnvironmentFingerprint
	ContractResult    string // PASS | FAIL | SKIPPED | ""
	Stages            map[string]string
	StageFailures     map[string]domain.FailureEvidence
	ResolvedPackages  []domain.PURL
	VerifierAdapter   string
	SandboxCapability domain.SandboxCapability
	CreatedAt         time.Time
}

ReceiptInfo is the slice of a verification receipt the aggregation pipeline needs: who verified, where, and what the contract said.

func ParseReceiptRow 

func ParseReceiptRow(r serverstore.ReceiptRow) (ReceiptInfo, bool)

ParseReceiptRow extracts ReceiptInfo from a stored receipt row.

type RegressionCandidate 

type RegressionCandidate struct {
	Package         string `json:"package"`         // purl of the suspect version
	PreviousPackage string `json:"previousPackage"` // purl of V-1
	// CaseID is present for receipt-established candidates. It makes the
	// comparison auditable: both sides ran the same immutable problem rather
	// than merely mentioning the same symbol.
	CaseID string `json:"caseId,omitempty"`
	Symbol string `json:"symbol,omitempty"`
	// Receipt-established boundaries retain every comparison dimension that
	// made the two executions comparable. Consumers must not read an adapter-
	// specific failure as a package-wide verdict.
	VerifierAdapter   string                   `json:"verifierAdapter,omitempty"`
	SandboxCapability domain.SandboxCapability `json:"sandboxCapability,omitempty"`
	CompanionPackages []string                 `json:"companionPackages,omitempty"`
	HarnessHash       string                   `json:"harnessHash,omitempty"`
	// Stage is the stage the comparison was made at. Observation candidates
	// use a PROJECT_* stage; exact receipt boundaries use CONTRACT. A
	// regression only means something within one stage.
	Stage                string  `json:"stage,omitempty"`
	ContextLabel         string  `json:"contextLabel"`
	EnvBucketHash        string  `json:"envBucketHash"`
	FailRate             float64 `json:"failRate"`
	PreviousPassRate     float64 `json:"previousPassRate"`
	Observations         int64   `json:"observations"`
	PreviousObservations int64   `json:"previousObservations"`
}

RegressionCandidate is a flagged — never confirmed — version regression. It stays a candidate: uncertain causes are hypotheses, not verdicts (goal.md §3.6).

func DetectRegressions 

func DetectRegressions(curPURL, prevPURL, symbol string,
	cur, prev []serverstore.EvidenceRow) []RegressionCandidate

DetectRegressions applies the §10.3 rule per shared environment bucket between version V (cur) and version V-1 (prev) of the same package+symbol.

type Sample 

type Sample struct {
	Class  domain.EvidenceClass
	Result domain.Result
	Count  int64
}

Sample is one aggregated evidence line entering a confidence computation. It deliberately carries no age: evidence does not decay, and a field that nothing reads is how a decay quietly comes back.

type Shard 

type Shard struct {
	SchemaVersion int            `json:"schemaVersion"`
	Key           string         `json:"key"`
	GeneratedAt   string         `json:"generatedAt"`
	Packages      []ShardPackage `json:"packages"`
}

Shard is the C6 wire document for one (ecosystem, package, major).

type ShardFailure 

type ShardFailure struct {
	ErrorCode   string            `json:"errorCode,omitempty"`
	Fingerprint string            `json:"fingerprint,omitempty"`
	Count       int64             `json:"count"`
	EnvSummary  map[string]string `json:"envSummary,omitempty"`
}

ShardFailure is one failure signature inside a shard symbol entry.

type ShardPackage 

type ShardPackage struct {
	PURL                      string        `json:"purl"`
	Symbols                   []ShardSymbol `json:"symbols,omitempty"`
	Samples                   []ShardSample `json:"samples,omitempty"`
	CanonicalCaseCountTotal   int           `json:"canonicalCaseCountTotal,omitempty"`
	DistinctSubjectCountTotal int           `json:"distinctSubjectCountTotal,omitempty"`
}

ShardPackage is one package version inside a shard.

type ShardSample 

type ShardSample struct {
	SampleID string `json:"sampleId"`
	Goal     string `json:"goal,omitempty"`
	// Believed is what the sample's author says a competent developer or
	// model expects, which the contract below then contradicts.
	//
	// This is the single most useful sentence the network can hand a model,
	// because it names the wrong answer the model was about to write. It
	// costs one line in the shard and saves the round trip that a goal
	// sentence alone forces. Empty on every sample authored before the
	// field existed, and on every sample that corrects nothing.
	Believed string `json:"believed,omitempty"`
	Status   string `json:"status"`
	License  string `json:"license"`
	// Packages is what the sample's manifest declares. It is retained so a
	// client can see the author's input rather than silently replacing it
	// with resolver output.
	Packages []string `json:"packages,omitempty"`
	// Symbols is the bounded, canonical view of the public symbol families
	// declared by the sample manifest. Invalid declarations are never copied
	// into the public shard. SymbolsTruncated says when any valid declaration
	// was beyond the bound or any invalid declaration had to be withheld.
	Symbols          []string `json:"symbols,omitempty"`
	SymbolsTruncated bool     `json:"symbolsTruncated,omitempty"`
	// Verifications keeps every resolver claim coupled to the environment
	// and stage verdict that established it. Flattening several receipts into
	// one package list would claim combinations that never ran and could
	// attach a PASS from one version to a FAIL at another.
	Verifications  []ShardVerification           `json:"verifications,omitempty"`
	Environment    domain.EnvironmentFingerprint `json:"environment"`
	ContractStages map[string]string             `json:"contractStages,omitempty"`
	// Contract is the assertion list the sample's contract command actually
	// RAN, in a pinned container with the network off, and passed.
	//
	// It is the most useful thing the network knows about a library and it
	// never left the server: the shard carried the sample's one-line goal
	// and nothing else, so every search answer came back with
	// "contract": null and an agent had to spend a second tool call
	// (get_sample) to learn what was actually proven -- which is exactly
	// the per-call, per-option detail a goal sentence cannot carry.
	//
	// Bounded, because a shard is fetched by every client: see
	// contractForShard.
	Contract []string `json:"contract,omitempty"`
}

ShardSample is one top sample carried in a shard, including its honest verification status and the contract stages its receipts actually showed.

func TopShardSamples 

func TopShardSamples(samples []ShardSampleInput) []ShardSample

TopShardSamples orders samples for shard inclusion and caps the list.

VERIFICATION FIRST, then hot score, then recency. Ordering by traffic alone meant the cap cut by popularity: a package with 21 samples whose oldest was STABLE -- contract-passed and cross-verified by independent peers -- dropped exactly that one, because twenty newer PUBLISHED samples with no receipts at all were more recent and no more popular.

Then COVERAGE. Twenty slots that all answer the same question about the same symbol are worth about one slot: a caller asking about a different part of the library sees nothing, while the shard is full. So the first pass takes the best sample for each distinct symbol before any symbol gets a second slot. Density is the point of the cap, not scarcity — twenty samples about twenty different things beats twenty about one.

type ShardSampleInput 

type ShardSampleInput struct {
	Sample    ShardSample
	HotScore  float64
	CreatedAt time.Time
	// Symbols is what the sample declares it is about, used to spread the
	// capped list across distinct subjects rather than piling it onto one.
	Symbols []string
}

ShardSampleInput pairs a rendered shard sample with its ordering keys.

type ShardSymbol 

type ShardSymbol struct {
	Family   string           `json:"family"`
	Stats    ShardSymbolStats `json:"stats"`
	Failures []ShardFailure   `json:"failures,omitempty"`
}

ShardSymbol is one symbol family entry of a shard package.

type ShardSymbolStats 

type ShardSymbolStats struct {
	ObservationCount  int64                 `json:"observationCount"`
	UniquePeerBuckets int                   `json:"uniquePeerBuckets"`
	PassRate          float64               `json:"passRate"`
	ByStage           map[string]StageCount `json:"byStage"`
	Confidence        string                `json:"confidence"`
	LastSeen          string                `json:"lastSeen,omitempty"`
}

ShardSymbolStats is the compact per-symbol statistics block of contract C6.

type ShardVerification added in v0.1.5 

type ShardVerification struct {
	ResolvedPackages  []string                      `json:"resolvedPackages"`
	Environment       domain.EnvironmentFingerprint `json:"environment"`
	Stages            map[string]string             `json:"stages"`
	VerificationLevel int                           `json:"verificationLevel,omitempty"`
	CreatedAt         string                        `json:"createdAt,omitempty"`
}

ShardVerification is one receipt-scoped resolver claim. Packages, stages and environment are deliberately inseparable: together they describe one real execution. VerificationLevel is the strongest level proved for the same exact package set without exposing peer identities in the shard.

type Snapshot 

type Snapshot struct {
	SchemaVersion        int                   `json:"schemaVersion"`
	PURL                 string                `json:"purl"`
	Symbol               string                `json:"symbol"`
	Rows                 []SnapshotRow         `json:"rows"`
	Failures             []FailureSummary      `json:"failures"`
	RegressionCandidates []RegressionCandidate `json:"regressionCandidates,omitempty"`
	// JDKBoundaryCandidates are kept separate from package-version
	// regressions: the resolved package set is identical at both endpoints
	// and the JDK line is the measured axis.
	JDKBoundaryCandidates []JDKBoundaryCandidate `json:"jdkBoundaryCandidates,omitempty"`
	GeneratedAt           string                 `json:"generatedAt"`
}

Snapshot is the §7.8 read-optimized compatibility document stored per (purl, symbol) and served by registry/web reads — requests never re-aggregate raw evidence.

func BuildSnapshot 

func BuildSnapshot(purl, symbol string, evidence []serverstore.EvidenceRow,
	receipts []ReceiptInfo, regressions []RegressionCandidate, now time.Time) Snapshot

BuildSnapshot computes the snapshot for one (purl, symbol) target from its aggregated evidence rows and the receipts of samples covering the target. Pure: no I/O, unit-testable without a database.

type SnapshotRow 

type SnapshotRow struct {
	ContextLabel string                        `json:"contextLabel"`
	EnvBucket    domain.EnvironmentFingerprint `json:"envBucket"`
	// ByStage tallies per stage. Observation stages (PROJECT_*, USED) come
	// from anonymous evidence; the CONTRACT key comes from signed receipts.
	// The stage key is the separation — no cell mixes the two.
	ByStage map[string]StageCount `json:"byStage"`
	// ObservationClassCounts counts weak co-occurrence evidence by class.
	ObservationClassCounts map[string]int64 `json:"observationClassCounts"`
	// VerificationCounts counts strong receipt-backed evidence by class.
	VerificationCounts map[string]int64 `json:"verificationCounts"`
	PassRate           float64          `json:"passRate"`
	Confidence         string           `json:"confidence"`
	ElevatedFailure    bool             `json:"elevatedFailure"`
	UniquePeerBuckets  int              `json:"uniquePeerBuckets"`
	LastSeen           string           `json:"lastSeen,omitempty"`
}

SnapshotRow is one environment-bucket row of a compatibility snapshot. The execution-context label leads (docs/execution-context.md §6); observation class counts and verification counts are kept in separate maps and are NEVER summed together (goal.md §3.5).

type StageCount 

type StageCount struct {
	Pass                 int64 `json:"pass"`
	Fail                 int64 `json:"fail"`
	FailComplete         int64 `json:"failComplete,omitempty"`
	FailPartial          int64 `json:"failPartial,omitempty"`
	FailMissing          int64 `json:"failMissing,omitempty"`
	FailLegacyIncomplete int64 `json:"failLegacyIncomplete,omitempty"`
	// FailAttributed is the subset of Fail carrying a modern normalized
	// fingerprint (complete or partial evidence). The historical JSON name is
	// retained for compatibility; the public label names fingerprint coverage.
	//
	// An observation failure with no code says a build containing this
	// package broke, and nothing about which package broke it. One tsc
	// failure wrote a FAIL row for all 412 packages in the lockfile, under a
	// single fingerprint, and 82% of production's failures are that shape.
	// They stay in the rate, because the build really did fail and this is
	// co-occurrence evidence by definition. What was missing was any way for
	// a reader to tell a package that breaks from a package that was merely
	// installed when something else broke.
	FailAttributed int64 `json:"failAttributed,omitempty"`
}

StageCount is the pass/fail tally of one stage.

type StatsDoc 

type StatsDoc struct {
	SchemaVersion int    `json:"schemaVersion"`
	Day           string `json:"day"`
	GeneratedAt   string `json:"generatedAt"`
	// Peers is TODAY's distinct anonymous peer buckets. Those rotate
	// daily, so this genuinely cannot be summed over time — a peer active
	// all month would appear as thirty. ProjectsMonth is the honest
	// participation figure that does not reset at midnight.
	Peers         int64 `json:"peers"`
	ProjectsMonth int64 `json:"projectsMonth"`
	Packages      int64 `json:"packages"`
	Symbols       int64 `json:"symbols"`
	// Evidence counts observation records, not peers or projects: a big
	// number here says "widely used", never "widely verified".
	Evidence        int64 `json:"evidence"`
	VerifiedSamples int64 `json:"verifiedSamples"`
	// PostHitSuccessRate is 0..1; PostHitBuildPass keeps the honest note
	// that no adoption data has been collected yet.
	PostHitSuccessRate float64         `json:"postHitSuccessRate"`
	PostHitBuildPass   PlaceholderStat `json:"postHitBuildPass"`
	// PostHitBuildsReported is the DENOMINATOR: adoption reports that
	// carried a build outcome either way. It exists so a reader can tell a
	// measured 0% from an unmeasured one, which the rate alone cannot say.
	PostHitBuildsReported     int64         `json:"postHitBuildsReported"`
	EstimatedReasoningAvoided EstimatedStat `json:"estimatedReasoningAvoided"`
	// Estimated marks the whole document as containing estimated figures,
	// mirroring EstimatedReasoningAvoided.Estimated for simple consumers.
	Estimated bool `json:"estimated"`
}

StatsDoc is the daily stats rollup served by GET /v1/stats. Field names are a public contract shared with the website and the CLI — renaming one silently blanks a landing-page counter, so they stay fixed: peers, packages, symbols, evidence, verifiedSamples, postHitSuccessRate, estimatedReasoningAvoided (always flagged estimated), estimated, generatedAt.

type Verdict 

type Verdict struct {
	Confidence      string // HIGH | MEDIUM | LOW
	PassRate        float64
	WeightedTotal   float64
	ElevatedFailure bool
}

Verdict is the computed confidence for one (package, symbol, env) cell.

func Compute 

func Compute(samples []Sample, independence int64) Verdict

Compute applies the C7 formula. independence is the count of unique peer buckets — simple observation counts are never used as a trust score (goal.md §16.5).

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.