domain

Documentation

Overview

Package domain holds CodeSampleX's core types and pure logic. It has no I/O and no dependencies outside the standard library.

Index

• Constants
• Variables
• func AnomalyTypes() []string
• func AnomalyVerdictConfirmed(verdict string) bool
• func AnomalyVerdictFromReceipt(report AnomalyReport, receipt VerificationReceipt) (verdict string, decided bool)
• func CSXIssueKinds() []string
• func CSXIssueReplayLane(r CSXIssueReport) (endpoint string, replayable bool, reason string)
• func CSXIssueVerdictConfirmed(verdict string) bool
• func CSXSurfaces() []string
• func CanonicalJSON(v any) ([]byte, error)
• func ClassifiedFailureFingerprint(stage Stage, actualToolchain string, term FailureTermination, ...) string
• func CommandEcosystem(argv []string) string
• func CommandTool(argv []string) string
• func CompareVersions(a, b string) int
• func ConcreteResolvedVersion(v string) bool
• func FailureFingerprint(stage Stage, term FailureTermination, errorCode, errorSummary string) string
• func GateNormalOutput(req SearchRequest, resp SearchResponse, argv []string) (SearchResponse, []SuppressedCandidate)
• func IsWantedTarget(p PURL) bool
• func MustCanonicalJSON(v any) []byte
• func RecordOutputGateDiagnostic(resp *SearchResponse, req SearchRequest, beforeGate int, ...)
• func RenderDiagnosticText(w io.Writer, d *DiagnosticTrace)
• func ResultCoordinate(r SearchResult) (string, bool)
• func RuntimeLine(runtime, version string) string
• func SHA256Hex(b []byte) string
• type AnomalyObservation
• type AnomalyReport
  • func (r AnomalyReport) Fingerprint() string
  • func (r AnomalyReport) Normalize() AnomalyReport
  • func (r AnomalyReport) Validate() error
• type CSXIssuePublicInput
• type CSXIssueReport
  • func (r CSXIssueReport) Fingerprint() string
  • func (r CSXIssueReport) Normalize() CSXIssueReport
  • func (r CSXIssueReport) Validate() error
• type Case
  • func (c Case) ComputeID() string
• type DiagnosticCandidate
• type DiagnosticCoordinate
• type DiagnosticDecomposition
• type DiagnosticEvidence
• type DiagnosticFailure
• type DiagnosticFailureEvent
• type DiagnosticGap
• type DiagnosticPipelineStep
• type DiagnosticTrace
  • func NewDiagnosticTrace(req SearchRequest) *DiagnosticTrace
  • func (d *DiagnosticTrace) AddGap(code, reason, detail string)
• type DiagnosticVersions
• type EnvironmentFingerprint
  • func (e EnvironmentFingerprint) Bucketed() EnvironmentFingerprint
  • func (e EnvironmentFingerprint) ContextLabel() string
  • func (e EnvironmentFingerprint) Hash() string
  • func (e EnvironmentFingerprint) Normalize() EnvironmentFingerprint
• type EvidenceClass
• type EvidenceQuality
• type EvidenceSummary
• type FailureDomain
• type FailureEnvironmentVariant
• type FailureEvidence
  • func (f FailureEvidence) Termination() FailureTermination
• type FailureEvidenceGap
• type FailureHypothesis
• type FailureStageEvidence
• type FailureTermination
  • func (t FailureTermination) FingerprintCoordinate() string
  • func (t FailureTermination) Structured() bool
• type KnownFailure
• type MatchGrade
• type ObservationBatch
• type ObservedCell
• type ObservedEnvironment
• type ObservedError
• type ObservedReports
• type PURL
  • func ParsePURL(s string) (PURL, error)
  • func PublicTargetFromDescriptor(value string) (PURL, bool)
  • func WantedTargetFromFramework(value string) (PURL, bool)
  • func (p PURL) AnyVersionPattern() string
  • func (p PURL) BreakingBucket() string
  • func (p PURL) Major() string
  • func (p PURL) MajorMinor() string
  • func (p PURL) String() string
• type Result
• type SampleManifest
• type SandboxCapability
• type SearchProvenance
• type SearchRequest
  • func (r SearchRequest) EnvironmentIsContext() bool
• type SearchResponse
• type SearchResult
  • func DedupeResultsByCoordinate(results []SearchResult) []SearchResult
  • func (r SearchResult) ConfidenceReason() string
  • func (r SearchResult) RecommendationClassification() (classification string, advisoryOnly bool, reason string)
  • func (r SearchResult) RelevanceLine(req SearchRequest, argv []string) string
  • func (r SearchResult) RelevanceSignals(req SearchRequest, argv []string) []string
  • func (r SearchResult) RelevantToRequest(req SearchRequest, argv []string) bool
  • func (r SearchResult) SampleEcosystems() []string
  • func (r SearchResult) SuppressionReason(req SearchRequest, argv []string) string
  • func (r SearchResult) UnrelatedToCommand(argv []string) bool
  • func (r SearchResult) VerifiedOffer() bool
• type Stage
• type SuppressedCandidate
• type SymbolConfidence
• type TerminationKind
• type VerificationLevel
• type VerificationReceipt
  • func (r VerificationReceipt) ReceiptID() string
  • func (r VerificationReceipt) SigningBytes() []byte
• type VerifierImage
• type WorkerRequirements

Constants

const (
	// AnomalyCSXPassLocalFail: the network served a passing conclusion for
	// this coordinate and the same coordinate failed locally.
	AnomalyCSXPassLocalFail = "csx-pass-local-fail"
	// AnomalyCSXFailLocalPass: the network served a failing or incompatible
	// conclusion and the same coordinate passed locally.
	AnomalyCSXFailLocalPass = "csx-fail-local-pass"
	// AnomalySymbolSignatureMismatch: a symbol/API signature the network
	// returned is not the signature the public package actually exports.
	AnomalySymbolSignatureMismatch = "symbol-signature-mismatch"
	// AnomalyUpgradePathBroken: a recommended upgrade path does not
	// resolve, build or run.
	AnomalyUpgradePathBroken = "upgrade-path-broken"
	// AnomalyDependencyGraphUnknown: a sample exists and runs, but the
	// dependency graph reports unknown or contradicts itself.
	AnomalyDependencyGraphUnknown = "dependency-graph-unknown"
	// AnomalyEvidenceConflict: two pieces of evidence at the SAME exact
	// coordinate contradict each other.
	AnomalyEvidenceConflict = "evidence-conflict"
	// AnomalyBrokenInternalReference: sample/evidence/dependency/finding
	// reference each other and one side does not exist.
	AnomalyBrokenInternalReference = "broken-internal-reference"
	// AnomalyRepeatedNoSafeMatch: the same NO_SAFE_MATCH keeps coming back
	// AND a reproducible public failure is attached. NO_SAFE_MATCH on its
	// own is a real answer, not an anomaly.
	AnomalyRepeatedNoSafeMatch = "repeated-no-safe-match"
)

Anomaly types. Each names a shape of mismatch that can be stated as a public coordinate plus two disagreeing observations, which is the whole admission test — "the model thinks this is odd" has no shape here on purpose.

const (
	// AnomalyStatusQueued: accepted, deduped, and a reproduction job exists.
	AnomalyStatusQueued = "queued"
	// AnomalyStatusVerifying: a verifier holds the reproduction job.
	AnomalyStatusVerifying = "verifying"
	// AnomalyStatusVerified: a verdict has been recorded.
	AnomalyStatusVerified = "verified"
	// AnomalyStatusUnsupported: accepted, but no verifier lane in this
	// network can reproduce it. It is NOT hidden as permanently pending —
	// the reason is returned to the caller and shown in admin.
	AnomalyStatusUnsupported = "unsupported-verifier-lane"
)

Report ingest states. A report is never "true"; it is at some point in a pipeline that may end in a verdict.

const (
	AnomalyVerdictCSXDefect             = "confirmed-csx-defect"
	AnomalyVerdictCompatibilityBoundary = "confirmed-compatibility-boundary"
	AnomalyVerdictNewEvidence           = "confirmed-new-evidence"
	AnomalyVerdictEnvironmentDifference = "environment-difference"
	AnomalyVerdictNotReproducible       = "not-reproducible"
	AnomalyVerdictInsufficientEvidence  = "insufficient-evidence"
	AnomalyVerdictDuplicate             = "duplicate"
)

Verdicts. Only the three "confirmed-" values may promote anything.

const (
	CSXSurfaceMCP      = "mcp"
	CSXSurfaceServer   = "server"
	CSXSurfaceWeb      = "web"
	CSXSurfaceVerifier = "verifier"
	CSXSurfaceFarm     = "farm"
)

Surfaces a report can be about.

const (
	// CSXIssueAnswerMasksFailure: a CSX answer displaced or hid the failure
	// the caller was actually looking at. This is the R2C-51 shape.
	CSXIssueAnswerMasksFailure = "answer-masks-original-failure"
	// CSXIssueIrrelevantRecommendation: a returned result is unrelated to
	// what was asked — a different ecosystem, a different problem.
	CSXIssueIrrelevantRecommendation = "irrelevant-recommendation"
	// CSXIssueToolContractMisleads: an MCP tool's schema, description or
	// response shape makes a model behave wrongly.
	CSXIssueToolContractMisleads = "tool-contract-misleads"
	// CSXIssueNondeterministicResponse: the same input produces responses
	// that break the response contract inconsistently.
	CSXIssueNondeterministicResponse = "nondeterministic-response"
	// CSXIssueBrokenInternalReference: sample/evidence/dependency/finding
	// reference each other and one side does not exist.
	CSXIssueBrokenInternalReference = "broken-internal-reference"
	// CSXIssueRuntimeBehavior: timeouts, retries, loops, duplicate calls —
	// how the product behaves rather than what it answers.
	CSXIssueRuntimeBehavior = "runtime-behavior"
)

Issue kinds. A closed vocabulary, because it is what makes two reports of one defect one report — and because "it seemed off" has no entry here, which is the point.

const (
	CSXIssueStatusTriage = "triage"
	// CSXIssueStatusReplayQueued: the report named an input this server can
	// legitimately re-run, and a replay is pending.
	CSXIssueStatusReplayQueued = "replay-queued"
	// CSXIssueStatusNoReplayLane: nothing here can re-run it automatically,
	// and the reason is returned to the caller and shown to an operator. It
	// is NOT hidden as permanently pending.
	CSXIssueStatusNoReplayLane = "no-replay-lane"
	CSXIssueStatusResolved     = "resolved"
)

