domain

package
v0.1.10 Latest Latest
Warning

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

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

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

This section is empty.

Variables

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

AllowedEcosystems is the Public v1 automatic-collection allowlist (goal.md §8.1).

Functions

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 CompareVersions added in v0.1.4 

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 added in v0.1.5 

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 IsWantedTarget added in v0.1.7 

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 SHA256Hex 

func SHA256Hex(b []byte) string

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

Types

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 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"; 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 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 FailureHypothesis 

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

FailureHypothesis is a probabilistic cause attribution.

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"`
}

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 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. 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 WantedTargetFromFramework added in v0.1.7 

func WantedTargetFromFramework(value string) (PURL, bool)

WantedTargetFromFramework converts a public, versioned framework/toolchain descriptor such as "unity@6000.0.24f1" or "jdk@21" into a generic purl. The generic namespace avoids pretending engines and SDKs are registry ecosystems while still fitting the existing privacy-reduced Wanted wire.

func (PURL) AnyVersionPattern added in v0.1.5 

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 added in v0.1.4 

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"`
	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 added in v0.1.6 

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
}

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 added in v0.1.6 

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"`
}

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 (SearchResult) ConfidenceReason added in v0.1.5 

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 machines to have run the thing, HIGH needs three plus volume. 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) VerifiedOffer added in v0.1.6 

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"
	StageProjectCompile   Stage = "PROJECT_COMPILE"
	StageProjectTest      Stage = "PROJECT_TEST"
	StageProjectProcess   Stage = "PROJECT_PROCESS"
	// 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 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 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
	// 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"`
	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 WorkerRequirements added in v0.1.7 

type WorkerRequirements struct {
	SandboxCapability SandboxCapability `json:"sandboxCapability,omitempty"`
	Ecosystem         string            `json:"ecosystem,omitempty"`
	Runtime           string            `json:"runtime,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.

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.