Report states.

const (
	CSXIssueVerdictDefect               = "confirmed-csx-defect"
	CSXIssueVerdictExpectedBehavior     = "expected-behavior"
	CSXIssueVerdictClientDifference     = "client-difference"
	CSXIssueVerdictNotReproducible      = "not-reproducible"
	CSXIssueVerdictInsufficientEvidence = "insufficient-evidence"
	CSXIssueVerdictDuplicate            = "duplicate"
)

Verdicts. Deliberately NOT the anomaly vocabulary: a product defect is not a compatibility boundary and must never be promotable to one.

const (
	DependencyUnknown    = "unknown"
	DependencyProvenNone = "proven-no-dependencies"
	DependencyResolved   = "resolved"
)

const (
	// RelevanceExactFailure is the caller's own sanitized failure
	// fingerprint having been recorded against this sample. It is a direct
	// evidence link between the failure in hand and this candidate and
	// outranks every other consideration, including ecosystem.
	RelevanceExactFailure = "exact-failure-fingerprint"
	// RelevanceSamePackage is the caller and the sample naming one package.
	// A version gap does not cancel it: that is what an adaptation candidate
	// is, and the delta already states the gap.
	RelevanceSamePackage = "same-package"
	// RelevanceSameSymbol is a complete declared identity in common.
	RelevanceSameSymbol = "same-symbol"
	// RelevanceAdjacentSymbol is a neighbouring API on the same owner:
	// decimal.Decimal.Round beside decimal.Decimal.RoundBank. The adaptation
	// path between them is explainable, which is what makes it a candidate.
	RelevanceAdjacentSymbol = "adjacent-symbol"
	// RelevanceSameTool is the sample being about the very tool the failing
	// command ran. A pkg:generic CLI subject has no dependency tree to
	// overlap with, so the command's own name is the link.
	RelevanceSameTool = "same-tool"
	// RelevanceSharedDiagnostic is one structured error identifier named by
	// both the request and the sample.
	RelevanceSharedDiagnostic = "shared-diagnostic"
	// RelevanceNamedSubject is the caller's own question naming this
	// sample's package or symbol.
	RelevanceNamedSubject = "query-names-subject"
	// RelevanceGoalSemantics is the question and the sample's goal
	// describing the same operation in different words. It is the signal a
	// caller earns by saying what they want rather than which library does
	// it, and it is the one that has to be measured rather than asserted —
	// see goalSemanticsFloor.
	RelevanceGoalSemantics = "same-goal-semantics"
)

Relevance* are the links that promote a candidate into normal output. Each is a fact about the request and the candidate together, never about the machine they would run on.

const (
	// SuppressedUnrelatedEcosystem is the older, narrower gate: the failing
	// command does not build for the ecosystem the sample is pinned to.
	SuppressedUnrelatedEcosystem = "unrelated-ecosystem"
	// SuppressedInsufficientGoalOverlap is this gate: the candidate shares
	// no package, symbol, diagnostic or subject with the request, and what
	// it does share is environment coordinates.
	SuppressedInsufficientGoalOverlap = "insufficient-goal-overlap"
)

Suppressed* are the stable reason codes a demoted candidate carries. They are read by machines — the hook trace, and the diagnostic payload — and the sentences beside them are for people and may be reworded.

const (
	// ObservedBasis is the only basis an ObservedReports may claim.
	ObservedBasis = "observed"
	// ObservedNote travels with every relay.
	//
	// It said "reported by machines". The relay counts peer buckets, not
	// machines — see ObservedCell.Reporters — and an observation is one
	// stage a build reached, not one run of anything.
	ObservedNote = "Reported by peers that ran this, not verified by this project. " +
		"No sample was proven for your case; these are the recorded observations, as recorded."
)

const (
	RecommendationVerifiedMatch      = "VERIFIED_MATCH"
	RecommendationReferenceCandidate = "REFERENCE_CANDIDATE"
)

const (
	MaxCoresidentPerBatch = 32
	MaxDependsOnPerBatch  = 256
)

Wire caps for a batch's edge facts, shared by the server that refuses a batch past them and the client that clamps before sending. One lockfile holds a handful of coresident versions of one library and a package's own direct dependencies; anything past these is abuse or a bug.

const AnomalyReportSchemaVersion = 1

AnomalyReportSchemaVersion is the only accepted wire version.

const CSXIssueReportSchemaVersion = 1

CSXIssueReportSchemaVersion is the only accepted wire version.

const DiagnosticSchemaVersion = "csx.debug.v1"

const RecommendationNoRelevantMatch = "NO_RELEVANT_MATCH"

RecommendationNoRelevantMatch is the status an automatic, unasked recommendation carries when the network answered but the answer is not about the failure in hand.

It is distinct from NO_SAFE_MATCH, which means the network had nothing. Here it had something and it is the wrong language, so the honest report is neither "here is a fix" nor "nothing exists" but "this is not about you".

const VerificationJobIDHeader = "X-CSX-Verification-Job-ID"

VerificationJobIDHeader binds a signed receipt submission to the exact claimed verification job it answers. The value itself is not trusted; the server checks the job's sample, reason, requirements and claimant against the signed receipt before completing that one row.

const VerificationPeerIDHeader = "X-CSX-Verification-Peer-ID"

VerificationPeerIDHeader accompanies a claimed job's artifact download. Public artifacts do not need it; quarantined authoring drafts require both this peer id and VerificationJobIDHeader to match the live claim.

Variables

var (
	ErrAnomalySchema           = errors.New("anomaly report schemaVersion must be 1")
	ErrAnomalyType             = errors.New("anomalyType must be one of: " + strings.Join(AnomalyTypes(), ", "))
	ErrAnomalyPackage          = errors.New("package must be a public purl, e.g. pkg:npm/axios@1.12.0")
	ErrAnomalyNoLocalObs       = errors.New("localObserved.result must be PASS or FAIL: a report with no local observation is a hypothesis, and hypotheses are not accepted")
	ErrAnomalyNoMismatch       = errors.New("csxObserved and localObserved must actually disagree: a concrete mismatch is the admission test")
	ErrAnomalyReproducible     = errors.New("reproducible must be yes, no or unknown")
	ErrAnomalyConfidence       = errors.New("confidence must be low, medium or high")
	ErrAnomalyStage            = errors.New("observation stage must be one of: resolve, compile, typecheck, test, run, contract")
	ErrAnomalyIdentifier       = errors.New("sampleId, evidenceId, searchFingerprint, errorFingerprint and relatedIds must be canonical, non-identifying stable ids")
	ErrAnomalyErrorCode        = errors.New("errorCode must be a short structured identifier")
	ErrAnomalyNoSafeMatchAlone = errors.New("a repeated NO_SAFE_MATCH is not an anomaly on its own: attach a reproducible public failure (localObserved FAIL + errorFingerprint + reproducible=yes)")
)

Errors the ingest path returns. Each one is a sentence a caller can act on, because "invalid report" tells an agent nothing about what to fix.

var (
	ErrCSXIssueSchema       = errors.New("csx issue report schemaVersion must be 1")
	ErrCSXIssueSurface      = errors.New("affectedSurface must be one of: " + strings.Join(CSXSurfaces(), ", "))
	ErrCSXIssueKind         = errors.New("issueKind must be one of: " + strings.Join(CSXIssueKinds(), ", "))
	ErrCSXIssueComponent    = errors.New("component is required: name the tool or endpoint this is about")
	ErrCSXIssueBehavior     = errors.New("actualBehavior and expectedBehavior are both required and must differ")
	ErrCSXIssueNoEvidence   = errors.New("a report needs something re-checkable: give a requestFingerprint, or publicInput naming the public endpoint and coordinates. A description on its own is not a report")
	ErrCSXIssueReproducible = errors.New("reproducible must be yes, no or unknown")
	ErrCSXIssueConfidence   = errors.New("confidence must be low, medium or high")
)

var AllowedEcosystems = map[string]bool{
	"npm":    true,
	"pypi":   true,
	"cargo":  true,
	"golang": true,
	"maven":  true,
}

AllowedEcosystems is the Public v1 package/receipt allowlist. Scanner coverage is a separate claim: verification-only ecosystems such as Maven may publish signed sample evidence without scanning arbitrary local projects.

Functions

func AnomalyTypes

func AnomalyTypes() []string

AnomalyTypes lists every accepted anomalyType, in schema order.

func AnomalyVerdictConfirmed

func AnomalyVerdictConfirmed(verdict string) bool

AnomalyVerdictConfirmed reports whether a verdict may promote a report to public evidence or to the internal defect queue. Everything else is a closed report and changes nothing anyone can see.

func AnomalyVerdictFromReceipt

func AnomalyVerdictFromReceipt(report AnomalyReport, receipt VerificationReceipt) (verdict string, decided bool)

AnomalyVerdictFromReceipt decides what a reproduction actually showed.

The receipt is the authority and the ONLY authority. The report's own confidence, its hypothesis and how sure the model sounded do not appear below: what appears is the contract result a signed receipt recorded, the PASS/FAIL the reporter measured, and whether the two machines were the same kind of machine.

decided=false means the contract never ran — a resolve or compile failure measured the verifier, not the sample — so the report stays open and the existing cross-verification retry does its work. Reporting a verdict from a run that never reached the assertion would be inventing one.

func CSXIssueKinds

func CSXIssueKinds() []string

CSXIssueKinds lists every accepted issueKind.

func CSXIssueReplayLane

func CSXIssueReplayLane(r CSXIssueReport) (endpoint string, replayable bool, reason string)

CSXIssueReplayLane reports whether this server can re-run the report's own request, and says why not when it cannot.

The "why not" is the useful half. For the defect class this channel most wants to catch — a search that answered the wrong question — the input that would have to be replayed is the caller's prompt, and the privacy contract means this network never has it. A stable fingerprint can travel; a fingerprint cannot be re-run. Saying that plainly is the difference between a queue an operator can trust and a queue full of work that will never move.

func CSXIssueVerdictConfirmed

func CSXIssueVerdictConfirmed(verdict string) bool

CSXIssueVerdictConfirmed reports whether a verdict may reach the repair queue. It is the ONLY gate: everything else is a closed report.

func CSXSurfaces

func CSXSurfaces() []string

CSXSurfaces lists every accepted affectedSurface.

func CanonicalJSON

func CanonicalJSON(v any) ([]byte, error)

CanonicalJSON renders v as deterministic JSON: object keys sorted, no insignificant whitespace, numbers preserved verbatim, no trailing newline. All content hashes and signatures in CodeSampleX are computed over this form.

func ClassifiedFailureFingerprint

func ClassifiedFailureFingerprint(stage Stage, actualToolchain string, term FailureTermination, errorCode, errorSummary string) string

ClassifiedFailureFingerprint is the v3 identity for actual-stage evidence. Outer command intent is deliberately excluded; the actual failing toolchain is included so unrelated compilers do not collapse behind one wrapper.

func CommandEcosystem

func CommandEcosystem(argv []string) string

CommandEcosystem is the package ecosystem the tool a command starts with builds for, or "" when it builds for none.

The base name is taken here rather than with filepath.Base because argv[0] crosses machines: a Windows caller sends C:\Program Files\nodejs\npm.cmd and a linux verifier reading it with filepath.Base would return the whole string. The launcher suffixes go with it — on Windows npm IS npm.cmd, and an ecosystem gate that only knew about .exe classified every npm build as belonging to no ecosystem at all.

func CommandTool

func CommandTool(argv []string) string

CommandTool is the bare name of the tool a command starts with, normalized the way CommandEcosystem needs it. It is exported because the relevance gate asks a second question of the same word: not only which ecosystem the tool builds for, but whether a sample is about the tool itself.

func CompareVersions

func CompareVersions(a, b string) int

CompareVersions orders two version strings the way a reader expects, which string comparison does not: "7.0.3" sorts above "14.0.1" because '7' > '1'. The record page picked the newest version that way and told every reader that npm/uuid was at 7.0.3 when the only evidence the network held was 14.0.1 — a wrong fact on the most-read page, about the one thing this site exists to be right about.

Numeric segments compare numerically, non-numeric ones lexically, and a version with fewer segments sorts below one that extends it ("1.2" < "1.2.1"). A pre-release suffix is ranked below the release it precedes, per semver: 1.2.0-rc1 < 1.2.0.

It returns -1, 0 or 1. This is deliberately not a full semver parser: the input is whatever a lockfile resolved, across nine ecosystems, and a comparator that rejects what it cannot parse would be worse than one that degrades to a sensible order.

func ConcreteResolvedVersion

func ConcreteResolvedVersion(v string) bool

ConcreteResolvedVersion reports whether v has the shape of a registry release selected by a resolver, rather than a request/range/protocol. It is intentionally cross-ecosystem and conservative: public versions used by the supported resolvers fit this ASCII set, while ^1, >=2, URLs, workspace references and whitespace do not. At least one digit is required so channel names such as "latest" cannot become signed version evidence.

func FailureFingerprint

func FailureFingerprint(stage Stage, term FailureTermination, errorCode, errorSummary string) string

FailureFingerprint returns the canonical v2 cluster identity for modern failure evidence. Package/version and exact environment are intentionally outside this hash and remain structured dimensions beside the cluster.

func GateNormalOutput

func GateNormalOutput(req SearchRequest, resp SearchResponse, argv []string) (SearchResponse, []SuppressedCandidate)

GateNormalOutput splits a retrieval response into what may be rendered as normal output and what may not.

When nothing survives, the response becomes a MISS. That is the honest answer and not a demotion: NO_SAFE_MATCH means this network has no sample it built for the caller's case, which is exactly what "everything it retrieved is about something else" amounts to. The alternative — rendering the nearest neighbour anyway under a REFERENCE_CANDIDATE label — is the forced HIT that goal.md §3.8 exists to forbid.

argv is the failing command's own words on the paths that have one, and empty on the paths that answered a question.

func IsWantedTarget

func IsWantedTarget(p PURL) bool

IsWantedTarget reports whether p is one of the fixed public engine/SDK coordinates. It is the publicness boundary for targets that do not live on a package registry; a syntactically valid arbitrary generic purl is false.

func MustCanonicalJSON

func MustCanonicalJSON(v any) []byte

MustCanonicalJSON panics on marshal failure; for types known to marshal.

func RecordOutputGateDiagnostic

func RecordOutputGateDiagnostic(resp *SearchResponse, req SearchRequest, beforeGate int, suppressed []SuppressedCandidate)

RecordOutputGateDiagnostic adds the final rendering decision to the same trace the search engine started. The output gate is shared by MCP, daemon and CLI paths, so keeping this mutation here prevents those entry points from explaining the same suppression differently.

func RenderDiagnosticText

func RenderDiagnosticText(w io.Writer, d *DiagnosticTrace)

RenderDiagnosticText renders only fields from DiagnosticTrace. JSON and human output therefore cannot drift into separate diagnostic models.

func ResultCoordinate

func ResultCoordinate(r SearchResult) (string, bool)

ResultCoordinate is the canonical (packages, symbols) key a duplicate shares. ok is false when the result declares neither, which is not a coordinate anyone can collide on.

func RuntimeLine

func RuntimeLine(runtime, version string) string

RuntimeLine reduces a runtime version to the release LINE it belongs to — the precision a job may demand of a machine it does not control.

A pinned image promises a line, never a patch digit: asking a verifier for node 22.23.2 or go 1.26.5 exactly is asking for something no image can guarantee, and the returning receipt is refused for not matching its own job. Which component names the line differs by runtime: Node, Bun, Deno, Java and browser engines ship lines as majors (22, 21), while Python, Go and Rust name theirs with the minor (3.14, 1.26). Unknown runtimes keep major.minor — the stricter of the two, since a requirement that is too loose accepts evidence from the wrong line.

func SHA256Hex

func SHA256Hex(b []byte) string

SHA256Hex returns "sha256:<hex>" over b — the project-wide content id form.

Types

type AnomalyObservation

type AnomalyObservation struct {
	// Result is PASS, FAIL or UNKNOWN. UNKNOWN is legal for what CSX said
	// (it may have said nothing) and illegal for the local side, which is
	// the whole admission test.
	Result string `json:"result"`
	// Stage names where the result happened: resolve | compile | typecheck
	// | test | run | contract. Empty means the reporter did not retain it;
	// any other value is refused rather than stored as arbitrary text.
	Stage string `json:"stage,omitempty"`
	// Detail is a short sanitized statement. Never raw logs.
	Detail string `json:"detail,omitempty"`
}

AnomalyObservation is one measured outcome. Result is the only field a verdict is ever computed from; Detail is sanitized prose for a human reading the queue.

type AnomalyReport

type AnomalyReport struct {
	SchemaVersion int    `json:"schemaVersion"`
	AnomalyType   string `json:"anomalyType"`

	// Package is the exact public coordinate the mismatch is about, as a
	// purl. It is required: a report with no public coordinate cannot be
	// reproduced by anybody, which makes it an opinion.
	Package string `json:"package"`
	Symbol  string `json:"symbol,omitempty"`

	// Environment is where the LOCAL observation happened. It is what turns
	// "it fails" into "it fails there", and it is the difference between a
	// confirmed defect and a recorded environment boundary.
	Environment EnvironmentFingerprint `json:"environment"`

	// SampleID, EvidenceID and SearchFingerprint are references to things
	// CSX itself already published. They are the only ids a reporter can
	// hold, and they are how a report is attached to something reproducible.
	SampleID          string `json:"sampleId,omitempty"`
	EvidenceID        string `json:"evidenceId,omitempty"`
	SearchFingerprint string `json:"searchFingerprint,omitempty"`

	CSXObserved   AnomalyObservation `json:"csxObserved"`
	LocalObserved AnomalyObservation `json:"localObserved"`

	// Reproducible is yes | no | unknown, as the reporter measured it — not
	// as it hopes. It ranks; it never decides.
	Reproducible string `json:"reproducible"`
	// Confidence is low | medium | high. Ranking only, never truth.
	Confidence string `json:"confidence"`

	// ErrorCode and ErrorFingerprint are the sanitizer's output for the
	// local failure. Raw stderr never travels; the fingerprint is what makes
	// two reports of the same failure one report.
	ErrorCode        string `json:"errorCode,omitempty"`
	ErrorFingerprint string `json:"errorFingerprint,omitempty"`
	// ErrorTemplate is the sanitized template — placeholders where paths,
	// tokens and usernames were.
	ErrorTemplate string `json:"errorTemplate,omitempty"`

	RelatedIDs []string `json:"relatedIds,omitempty"`

	// LLMHypothesis is the reporter's guess at the cause. It is stored, it
	// is shown to a human, and it is deliberately absent from Fingerprint
	// and from every verdict computation in this file. A wrong guess must
	// cost the report nothing.
	LLMHypothesis string `json:"llmHypothesis,omitempty"`
}

AnomalyReport is the wire document an agent submits and the server stores.

func (AnomalyReport) Fingerprint

func (r AnomalyReport) Fingerprint() string

Fingerprint is the dedupe key: exact public coordinate plus the shape of the mismatch. Two agents that hit the same wall produce the same string, which is what stops one bad answer from queuing a thousand containers.

LLMHypothesis, confidence and free prose are deliberately NOT in it. Two reports of one fact must not become two facts because two models explained it differently.

func (AnomalyReport) Normalize

func (r AnomalyReport) Normalize() AnomalyReport

Normalize canonicalizes the fields a verdict and a fingerprint are computed from, so two reports that say the same thing in different case dedupe against each other instead of both queuing work.

func (AnomalyReport) Validate

func (r AnomalyReport) Validate() error

Validate applies the admission test. It runs on the client before an upload and again on the server, because the client is a program somebody else can replace.

Everything it refuses is refused for the same reason: it cannot be re-verified by anyone. That is the only bar — not whether the report sounds right, not how confident the reporter is.

type CSXIssuePublicInput

type CSXIssuePublicInput struct {
	// Endpoint is the public read route the request went to.
	Endpoint string `json:"endpoint"`
	// Packages are public purls the request named.
	Packages []string `json:"packages,omitempty"`
	Symbols  []string `json:"symbols,omitempty"`
	// Environment is the fingerprint the request was graded against.
	Environment EnvironmentFingerprint `json:"environment,omitempty"`
}

CSXIssuePublicInput is the part of a request that was ALREADY PUBLIC and can therefore be sent and re-run.

Note what has no field here: the caller's question. There is no `query`, no prompt, no free-text input shape — not as a matter of policy layered on top, but because the struct has nowhere to put one. That is the whole reason the replay lane is narrow, and it is worth stating plainly: for the defect class this channel most wants to catch — a search that answered the wrong question — the input that would have to be replayed IS the user's prompt, and this network never receives it. A stable request fingerprint can travel, and a fingerprint cannot be re-run.

type CSXIssueReport

type CSXIssueReport struct {
	SchemaVersion   int    `json:"schemaVersion"`
	AffectedSurface string `json:"affectedSurface"`
	IssueKind       string `json:"issueKind"`
	// Component is the tool or endpoint the report is about:
	// "search_known_solution", "/v2/search", "csx worker".
	Component string `json:"component"`

	// RequestFingerprint is a stable, non-identifying id for the request.
	// It is what makes two occurrences of one defect one row.
	RequestFingerprint string `json:"requestFingerprint,omitempty"`
	// PublicInput is present only when the request can honestly be restated
	// from public coordinates alone.
	PublicInput *CSXIssuePublicInput `json:"publicInput,omitempty"`

	// ActualBehavior and ExpectedBehavior are short sanitized statements.
	// Both are required and they must differ: a report where they agree is
	// describing something working.
	ActualBehavior   string `json:"actualBehavior"`
	ExpectedBehavior string `json:"expectedBehavior"`

	Reproducible string `json:"reproducible"` // yes | no | unknown
	Confidence   string `json:"confidence"`   // low | medium | high

	RelatedIDs []string `json:"relatedIds,omitempty"`

	// LLMHypothesis is the reporter's guess. Stored, shown, and excluded
	// from the fingerprint and from every verdict — same rule as an anomaly
	// report, for the same reason.
	LLMHypothesis string `json:"llmHypothesis,omitempty"`
}

CSXIssueReport is the wire document.

func (CSXIssueReport) Fingerprint

func (r CSXIssueReport) Fingerprint() string

Fingerprint is the dedupe key: which surface, which component, which shape of defect, and which request.

The prose is NOT in it, deliberately. Two models describing one defect in two sentences must produce one row and one occurrence count — otherwise a popular defect becomes a pile of tickets, which is the exact outcome the conservative policy exists to prevent.

func (CSXIssueReport) Normalize

func (r CSXIssueReport) Normalize() CSXIssueReport

Normalize canonicalizes the fields the fingerprint and the verdict use.

func (CSXIssueReport) Validate

func (r CSXIssueReport) Validate() error

Validate applies the admission test. It is narrower than it looks: what it refuses is a report nobody can act on, which is the same set as the reports a model can generate for free.

type Case

type Case struct {
	SchemaVersion int               `json:"schemaVersion"`
	CaseID        string            `json:"caseId,omitempty"`
	Kind          string            `json:"kind"` // HOW | FIX | MIGRATION | CONFIG
	Goal          string            `json:"goal"`
	Packages      []string          `json:"packages"`
	Symbols       []string          `json:"symbols,omitempty"`
	Constraints   map[string]string `json:"constraints,omitempty"`
	Contract      []string          `json:"contract"`
	// Believed is the thing a competent developer or model expects, which
	// the contract then measures and contradicts.
	//
	// It is what turns a sample into a FINDING. The findings page is the
	// most persuasive thing on the site — "the documentation says X, the
	// contract measured Y" does more than any paragraph of explanation —
	// and it was a hand-written list of twenty-nine entries in Go source
	// while the storehouse grew past three hundred samples. The page that
	// convinces people was the one that could not grow.
	//
	// Optional, and omitted when empty, so every case id computed before
	// this field existed is unchanged.
	Believed string `json:"believed,omitempty"`
}

Case describes a problem being solved — never code (goal.md §7.4).

func (Case) ComputeID

func (c Case) ComputeID() string

ComputeID derives the content-addressed case ID over the canonical JSON of the case with CaseID cleared.

type DiagnosticCandidate

type DiagnosticCandidate struct {
	SampleID            string             `json:"sampleId,omitempty"`
	Packages            []string           `json:"packages,omitempty"`
	Match               MatchGrade         `json:"match,omitempty"`
	Score               float64            `json:"score"`
	Outcome             string             `json:"outcome"`
	ReasonCodes         []string           `json:"reasonCodes,omitempty"`
	RelevanceSignals    []string           `json:"relevanceSignals,omitempty"`
	FeatureContribution map[string]float64 `json:"featureContribution,omitempty"`
}

type DiagnosticCoordinate

type DiagnosticCoordinate struct {
	Packages    []string               `json:"packages,omitempty"`
	Symbols     []string               `json:"symbols,omitempty"`
	Environment EnvironmentFingerprint `json:"environment"`
}

type DiagnosticDecomposition

type DiagnosticDecomposition struct {
	PackageCount          int `json:"packageCount"`
	SymbolCount           int `json:"symbolCount"`
	ContextSymbolCount    int `json:"contextSymbolCount"`
	StructuredDiagnostics int `json:"structuredDiagnostics"`
	TopicTokenCount       int `json:"topicTokenCount"`
}

type DiagnosticEvidence

type DiagnosticEvidence struct {
	UsageObservationScope       string `json:"usageObservationScope"`
	UsageObservationSymbolProof bool   `json:"usageObservationIsSymbolProof"`
	VerifiedCoordinateCount     int    `json:"verifiedCoordinateCount"`
	UnverifiedCoordinateCount   int    `json:"unverifiedCoordinateCount"`
	DependencyState             string `json:"dependencyState"`
}

type DiagnosticFailure

type DiagnosticFailure struct {
	OuterCommand string                   `json:"outerCommand,omitempty"`
	OuterStage   string                   `json:"outerStage,omitempty"`
	ExitCode     int                      `json:"outerExit"`
	Termination  string                   `json:"termination,omitempty"`
	Events       []DiagnosticFailureEvent `json:"processLineage,omitempty"`
}

type DiagnosticFailureEvent

type DiagnosticFailureEvent struct {
	ActualToolchain   string `json:"actualToolchain,omitempty"`
	ActualStage       string `json:"actualFailureStage"`
	DiagnosticCode    string `json:"diagnosticCode,omitempty"`
	Fingerprint       string `json:"fingerprint,omitempty"`
	DiagnosticQuality string `json:"diagnosticQuality,omitempty"`
	StageEvidence     string `json:"stageEvidence,omitempty"`
	EvidenceGap       string `json:"evidenceGap,omitempty"`
}

type DiagnosticGap

type DiagnosticGap struct {
	Code       string `json:"code"`
	ReasonCode string `json:"reasonCode"`
	Detail     string `json:"detail,omitempty"`
}

type DiagnosticPipelineStep

type DiagnosticPipelineStep struct {
	Stage          string `json:"stage"`
	InputCount     int    `json:"inputCount"`
	OutputCount    int    `json:"outputCount"`
	RejectedCount  int    `json:"rejectedCount,omitempty"`
	ElapsedMicros  int64  `json:"elapsedMicros"`
	EvidenceSource string `json:"evidenceSource,omitempty"`
}

type DiagnosticTrace

type DiagnosticTrace struct {
	SchemaVersion    string                   `json:"schemaVersion"`
	RequestID        string                   `json:"requestId"`
	Versions         DiagnosticVersions       `json:"versions"`
	Coordinate       DiagnosticCoordinate     `json:"normalizedCoordinate"`
	Query            DiagnosticDecomposition  `json:"queryDecomposition"`
	Pipeline         []DiagnosticPipelineStep `json:"matchPipeline,omitempty"`
	Candidates       []DiagnosticCandidate    `json:"candidates,omitempty"`
	Evidence         DiagnosticEvidence       `json:"evidence"`
	Failure          *DiagnosticFailure       `json:"failure,omitempty"`
	Gaps             []DiagnosticGap          `json:"gaps,omitempty"`
	Decision         string                   `json:"decision"`
	PotentialAnomaly bool                     `json:"potentialAnomaly"`
}

DiagnosticTrace is the single debug representation rendered by CLI/MCP as text and JSON. It contains public coordinates, bounded aggregate counts and sanitized reason codes only. Query prose, local paths and raw diagnostics do not belong here.

func NewDiagnosticTrace

func NewDiagnosticTrace(req SearchRequest) *DiagnosticTrace

func (*DiagnosticTrace) AddGap

func (d *DiagnosticTrace) AddGap(code, reason, detail string)

type DiagnosticVersions

type DiagnosticVersions struct {
	Client   string `json:"client,omitempty"`
	Server   string `json:"server,omitempty"`
	Protocol string `json:"protocol,omitempty"`
	Payload  int    `json:"payload"`
}

type EnvironmentFingerprint

type EnvironmentFingerprint struct {
	SchemaVersion         int      `json:"schemaVersion"`
	Ecosystem             string   `json:"ecosystem"`
	OS                    string   `json:"os"`
	OSVersionBucket       string   `json:"osVersionBucket,omitempty"`
	Arch                  string   `json:"arch"`
	Runtime               string   `json:"runtime,omitempty"`
	RuntimeVersion        string   `json:"runtimeVersion,omitempty"`
	Language              string   `json:"language,omitempty"`
	LanguageVersion       string   `json:"languageVersion,omitempty"`
	Compiler              string   `json:"compiler,omitempty"`
	CompilerVersion       string   `json:"compilerVersion,omitempty"`
	PackageManager        string   `json:"packageManager,omitempty"`
	PackageManagerVersion string   `json:"packageManagerVersion,omitempty"`
	ModuleSystem          string   `json:"moduleSystem,omitempty"`
	Frameworks            []string `json:"frameworks,omitempty"`

	// ExecutionContext is an independent compatibility axis: where the
	// observed stage actually executed. Open vocabulary — well-known values
	// are "node", "browser", "webview", "electron", "webworker",
	// "serviceworker", "bun", "deno", "java"; new runtimes extend it without a
	// schema change. Build/test observations record the toolchain context
	// (a browser-targeting build still executes in node); browser-context
	// evidence only comes from stages that truly ran there.
	ExecutionContext string `json:"executionContext,omitempty"`
	// Browser dimensions, set only when ExecutionContext is a browser-like
	// runtime. Normalized locally — the raw User-Agent never leaves the
	// machine (fingerprinting is not the goal; API compatibility is).
	BrowserFamily string `json:"browserFamily,omitempty"` // chrome|edge|firefox|safari|chromium|android-webview|ios-wkwebview|electron
	BrowserMajor  string `json:"browserMajor,omitempty"`  // "140" — already a bucket
	Engine        string `json:"engine,omitempty"`        // chromium|gecko|webkit
	EngineVersion string `json:"engineVersion,omitempty"`

	// Virtualization says where the toolchain ran relative to real
	// hardware: "container", "vm", "wsl", or empty for bare metal /
	// undetectable. A build inside a container is a different
	// compatibility population than the host that started it, and
	// recording both as plain "linux" makes the graph lie.
	Virtualization string `json:"virtualization,omitempty"`
	// ContainerRuntime names the engine when one is detectable:
	// docker | podman | containerd | kubernetes | lxc.
	ContainerRuntime string `json:"containerRuntime,omitempty"`
	// Libc separates musl (alpine) from glibc. This single dimension
	// explains a large share of "works on my machine" for anything with a
	// native module: prebuilt binaries routinely load on one and fail on
	// the other while every other dimension looks identical.
	Libc string `json:"libc,omitempty"`
	// LibcVersion is the glibc version, when the libc is glibc: "2.35".
	//
	// musl versus glibc is the first thing that stops a native module
	// loading on Linux, and the glibc VERSION is the second. Prebuilt
	// wheels and node binaries target a floor — manylinux2014 is glibc
	// 2.17, manylinux_2_28 is 2.28 — and a binary built against 2.35 fails
	// on 2.31 with "GLIBC_2.34 not found". Reporting only the family made a
	// sample verified on Ubuntu 24.04 an EXACT match for a caller on
	// CentOS 7, which is precisely the case this project exists to catch.
	//
	// It is a property of the platform, like the OS itself, and identifies
	// nobody. Empty on musl and on non-Linux.
	LibcVersion string `json:"libcVersion,omitempty"`
	// Distro is the /etc/os-release ID: "ubuntu", "debian", "alpine".
	//
	// osVersionBucket carries only the version NUMBER, so Ubuntu 22 and
	// any other distribution's 22 were the same bucket. The number means
	// nothing without the name beside it.
	Distro string `json:"distro,omitempty"`
	// CI marks an automated runner. CI fleets are clones of each other, so
	// this is recorded to let aggregation discount them rather than treat
	// them as many independent developer environments (goal.md §16.5).
	CI bool `json:"ci,omitempty"`
}

EnvironmentFingerprint is a schema-versioned sparse description of the environment an observation or verification happened in (goal.md §7.3). Dimensions meaningless for a language are simply omitted.

func (EnvironmentFingerprint) Bucketed

func (e EnvironmentFingerprint) Bucketed() EnvironmentFingerprint

Bucketed returns a copy with version fields reduced to major.minor buckets, the privacy-lowering form used in web aggregates (goal.md §7.3).

func (EnvironmentFingerprint) ContextLabel

func (e EnvironmentFingerprint) ContextLabel() string

ContextLabel renders the execution-context axis for display and aggregation row keys: "chrome 140", "node 22.18", "safari 19".

func (EnvironmentFingerprint) Hash

func (e EnvironmentFingerprint) Hash() string

Hash returns the stable content id of the fingerprint.

func (EnvironmentFingerprint) Normalize

func (e EnvironmentFingerprint) Normalize() EnvironmentFingerprint

Normalize fills derivable fields: a bare runtime implies its execution context, and browser fields imply engine family where unambiguous. It also erases placeholder values, so an undetected dimension is absent rather than present-and-different.

type EvidenceClass

type EvidenceClass string

EvidenceClass separates weak co-occurrence evidence from strong verification evidence (goal.md §6.1).

const (
	ClassUsageObservation       EvidenceClass = "USAGE_OBSERVATION"
	ClassAdoptionEvidence       EvidenceClass = "ADOPTION_EVIDENCE"
	ClassSampleVerification     EvidenceClass = "SAMPLE_VERIFICATION"
	ClassRuntimeInstrumentation EvidenceClass = "RUNTIME_INSTRUMENTATION"
)

type EvidenceQuality

type EvidenceQuality string

EvidenceQuality states how much of a failed execution was preserved. LegacyIncomplete is reserved for records written before this contract; it prevents a historical hash from masquerading as complete modern evidence.

const (
	EvidenceComplete         EvidenceQuality = "complete"
	EvidencePartial          EvidenceQuality = "partial"
	EvidenceMissing          EvidenceQuality = "missing"
	EvidenceLegacyIncomplete EvidenceQuality = "legacy-evidence-incomplete"
)

type EvidenceSummary

type EvidenceSummary struct {
	ProjectCompileObservations int64    `json:"projectCompileObservations"`
	CleanBuilds                int64    `json:"cleanBuilds"`
	ContractPasses             int64    `json:"contractPasses"`
	IndependentCrossPeers      int64    `json:"independentCrossPeers"`
	UniquePeerBuckets          int64    `json:"uniquePeerBuckets"`
	PassRate                   float64  `json:"passRate"`
	Confidence                 string   `json:"confidence"` // HIGH | MEDIUM | LOW
	ElevatedFailures           []string `json:"elevatedFailures,omitempty"`
	LastSeen                   string   `json:"lastSeen,omitempty"`
}

EvidenceSummary carries the honest numbers behind a result (goal.md §11.5). Compile observations are co-occurrence evidence, never execution proof.

type FailureDomain

type FailureDomain string

FailureDomain classifies an inferred failure cause (goal.md §6.4). Uncertain causes MUST stay UNKNOWN or be expressed as hypotheses.

const (
	FailCode                 FailureDomain = "CODE"
	FailAPIRemovedOrChanged  FailureDomain = "API_REMOVED_OR_CHANGED"
	FailLibraryRegression    FailureDomain = "LIBRARY_REGRESSION"
	FailTransitiveDependency FailureDomain = "TRANSITIVE_DEPENDENCY"
	FailRuntime              FailureDomain = "RUNTIME"
	FailBrowser              FailureDomain = "BROWSER"
	FailEngine               FailureDomain = "ENGINE"
	FailOS                   FailureDomain = "OS"
	FailArch                 FailureDomain = "ARCH"
	FailToolchain            FailureDomain = "TOOLCHAIN"
	FailConfiguration        FailureDomain = "CONFIGURATION"
	FailExternalService      FailureDomain = "EXTERNAL_SERVICE"
	FailResource             FailureDomain = "RESOURCE"
	FailSecurityPolicy       FailureDomain = "SECURITY_POLICY"
	FailUnknown              FailureDomain = "UNKNOWN"
)

type FailureEnvironmentVariant

type FailureEnvironmentVariant struct {
	Environment EnvironmentFingerprint `json:"environment,omitempty"`
	Summary     map[string]string      `json:"summary,omitempty"`
	Count       int64                  `json:"count"`
	FirstSeen   string                 `json:"firstSeen,omitempty"`
	LastSeen    string                 `json:"lastSeen,omitempty"`
}

FailureEnvironmentVariant is one exact recorded environment bucket inside a cluster fingerprint. Keeping variants outside the cluster identity avoids cardinality explosions while preserving where the failure reproduced.

type FailureEvidence

type FailureEvidence struct {
	TerminationKind TerminationKind      `json:"terminationKind,omitempty"`
	ExitCode        *int                 `json:"exitCode,omitempty"`
	Signal          string               `json:"signal,omitempty"`
	TimeoutMillis   int64                `json:"timeoutMillis,omitempty"`
	ErrorSummary    string               `json:"errorSummary,omitempty"`
	ErrorCode       string               `json:"errorCode,omitempty"`
	Fingerprint     string               `json:"fingerprint,omitempty"`
	EvidenceQuality EvidenceQuality      `json:"evidenceQuality"`
	OuterCommand    string               `json:"outerCommand,omitempty"`
	OuterStage      Stage                `json:"outerStage,omitempty"`
	ActualToolchain string               `json:"actualToolchain,omitempty"`
	StageEvidence   FailureStageEvidence `json:"stageEvidence,omitempty"`
	EvidenceGap     FailureEvidenceGap   `json:"evidenceGap,omitempty"`
}

FailureEvidence is safe public failure material. ErrorSummary is already normalized/redacted and capped; raw stdout/stderr never belongs here.

func (FailureEvidence) Termination

func (f FailureEvidence) Termination() FailureTermination

Termination returns the structured subset of f.

type FailureEvidenceGap

type FailureEvidenceGap string

FailureEvidenceGap states what the captured output could not prove.

const (
	FailureDiagnosticMissing FailureEvidenceGap = "diagnostic-missing"
	FailureStageUnknown      FailureEvidenceGap = "stage-unknown"
)

type FailureHypothesis

type FailureHypothesis struct {
	Domain     FailureDomain `json:"domain"`
	Confidence float64       `json:"confidence"`
}

FailureHypothesis is a probabilistic cause attribution.

type FailureStageEvidence

type FailureStageEvidence string

FailureStageEvidence is the bounded reason an actual failure stage was selected. It distinguishes structured proof, parser markers, and aggregate evidence without retaining raw logs.

const (
	FailureStageStructuredTermination  FailureStageEvidence = "structured-termination"
	FailureStageResolveDiagnostic      FailureStageEvidence = "resolve-diagnostic"
	FailureStageCompilerDiagnostic     FailureStageEvidence = "compiler-diagnostic"
	FailureStageTestRunnerDiagnostic   FailureStageEvidence = "test-runner-diagnostic"
	FailureStageBuildAggregate         FailureStageEvidence = "build-aggregate"
	FailureStageUnclassifiedDiagnostic FailureStageEvidence = "unclassified-diagnostic"
)

type FailureTermination

type FailureTermination struct {
	Kind          TerminationKind `json:"kind,omitempty"`
	ExitCode      *int            `json:"exitCode,omitempty"`
	Signal        string          `json:"signal,omitempty"`
	TimeoutMillis int64           `json:"timeoutMillis,omitempty"`
}

FailureTermination contains only structured process state. ExitCode is a pointer because exit 0 is a real value while nil means not recorded.

func (FailureTermination) FingerprintCoordinate

func (t FailureTermination) FingerprintCoordinate() string

FingerprintCoordinate is a stable, non-secret representation of the structured termination state used by the v2 cluster fingerprint.

func (FailureTermination) Structured

func (t FailureTermination) Structured() bool

type KnownFailure

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

KnownFailure names a failure cluster relevant to the requesting env.

type MatchGrade

type MatchGrade string

MatchGrade classifies how safely a search result fits the requesting environment (goal.md §11.4).

const (
	GradeExact              MatchGrade = "EXACT"
	GradeCompatible         MatchGrade = "COMPATIBLE"
	GradeAdaptationRequired MatchGrade = "ADAPTATION_REQUIRED"
	GradeReferenceOnly      MatchGrade = "REFERENCE_ONLY"
	GradeNoSafeMatch        MatchGrade = "NO_SAFE_MATCH"
)

type ObservationBatch

type ObservationBatch struct {
	SchemaVersion    int                    `json:"schemaVersion"`
	Epoch            string                 `json:"epoch"` // daily bucket "2026-08-13"
	AnonID           string                 `json:"anonId"`
	ProjectBucket    string                 `json:"projectBucket"`
	Package          string                 `json:"package"`
	Symbol           string                 `json:"symbol,omitempty"`
	SymbolConfidence SymbolConfidence       `json:"symbolConfidence,omitempty"`
	Environment      EnvironmentFingerprint `json:"environment"`
	Stage            Stage                  `json:"stage"`
	Result           Result                 `json:"result"`
	ObservationCount int                    `json:"observationCount"`
	ErrorFingerprint string                 `json:"errorFingerprint,omitempty"`
	ErrorCode        string                 `json:"errorCode,omitempty"`
	// Structured failure evidence. These optional fields preserve wire
	// compatibility with pre-v2 clients; an omitted quality on a FAIL is
	// stored as legacy-evidence-incomplete, never upgraded by inference.
	TerminationKind    TerminationKind      `json:"terminationKind,omitempty"`
	ExitCode           *int                 `json:"exitCode,omitempty"`
	Signal             string               `json:"signal,omitempty"`
	TimeoutMillis      int64                `json:"timeoutMillis,omitempty"`
	ErrorSummary       string               `json:"errorSummary,omitempty"`
	EvidenceQuality    EvidenceQuality      `json:"evidenceQuality,omitempty"`
	OuterCommand       string               `json:"outerCommand,omitempty"`
	OuterStage         Stage                `json:"outerStage,omitempty"`
	ActualToolchain    string               `json:"actualToolchain,omitempty"`
	StageEvidence      FailureStageEvidence `json:"stageEvidence,omitempty"`
	FailureEvidenceGap FailureEvidenceGap   `json:"evidenceGap,omitempty"`
	// Direct says the reporter listed this package in their own manifest
	// rather than receiving it through somebody else's.
	//
	// Every adapter already works this out from the lockfile and it never
	// left the machine, so the network could not tell demand from gravity: a
	// transitive dependency pulled into a thousand lockfiles outranks a
	// package fifty people actually chose, and ranking authoring work by raw
	// observation count ranked the shadow of popular packages.
	//
	// It costs nothing in privacy. One bit about a public package, and that
	// somebody wrote it down is already implied by observing it at all.
	Direct bool `json:"direct,omitempty"`
	// Coresident is the other versions of THIS library present in the same
	// resolution.
	//
	// One library installed at two versions is the commonest reason a build
	// does not work, and the server cannot work it out: this batch carries a
	// single package, so a lockfile arrives already shredded and the finest
	// grouping left is a project and a day. A project that builds twice in an
	// afternoon against different lockfiles produces exactly the input that
	// would be read as a collision, so pairing server-side is inference. The
	// scanner holds the lockfile at once, so it reports the fact instead.
	//
	// Version strings of a package whose name is already being sent. Nothing
	// new about the project leaves the machine.
	Coresident []string `json:"coresident,omitempty"`
	// DependsOn is the packages THIS one pulled in this resolution, as purls.
	//
	// Coresident says two versions of a library were installed together;
	// this says who wanted each. Knowing only that there are two is the half
	// of the answer nobody can act on.
	//
	// Both ends are public — an edge between two public packages is already
	// registry information, and npm will tell anyone that a@1.2.0 depends on
	// b. Edges with a private end are dropped before this is built.
	DependsOn []string `json:"dependsOn,omitempty"`
}

ObservationBatch is the anonymous automatic-evidence wire unit (goal.md §7.6). It must never carry source, paths, project names, or raw logs — only the fields below.

type ObservedCell

type ObservedCell struct {
	Environment ObservedEnvironment `json:"environment"`
	Stage       string              `json:"stage"`
	Pass        int64               `json:"pass"`
	Fail        int64               `json:"fail"`
	// Reporters is the peak number of distinct reporting PEER BUCKETS in a
	// single epoch, never a sum across days: one peer building all afternoon
	// is one data point, and summing would let a single caller manufacture
	// volume.
	//
	// It is filled from UniquePeerBuckets (internal/httpapi/relay.go), and a
	// peer id is the hash of a self-generated key with no registration
	// behind it. It is not a count of machines and not a count of people —
	// one operator holds as many keys as they run workers. What it does mean
	// is real: the same coordinate was reported from more than one place.
	Reporters int    `json:"reporters"`
	LastSeen  string `json:"lastSeen,omitempty"`
}

ObservedCell is one (environment, stage) tally exactly as recorded. It is counts and coordinates — no grade, no confidence, no score, no sample.

type ObservedEnvironment

type ObservedEnvironment struct {
	OS             string `json:"os,omitempty"`
	Arch           string `json:"arch,omitempty"`
	Runtime        string `json:"runtime,omitempty"`
	RuntimeVersion string `json:"runtimeVersion,omitempty"`
	PackageManager string `json:"packageManager,omitempty"`
	Libc           string `json:"libc,omitempty"`
	Context        string `json:"context,omitempty"`
}

ObservedEnvironment is the closed set of environment dimensions a relayed observation may carry. It is a fixed projection rather than the whole fingerprint: the full record has ~25 fields including distro, libc version, container runtime, virtualization, frameworks and CI, and shipping those against a stable anonymous id is a fingerprint, not a measurement.

type ObservedError

type ObservedError struct {
	Stage       string            `json:"stage"`
	ErrorCode   string            `json:"errorCode,omitempty"`
	Fingerprint string            `json:"fingerprint,omitempty"`
	Count       int64             `json:"count"`
	Environment map[string]string `json:"environment,omitempty"`
	// Reporters and Projects say how widespread the failure is, in peer
	// buckets and project buckets rather than in machines or people. Count
	// alone is misleading: one peer building all afternoon reports thousands
	// of occurrences and proves nothing about anyone else.
	Reporters int `json:"reporters,omitempty"`
	Projects  int `json:"projects,omitempty"`
}

ObservedError is one recorded failure signature. ErrorCode is a public identifier such as ERR_REQUIRE_ESM; no error text ever travels.

type ObservedReports

type ObservedReports struct {
	PURL   string          `json:"purl"`
	Symbol string          `json:"symbol,omitempty"`
	Cells  []ObservedCell  `json:"cells,omitempty"`
	Errors []ObservedError `json:"errors,omitempty"`
	// Basis is always ObservedBasis. It is stated on the wire so a reader
	// cannot mistake the payload for verification by omission.
	Basis string `json:"basis"`
	// Note restates the limit in words for a model that skims structure.
	Note string `json:"note"`
}

ObservedReports is what the network already recorded about a coordinate when it has no verified sample to offer. It is RELAYED, never asserted: the project stands behind the samples it ran and the findings it detected, and these are neither. The grade stays NO_SAFE_MATCH — nothing here has been proven for the caller's case — and this payload is the difference between saying so with an empty hand and saying so while handing over everything already known.

type PURL

type PURL struct {
	Ecosystem string
	Name      string
	Version   string
}

PURL identifies a public package as pkg:<ecosystem>/<name>@<version>. Ecosystems in Public v1: npm, pypi, cargo, golang, maven. golang names may contain '/' (module paths); npm names may be scoped (@scope/name).

func ParsePURL

func ParsePURL(s string) (PURL, error)

ParsePURL parses a package URL string. It accepts both canonical percent-encoded scoped npm names (pkg:npm/%40scope/name@1.0.0) and the lenient raw form (pkg:npm/@scope/name@1.0.0).

func PublicTargetFromDescriptor

func PublicTargetFromDescriptor(value string) (PURL, bool)

PublicTargetFromDescriptor converts a public, versioned target descriptor such as "unity@6000.0.24f1", "jdk@21" or "git@2.51.0" into a generic purl. generic namespace avoids pretending engines, SDKs, OSes and CLI tools are library-registry ecosystems while still fitting the privacy-reduced Wanted wire.

func WantedTargetFromFramework

func WantedTargetFromFramework(value string) (PURL, bool)

WantedTargetFromFramework keeps the original call surface used by clients that derive engine/SDK targets from Environment.Frameworks. New callers that name a CLI or OS explicitly should use PublicTargetFromDescriptor.

func (PURL) AnyVersionPattern

func (p PURL) AnyVersionPattern() string

AnyVersionPattern is this package under any version, in the CANONICAL stored form, for a SQL LIKE prefilter.

String() escapes a leading "@" to "%40", so a scoped npm package is stored as pkg:npm/%40types/node@20.0.0 — and callers that built the pattern from the raw name asked for pkg:npm/@types/node@%, which matches nothing. Every scoped package (@types/*, @babel/*, @tanstack/*, a large share of npm) silently failed to find its own samples.

The escaped "%40" leaves a literal % in the pattern, which LIKE reads as a wildcard. That makes the prefilter slightly looser, never tighter, and the exact ecosystem/name comparison downstream is what decides.

func (PURL) BreakingBucket

func (p PURL) BreakingBucket() string

BreakingBucket returns the version line within which semver promises no breaking change: "1" for 1.2.3, but "0.6" for 0.6.20.

Major() is deliberately NOT this, because it also generates shard keys and changing it would invalidate every shard. But grading with it treated 0.x as a stable major, so axum 0.6 against 0.8 was reported as a minor difference when semver makes a 0.x minor bump exactly as breaking as a major one. Pre-1.0 is where most Rust and a lot of Dart lives.

func (PURL) Major

func (p PURL) Major() string

Major returns the major version bucket used for shard keys. golang keeps its "v" prefix ("v1"); other ecosystems return the bare first segment ("1").

func (PURL) MajorMinor

func (p PURL) MajorMinor() string

MajorMinor returns "major.minor" ("1.12"; golang "v1.2"). A version with a single segment returns just the major bucket.

func (PURL) String

func (p PURL) String() string

String renders the canonical purl form; a leading '@' in npm scoped names is percent-encoded per the PURL spec.

type Result

type Result string

Result of a stage.

const (
	ResultPass Result = "PASS"
	ResultFail Result = "FAIL"
)

type SampleManifest

type SampleManifest struct {
	SchemaVersion int      `json:"schemaVersion"`
	Case          Case     `json:"case"`
	Packages      []string `json:"packages"`
	Symbols       []string `json:"symbols,omitempty"`
	// Subject is the ONE package this sample is about, when it is known.
	//
	// A receipt resolves the whole lockfile, and the snapshot targets used to
	// be the cartesian product of that against every declared symbol. A
	// Sinatra sample tested with minitest therefore filed Sinatra::Base under
	// minitest, rack and three more; production had 680 symbols claimed by
	// more than one package and one claimed by 21. Without this the owner has
	// to be inferred from which sample resolved the fewest packages, which
	// works and is a guess.
	//
	// The authoring queue assigns an exact coordinate, so the guess is
	// unnecessary for anything it produced. Optional and omitempty: every
	// sample authored before this field existed still hashes to the same
	// content address, and the inference covers them.
	Subject         string                 `json:"subject,omitempty"`
	Environment     EnvironmentFingerprint `json:"environment"`
	License         string                 `json:"license"` // default MIT-0
	BuildCommand    []string               `json:"buildCommand,omitempty"`
	ContractCommand []string               `json:"contractCommand"`
	VerifierAdapter string                 `json:"verifierAdapter"`
}

SampleManifest is the csx.json descriptor inside a sample artifact (goal.md §7.5).

type SandboxCapability

type SandboxCapability string

SandboxCapability declares what isolation a verifying peer can provide (goal.md §16.3).

const (
	CapCompileOnly        SandboxCapability = "COMPILE_ONLY"
	CapContainerRun       SandboxCapability = "CONTAINER_RUN"
	CapStrongIsolationRun SandboxCapability = "STRONG_ISOLATION_RUN"
	CapLiveIntegration    SandboxCapability = "LIVE_INTEGRATION"
)

type SearchProvenance

type SearchProvenance string

SearchProvenance records whether search input was declared by the caller or inferred from ambient project/error context. The empty value is deliberate: it is the third state needed to distinguish legacy JSON from an explicit declaration at a protocol boundary.

const (
	SearchProvenanceExplicit SearchProvenance = "explicit"
	SearchProvenanceContext  SearchProvenance = "context"
)

type SearchRequest

type SearchRequest struct {
	SchemaVersion int      `json:"schemaVersion"`
	Query         string   `json:"query"`
	Packages      []string `json:"packages,omitempty"`
	// ProjectPackages is the caller's dependency tree, filled in
	// automatically rather than named by the caller. It ranks: a sample
	// about something already in the tree is more likely to be the one
	// wanted. It must never GRADE, because the caller did not ask about it.
	//
	// Splitting it out fixed the worst hit-rate defect the project has had.
	// `csx search` fills packages from the lockfile, so asking "freeze the
	// clock in a python test" inside a Go checkout arrived carrying two
	// unrelated Go purls; the grader read that as "you asked about these
	// packages and this sample is about none of them", returned
	// REFERENCE_ONLY, and the multiplier put the correct freezegun sample
	// at 0.105 against a 0.25 miss threshold. From an empty directory the
	// same query scored 0.27 and answered correctly.
	//
	// An agent is always inside SOME project, and the library it asks about
	// is usually one it is about to add — so the dominant real case was the
	// broken one.
	ProjectPackages []string `json:"projectPackages,omitempty"`
	// ContextSymbols are scanner/error-derived context. They may improve ranking,
	// but unlike Symbols they were not declared by the caller and therefore
	// must never exclude a candidate.
	ContextSymbols []string `json:"contextSymbols,omitempty"`
	Symbols        []string `json:"symbols,omitempty"`
	// SymbolProvenance is explicit on public/MCP requests and context for
	// scanner-derived local requests. A new CLI also populates Symbols for an
	// old daemon; the new daemon uses this marker to avoid treating that legacy
	// compatibility copy as an exclusion.
	SymbolProvenance SearchProvenance       `json:"symbolProvenance,omitempty"`
	Environment      EnvironmentFingerprint `json:"environment"`
	// EnvironmentProvenance records whether ecosystem-scoped dimensions came
	// from the caller or the current project. Only context dimensions may be
	// softened when the candidate belongs to another ecosystem.
	EnvironmentProvenance SearchProvenance `json:"environmentProvenance,omitempty"`
	ErrorFingerprint      string           `json:"errorFingerprint,omitempty"`
	// ErrorFingerprints is the same error hashed for every stage it could
	// have been recorded under. A caller pasting a build log knows the
	// error, not the stage it was observed at.
	ErrorFingerprints []string `json:"errorFingerprints,omitempty"`
	ErrorCode         string   `json:"errorCode,omitempty"`
	Limit             int      `json:"limit,omitempty"` // default 3
	// Debug requests a local diagnostic trace. It never changes ranking or
	// grading and is not part of the frozen public v1 request.
	Debug bool `json:"debug,omitempty"`
}

SearchRequest is the in-process superset shared by the local daemon, MCP, and public search. Public v1 uses only its frozen original fields; v2 owns provenance/context additions (goal.md §11.1).

func (SearchRequest) EnvironmentIsContext

func (r SearchRequest) EnvironmentIsContext() bool

EnvironmentIsContext is fail-closed: absent/unknown provenance is explicit. The local daemon is the only boundary allowed to translate a proven legacy CLI request into context provenance.

type SearchResponse

type SearchResponse struct {
	SchemaVersion int            `json:"schemaVersion"`
	Results       []SearchResult `json:"results"`
	Miss          bool           `json:"miss"`
	// Observed rides on a MISS and only on a miss. It hangs off the response
	// rather than off a result so it can never be read as a property of a
	// sample, and so the grade path never has it in scope.
	Observed *ObservedReports `json:"observed,omitempty"`
	// Diagnostic is present only when SearchRequest.Debug was true. It is
	// generated from the same pipeline result and never changes the answer.
	Diagnostic *DiagnosticTrace `json:"diagnostic,omitempty"`
}

SearchResponse: Miss=true means NO_SAFE_MATCH — deliberately better than a wrong HIT (goal.md §3.8).

type SearchResult

type SearchResult struct {
	Grade        MatchGrade `json:"match"`
	Confidence   string     `json:"confidence"`
	Score        float64    `json:"score"`
	Case         *Case      `json:"case,omitempty"`
	SampleID     string     `json:"sampleId,omitempty"`
	SampleStatus string     `json:"sampleStatus,omitempty"`
	// ExactFailureMatched is true only when one of the caller's sanitized
	// error fingerprints equalled a recorded failure for a nonempty symbol
	// declared by this candidate, and the selected nonempty contract passed.
	// An error code, package match, different-symbol cluster, or semantic hit
	// must never set it.
	ExactFailureMatched bool            `json:"exactFailureMatched"`
	Exact               []string        `json:"exact"`
	Different           []string        `json:"different"`
	Adaptation          []string        `json:"adaptationNeeded"`
	Evidence            EvidenceSummary `json:"evidence"`
	KnownFailures       []KnownFailure  `json:"knownFailures,omitempty"`
}

SearchResult is one ranked answer with its environment delta (goal.md §11.5): the LLM reasons over Different/Adaptation, not the whole problem.

func DedupeResultsByCoordinate

func DedupeResultsByCoordinate(results []SearchResult) []SearchResult

DedupeResultsByCoordinate keeps one result per (packages, symbols) coordinate.

Two samples for the same coordinate are the same answer twice. Side by side they burn the caller's result budget and, worse, read as corroboration -- two independent sources agreeing -- when they are one coordinate measured twice by the same fleet. The corpus reached 37% duplicates before the work queue stopped issuing the same coordinate repeatedly, and the ones already published do not disappear on their own.

This hides rather than withdraws. A duplicate is still evidence and still answers its own sample page; quarantine is for a takedown, not for tidiness, and using it here would delete work the network paid for.

It lives in domain because BOTH search surfaces apply it: the server's HTTP handler and the local engine behind search_known_solution. Folding one and not the other left the primary agent surface returning the same coordinate twice in its three-result window.

The input is expected in descending score order, so the first result for a coordinate is the best one; the ordering is preserved otherwise.

func (SearchResult) ConfidenceReason

func (r SearchResult) ConfidenceReason() string

ConfidenceReason explains, in one clause, what this result's confidence level is actually about.

Confidence is a statement about INDEPENDENCE: MEDIUM needs two separate peer buckets to have run the thing, HIGH needs three plus volume. It is counted in peer buckets and it is described in peer buckets — the value this function reads is literally UniquePeerBuckets, and a peer id is the hash of a self-generated key with no registration behind it. Calling that a machine, which this text did, promised a head count the network never measured and cannot. On a young network almost nothing has that, so almost every answer reads "CONFIDENCE: LOW" -- next to a sample whose contract passed in a pinned container with the network off. A reader takes that as "this answer is probably wrong", which is not what it says and not what the evidence shows. Naming the reason costs one clause and stops the label from arguing against the evidence printed beside it.

func (SearchResult) RecommendationClassification

func (r SearchResult) RecommendationClassification() (classification string, advisoryOnly bool, reason string)

RecommendationClassification is shared by MCP and agent hooks. LOW confidence, reference-only grades, and anything requiring adaptation are supporting candidates, never an automatic fix basis.

func (SearchResult) RelevanceLine

func (r SearchResult) RelevanceLine(req SearchRequest, argv []string) string

RelevanceLine is the one-line, mechanically generated justification that travels with a candidate that passed the gate. A reader who cannot see why a sample was shown has no way to judge it, and "it scored 0.67" is not a reason — it is the absence of one.

func (SearchResult) RelevanceSignals

func (r SearchResult) RelevanceSignals(req SearchRequest, argv []string) []string

RelevanceSignals names every concrete link between this request and this candidate, in a stable order. An empty result means the only thing the two have in common is where they run.

func (SearchResult) RelevantToRequest

func (r SearchResult) RelevantToRequest(req SearchRequest, argv []string) bool

RelevantToRequest reports whether this candidate may be rendered as normal output for this request.

A candidate that declares no subject at all — no case, so no goal, no packages, no symbols — is not judged. The gate reads what a sample says it is ABOUT, and with nothing to read the honest answer is "no opinion", not "irrelevant": calling it irrelevant would be a verdict reached from the absence of evidence. Both producers attach the case, so this is the shape of a degenerate payload rather than of a weak answer.

func (SearchResult) SampleEcosystems

func (r SearchResult) SampleEcosystems() []string

SampleEcosystems lists the non-generic ecosystems this result's packages belong to, in the order they appear. It exists so a demoted candidate can state WHY it was demoted with the same words the gate used.

func (SearchResult) SuppressionReason

func (r SearchResult) SuppressionReason(req SearchRequest, argv []string) string

SuppressionReason is the stable code for why this candidate did not reach normal output, or "" when it did.

argv is empty on the paths that answered a QUESTION rather than a command, and there the ecosystem gate must not run at all: it reads an empty argv as "this command builds for no ecosystem I know" and rejects every pinned sample on that basis, which is a verdict about a command that never ran.

func (SearchResult) UnrelatedToCommand

func (r SearchResult) UnrelatedToCommand(argv []string) bool

UnrelatedToCommand reports whether this result is about an ecosystem the command that just failed does not build for.

It is the relevance gate every unasked recommendation shares — the MCP lookup after a wrapped command and the agent hooks alike — so that one definition of "this is the wrong language" cannot drift into two.

The exemption is an exact failure-fingerprint match. That is the sanitized identity of THIS failure having been seen against THAT sample, which is an explicit evidence link between the two and outranks any argument from ecosystem: a Node build breaking on a native module is genuinely answered by whatever recorded the same fingerprint, whatever language it was written in. Nothing else earns the exemption; a grade does not, because a grade is a statement about where a sample can run and never about the error in hand.

func (SearchResult) VerifiedOffer

func (r SearchResult) VerifiedOffer() bool

VerifiedOffer reports whether this result is safe to offer as already verified in the caller's environment. A contract PASS is necessary but not sufficient: adaptation, any disclosed difference, and reference-only grades all require the caller to verify again.

type Stage

type Stage string

Stage names an observed or verified pipeline step. Observation stages (weak, project-level — goal.md §6.1.A) are PROJECT_*; verification stages (strong, per-sample — §6.3) are the bare names.

const (
	StageUsed             Stage = "USED"
	StageProjectTypecheck Stage = "PROJECT_TYPECHECK"
	StageProjectResolve   Stage = "PROJECT_RESOLVE"
	StageProjectCompile   Stage = "PROJECT_COMPILE"
	StageProjectTest      Stage = "PROJECT_TEST"
	StageProjectProcess   Stage = "PROJECT_PROCESS"
	// PROCESS_START and UNKNOWN are failure-only observation stages. The
	// former is proven by a structured spawn error; the latter prevents an
	// outer command name from being promoted to an actual failure stage when
	// the captured diagnostics do not establish where execution stopped.
	StageProcessStart Stage = "PROCESS_START"
	StageUnknown      Stage = "UNKNOWN"
	// PROJECT_LOAD observes module/library load in the executing context
	// (import succeeded in node/bun/deno/browser) without asserting more.
	StageProjectLoad Stage = "PROJECT_LOAD"

	// Runtime-instrumentation stages (evidence class
	// RUNTIME_INSTRUMENTATION, goal.md §6.1.D). Emitted ONLY by adapters
	// with A3 capability that directly observed the call — never inferred.
	// No Public v1 adapter claims A3; the stages exist so browser/worker
	// instrumentation can contribute without a schema change.
	// SYMBOL_EXECUTED result is always PASS (execution observed, outcome
	// not asserted). SYMBOL_CALL result PASS = returned, FAIL = threw.
	StageSymbolExecuted Stage = "SYMBOL_EXECUTED"
	StageSymbolCall     Stage = "SYMBOL_CALL"

	StageResolve   Stage = "RESOLVE"
	StageSymbol    Stage = "SYMBOL"
	StageTypecheck Stage = "TYPECHECK"
	StageCompile   Stage = "COMPILE"
	StageLoad      Stage = "LOAD"
	StageExecute   Stage = "EXECUTE"
	StageTest      Stage = "TEST"
	StageContract  Stage = "CONTRACT"
)

type SuppressedCandidate

type SuppressedCandidate struct {
	SampleID   string     `json:"sampleId,omitempty"`
	Packages   []string   `json:"packages,omitempty"`
	Grade      MatchGrade `json:"match,omitempty"`
	Confidence string     `json:"confidence,omitempty"`
	Score      float64    `json:"score,omitempty"`
	Reason     string     `json:"suppressedReason"`
	Signals    []string   `json:"relevanceSignals,omitempty"`
}

SuppressedCandidate is a retrieval candidate that did not reach normal output, kept so the decision is observable rather than invisible.

Retrieval and rendering are different questions and this type is the seam between them: the engine found something, and the output layer declined to present it as an answer. It carries the coordinate and the reason, never the sample body — a suppressed candidate that ships its contract has not been suppressed.

type SymbolConfidence

type SymbolConfidence string

SymbolConfidence expresses how sure static analysis is about a symbol resolution (goal.md §7.2).

const (
	SymbolExact    SymbolConfidence = "EXACT"
	SymbolProbable SymbolConfidence = "PROBABLE"
	SymbolUnknown  SymbolConfidence = "UNKNOWN"
)

type TerminationKind

type TerminationKind string

TerminationKind is the structured way an executable stage ended. An empty value means the producer did not establish termination; it is never another spelling of "exit code unavailable".

const (
	TerminationExit               TerminationKind = "exit"
	TerminationSignal             TerminationKind = "signal"
	TerminationTimeout            TerminationKind = "timeout"
	TerminationProcessStartFailed TerminationKind = "process-start-failed"
)

type VerificationLevel

type VerificationLevel string

VerificationLevel grades how far a sample has been verified (goal.md §6.2).

const (
	L0SourceOnly   VerificationLevel = "L0_SOURCE_ONLY"
	L1Resolved     VerificationLevel = "L1_RESOLVED"
	L2Compiled     VerificationLevel = "L2_COMPILED"
	L3ContractPass VerificationLevel = "L3_CONTRACT_PASS"
	L4CrossPass    VerificationLevel = "L4_CROSS_PASS"
	L5MatrixPass   VerificationLevel = "L5_MATRIX_PASS"
)

type VerificationReceipt

type VerificationReceipt struct {
	SchemaVersion   int                    `json:"schemaVersion"`
	SampleID        string                 `json:"sampleId"`
	CaseID          string                 `json:"caseId"`
	EnvironmentHash string                 `json:"environmentHash"`
	Environment     EnvironmentFingerprint `json:"environment"`
	Stages          map[string]string      `json:"stages"` // stage → PASS|FAIL|SKIPPED
	// StageFailures carries secret-safe structured evidence only for failed
	// stages. Full logs remain local and LogsDigest continues to attest to
	// them without publishing their contents.
	StageFailures map[string]FailureEvidence `json:"stageFailures,omitempty"`
	// ResolvedPackages is what the resolve stage ACTUALLY installed, read
	// out of the lockfile it generated, as purls.
	//
	// Without it a receipt takes the version from the manifest, which the
	// sample's author wrote and the verification never checked — a claim
	// where this project promises evidence. It is also the axis a
	// regression farm needs: the same contract run against three releases
	// produced three receipts that said exactly the same thing, so there
	// was nowhere for "passes at 2.3, fails at 2.2" to live.
	//
	// Empty means NOT ESTABLISHED, never "matches the manifest". A
	// lockfile that cannot be read yields nothing rather than a guess.
	ResolvedPackages []string `json:"resolvedPackages,omitempty"`
	// VerifierImage identifies the container image bytes the stages ran in.
	//
	// The receipt already named the environment — os, libc, runtime line —
	// but not WHICH image produced it, and a floating tag can put different
	// software behind the same label on two workers or on one worker at two
	// times. Without this field "the contract ran in a pinned container"
	// could not be checked from the receipt at all; with it, a caller can
	// take the reference and re-run the same bytes.
	//
	// Signed like everything else here: it is part of the canonical JSON the
	// peer signature covers, so it cannot be attached after the fact.
	//
	// A nil pointer means NOT ESTABLISHED, never "the default image". The
	// native fallback runner has no image, and receipts signed before this
	// field existed carry none — those must not be read as a claim about
	// which bytes ran.
	VerifierImage     *VerifierImage    `json:"verifierImage,omitempty"`
	VerifierAdapter   string            `json:"verifierAdapter"`
	SandboxCapability SandboxCapability `json:"sandboxCapability"`
	LogsDigest        string            `json:"logsDigest"`
	CreatedAt         string            `json:"createdAt"` // RFC3339
	PeerID            string            `json:"peerId"`
	PeerPubkey        string            `json:"peerPubkey"`    // base64 ed25519 public key
	PeerSignature     string            `json:"peerSignature"` // base64 over SigningBytes
}

VerificationReceipt is the immutable, signed record of one sample verification in one environment (goal.md §7.7).

func (VerificationReceipt) ReceiptID

func (r VerificationReceipt) ReceiptID() string

ReceiptID is the content hash identifying an immutable receipt.

func (VerificationReceipt) SigningBytes

func (r VerificationReceipt) SigningBytes() []byte

SigningBytes returns the canonical JSON the peer signature covers (the receipt with PeerSignature cleared).

type VerifierImage

type VerifierImage struct {
	// Reference is the canonical immutable reference, "<alias>@sha256:<hex>".
	// The alias is readable and the digest is the authority.
	Reference string `json:"reference"`
	// Digest is the registry content digest of the image index.
	//
	// Deliberately NOT the daemon's local image ID: that is a property of
	// the image store implementation, so two workers running byte-identical
	// images can report different IDs, and cross-worker agreement is the
	// whole point of recording this.
	Digest string `json:"digest"`
}

VerifierImage is the immutable identity of the container image a verification ran in.

Reference is what a re-run executes verbatim; Digest is the same content digest on its own so a store or an API can index and compare it without parsing a reference. They are required to agree, and the server rejects a receipt where they do not — two fields that can disagree are worth having only if something checks them.

type WorkerRequirements

type WorkerRequirements struct {
	SandboxCapability SandboxCapability `json:"sandboxCapability,omitempty"`
	VerifierAdapter   string            `json:"verifierAdapter,omitempty"`
	// OS is the container platform the sample's contract must run on
	// ("linux", "windows"). The queue filters offers on it and the receipt
	// check refuses a run from anywhere else; empty runs anywhere, which is
	// every job created before the field existed.
	OS               string   `json:"os,omitempty"`
	Ecosystem        string   `json:"ecosystem,omitempty"`
	Runtime          string   `json:"runtime,omitempty"`
	RuntimeVersion   string   `json:"runtimeVersion,omitempty"`
	ExecutionContext string   `json:"executionContext,omitempty"`
	BrowserFamily    string   `json:"browserFamily,omitempty"`
	BrowserMajor     string   `json:"browserMajor,omitempty"`
	Engine           string   `json:"engine,omitempty"`
	EngineVersion    string   `json:"engineVersion,omitempty"`
	Frameworks       []string `json:"frameworks,omitempty"`
}

WorkerRequirements is the closed, declarative description attached to a verification job. A worker must satisfy every non-empty field before it claims the job. This stays separate from EnvironmentFingerprint: it says what must be available, not where a result already ran.