core

package
v2026.0.143 Latest Latest
Warning

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

 Go to latest Published: Aug 22, 2026 License: MPL-2.0 Imports: 28 Imported by: 0

Documentation

Overview

Package core provides the typed, bounded contracts shared by Primitive.

Primitive is an open-source library that makes Go's standard library easier to compose. Core supplies closed protocol enums, checked numeric and digest values, lexical paths, strict JSON boundaries, stable error identities, and the package architecture catalog. Constructors parse or validate at ingress; Validate methods protect package crossings and external output. Stable errors support errors.Is and errors.As.

Index

Constants

View Source 
const (
	// PrimitiveModulePath is the canonical Go module path.
	PrimitiveModulePath = "github.com/deliri/primitive/v2026"
	// PrimitivePackagePathPrefix prefixes every Primitive package import path.
	PrimitivePackagePathPrefix = PrimitiveModulePath + "/"
	// PrimitivePackageCount is the number of packages in the complete catalog.
	PrimitivePackageCount = 41
	// PrimitiveDirectImportCount is the number of admitted direct import edges.
	PrimitiveDirectImportCount = 150
	// PrimitiveDirectTestImportCount is the number of admitted test-only edges.
	PrimitiveDirectTestImportCount = 31
	// PrimitiveMaximumDirectImports caps direct sibling imports per package.
	PrimitiveMaximumDirectImports = 10
)
View Source 
const (
	// RedactedValueText is the only text emitted when formatting secret material.
	RedactedValueText = "[REDACTED]"
	// SecretMaterialMinimumBytes is the minimum admitted material length.
	SecretMaterialMinimumBytes = 16
	// SecretMaterialMaximumBytes is the maximum admitted material length.
	SecretMaterialMaximumBytes = 64
	// SHA256DigestBytes is the exact binary width of SHA-256.
	SHA256DigestBytes = 32
)
View Source 
const (
	// ProtocolMemberAccount names the paying account a fact is scoped to.
	ProtocolMemberAccount = "account"
	// ProtocolMemberOffering names the product an account holds.
	ProtocolMemberOffering = "offering"
)

Protocol member names that more than one package spells.

A JSON member name is a protocol value: it is part of the bytes a signature covers and part of what a decoder matches on. When two packages each write the same name as its own literal, nothing in the build notices if one of them is later corrected and the other is not, and the two ends of an exchange disagree about a fact they both believe they agree on.

Only names that genuinely denote the same fact belong here. A name that one package happens to spell the same way while meaning something else is not shared vocabulary and must keep its own literal, so this set never becomes a bag of coincidentally equal strings.

View Source 
const (
	// SignalInterruptLabel is the shared compiler-owned label for an
	// interactive operating-system interrupt.
	SignalInterruptLabel = "interrupt"
	// SignalTerminateLabel is the shared compiler-owned label for an orderly
	// operating-system termination request.
	SignalTerminateLabel = "terminate"
)
View Source 
const (
	// TestIsolationCorePackagePath is the exact Core import recognized by the
	// pinned test-isolation analyzer.
	TestIsolationCorePackagePath = PrimitivePackagePathPrefix + "core"
	// TestIsolationDeclarationPackagePath is the exact declaration package
	// import recognized by the pinned test-isolation analyzer.
	TestIsolationDeclarationPackagePath = PrimitivePackagePathPrefix + "testserial"
	// TestIsolationDeclarationFunctionName is the exact declaration function
	// recognized by the testserial package and its pinned analyzer.
	TestIsolationDeclarationFunctionName = "Declare"
	// TestIsolationDeclarationTypeName is the exact aggregate declaration type
	// recognized by the pinned test-isolation analyzer.
	TestIsolationDeclarationTypeName = "TestIsolationDeclaration"
	// TestIsolationDeclarationHazardFieldName is the aggregate hazard field.
	TestIsolationDeclarationHazardFieldName = "Hazard"
	// TestIsolationDeclarationScopeFieldName is the aggregate scope field.
	TestIsolationDeclarationScopeFieldName = "Scope"
)
View Source 
const (
	// JSONDocumentMaximumBytes is the shared one-mebibyte document cap.
	JSONDocumentMaximumBytes = 1 << 20
	// CredentialedRequestDocumentSyntaxBytes is the exact outer punctuation
	// shared by request-plus-installation-certificate documents.
	CredentialedRequestDocumentSyntaxBytes = len(`{"request":,"certificate":}`)
	// CredentialedDocumentWhitespaceMaximumBytes is the shared allowance for
	// insignificant outer whitespace around one credentialed document.
	CredentialedDocumentWhitespaceMaximumBytes = 8 << 10
	// JSONNestingDepthMaximum is the open-container cap.
	JSONNestingDepthMaximum = 64
	// JSONObjectFieldCountMaximum is the per-object field cap.
	JSONObjectFieldCountMaximum = 256
)
View Source 
const (
	// CatalogPageMaximumEntries is the shared hard ceiling for one bounded
	// customer-visible catalog page.
	CatalogPageMaximumEntries = 100
)
View Source 
const (

	// FilesystemPathMaximumComponents bounds non-root lexical components.
	FilesystemPathMaximumComponents = 256
)
View Source 
const GoogleCloudStorageHost = "storage.googleapis.com"

GoogleCloudStorageHost is the canonical Google Cloud Storage data host.

It lives here rather than in one provider package because two of them need the same literal for different reasons: objectstore validates that a signed capability it was handed points at Cloud Storage, and gcsobjects names the address of an object it just published. Two copies of one protocol value is the duplication section 4.1 forbids, and the copy that drifts is the one nobody is looking at.

View Source 
const (

	// OfferingCanonicalJSONMaximumBytes is the maximum compact JSON string
	// extent of one Offering.
	OfferingCanonicalJSONMaximumBytes = offeringMaximumBytes + len(`""`)
)
View Source 
const ReaderConsecutiveEmptyReadMaximum = 100

ReaderConsecutiveEmptyReadMaximum is the common streaming refusal threshold for consecutive io.Reader results of (0, nil). The standard library permits that result transiently but defines io.ErrNoProgress for repeated instances; Primitive bounds the otherwise unending wait at this shared ceiling.

View Source 
const SchemeHTTPS = "https"

SchemeHTTPS is the HTTPS URL scheme.

Exported for the same reason as the host above: objectstore checks that an issued capability is HTTPS, and gcsobjects composes an object address, so the literal had two homes and would have grown a third.

View Source 
const (
	// UnknownEnumDiagnostic is the one diagnostic projection for a value that
	// is outside a compiler-owned enumeration domain.
	UnknownEnumDiagnostic = "unknown"
)

Variables

This section is empty.

Functions

func CheckedInt64FromUint64 

func CheckedInt64FromUint64(value uint64) (int64, error)

CheckedInt64FromUint64 converts value or returns ErrNumericOverflow.

func CheckedUint32FromInt 

func CheckedUint32FromInt(value int) (uint32, error)

CheckedUint32FromInt converts value or returns ErrNumericOverflow.

func CheckedUint64FromInt64 added in v2026.0.3 

func CheckedUint64FromInt64(value int64) (uint64, error)

CheckedUint64FromInt64 converts a non-negative value or returns ErrNumericOverflow.

func DecodeCanonicalHex added in v2026.0.37 

func DecodeCanonicalHex(destination []byte, value string) error

DecodeCanonicalHex fills destination from text that must be exact canonical lowercase hexadecimal for exactly len(destination) bytes: every input byte must already belong to the canonical lowercase alphabet, so uppercase, mixed case, odd extents, prefixes, and stray bytes are all refused. The destination carries the extent, so a fixed-size identity decodes into its own storage without an allocation and a variable one sizes its buffer first. Spelling is validated before decoding, so refusal leaves a populated destination unchanged. This is the one admission rule for canonical hex in the repository: identities in every package delegate here rather than restating the decode-and-re-encode comparison.

func DecodeJSONStringToken added in v2026.0.3 

func DecodeJSONStringToken(data []byte) (string, error)

DecodeJSONStringToken decodes one JSON string token into its exact Go string. It is the single owner of the repository's JSON string-token admission rule: absence, JSON null, invalid UTF-8, and unpaired surrogates are refused before any domain parse sees the value, so every typed enum and identity that arrives as a JSON string inherits one hardening contract instead of restating it. It enforces the shared JSON document ceiling before scanning or decoding; the owning caller remains responsible for any tighter domain-specific cap.

func DecodeStrictJSON 

func DecodeStrictJSON[T Validatable](reader io.Reader, limits StrictJSONLimits) (T, error)

DecodeStrictJSON reads one strict JSON document into T. It reads no more than the configured maximum plus one proof byte, bounds repeated empty reads, and preserves native reader failures. It rejects invalid UTF-8, unpaired JSON surrogate escapes, unknown fields, case-insensitive duplicate object keys at every nesting level, trailing data, null documents, and configured-limit violations. The uniqueness rule applies package-wide, not only to Go structs.

Strict describes rejection and resource rules, not an injective or canonical byte representation. Leading and trailing whitespace and equivalent JSON string escapes may decode to the same typed value. A protocol that signs or hashes wire bytes must authenticate the original bytes before decoding; a protocol that signs typed values must define its own canonical projection. Every failure returns the zero value of T.

func DecodeStrictJSONStructure added in v2026.0.3 

func DecodeStrictJSONStructure[T any](
	data []byte,
	limits StrictJSONLimits,
) (T, error)

DecodeStrictJSONStructure applies the complete strict JSON grammar and configured bounds without invoking T.Validate. It exists for typed boundary projection: a caller decodes into a private temporary, adds non-wire request state, validates the completed owning value, and only then permits it to escape. Callers that do not need that exact sequence use DecodeStrictJSON.

func EncodeValidatedJSON 

func EncodeValidatedJSON[T ValidatedJSONMarshaler](value T, limits StrictJSONLimits) ([]byte, error)

EncodeValidatedJSON validates limits and value, then emits one strict JSON document. A bidirectional value must decode into T, including through methods on *T, pass T.Validate, and re-encode to the same bytes; the generic constraint cannot express that value/pointer symmetry, so this function enforces it. An issue-only ValidatedJSONProjection instead proves its exact emitted bytes through its distinct compiler-owned projection validator. The package-wide case-insensitive object-key uniqueness rule applies to encoded output at every nesting level. Invalid UTF-8, unpaired JSON surrogate escapes, and any explicit null representation are rejected.

func MarshalCanonicalJSONDocument added in v2026.0.3 

func MarshalCanonicalJSONDocument[Document any](document Document) ([]byte, error)

MarshalCanonicalJSONDocument encodes one Go value as the repository's single canonical JSON document. It uses encoding/json/v2's compact strict projection, so invalid UTF-8 is rejected and direct and embedded values have one spelling and one byte extent.

The caller owns the document invariant. This helper owns only the shared encoder configuration; typed protocol values still validate before calling it, and raw strings use MarshalCanonicalJSONString for the UTF-8 gate.

This is the one owner of that mechanic. A second copy anywhere in the repository would let two owners disagree about the bytes a protocol carries, which is why MarshalCanonicalJSONString projects from it instead of repeating it.

func MarshalCanonicalJSONString added in v2026.0.3 

func MarshalCanonicalJSONString(value string) ([]byte, error)

MarshalCanonicalJSONString encodes one Go string as the repository's single canonical JSON string token. It is the encoding counterpart of DecodeJSONStringToken: it adds the string-specific gate, refusing invalid UTF-8 before any protocol sees it, and takes the canonical encoding itself from MarshalCanonicalJSONDocument.

A second string-escaping grammar anywhere in the repository would let two owners disagree about the bytes a signature covers, which is why this rule has one home instead of one copy per package.

func ReaderIsNil added in v2026.0.143 

func ReaderIsNil(reader io.Reader) bool

ReaderIsNil reports whether reader is a nil interface or contains a typed nil value. It closes the shared io.Reader ingress rule before a package calls a method on an externally supplied implementation.

func SHA256BytesOf added in v2026.0.39 

func SHA256BytesOf(data []byte) [sha256.Size]byte

SHA256BytesOf returns the raw thirty two byte SHA-256 of one complete in-memory buffer.

It is the fixed-array companion to SHA256Of, for the callers that key or fingerprint on the raw bytes rather than keep a typed digest. Like SHA256Of it cannot fail, so it returns the array directly; a caller is spared an unreachable error check that would otherwise tempt a zero fingerprint on a branch that never runs, aliasing distinct inputs to the same key.

func ValidateHTTPFieldValue added in v2026.0.3 

func ValidateHTTPFieldValue(value string) error

ValidateHTTPFieldValue rejects field content that no HTTP message can carry. The admitted grammar is RFC 9110 field-value: visible ASCII, space, horizontal tab, and obs-text. Control bytes and DEL are refused because net/http refuses to transmit them, so accepting one here would defer a permanent contract violation into an opaque transport failure.

func ValidateReceiveOnlyJSONProjection added in v2026.0.96 

func ValidateReceiveOnlyJSONProjection[
	Projection ValidatedJSONMarshaler,
	Document any,
	DocumentPtr interface {
		*Document
		Validatable
		json.Unmarshaler
	},
](projection Projection, encoded []byte, limits StrictJSONLimits) error

ValidateReceiveOnlyJSONProjection proves that exact issue-only bytes decode through their distinct receive-only owner and preserve the producer's canonical projection. Projection and document stay separate compiler-owned directions; neither needs a compatibility decoder or encoder.

Types

type AbsolutePath 

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

AbsolutePath is one lexically clean native absolute path. It makes no false claim about whether the path names a file, directory, or existing entry.

func ParseAbsolutePath 

func ParseAbsolutePath(value string) (AbsolutePath, error)

ParseAbsolutePath validates lexical absolute-path form without filesystem I/O.

func (AbsolutePath) Base 

func (p AbsolutePath) Base() (PathComponent, error)

Base returns the final component and rejects the componentless root.

func (AbsolutePath) Join 

func (p AbsolutePath) Join(component PathComponent) (AbsolutePath, error)

Join appends one validated component without introducing path-kind claims.

func (AbsolutePath) JoinRelative added in v2026.0.21 

func (p AbsolutePath) JoinRelative(relative RelativePath) (AbsolutePath, error)

JoinRelative resolves a relative path against an absolute one.

An absolute root plus a nested relative path is how every rooted filesystem request is expressed, so products otherwise reach for filepath.Join on two strings and re-parse. Both sides are already validated by their own types, and the result is validated again as an absolute path, so no unchecked text exists at any point.

func (AbsolutePath) MarshalJSON 

func (p AbsolutePath) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical native absolute path as a JSON string.

func (AbsolutePath) Parent 

func (p AbsolutePath) Parent() (AbsolutePath, error)

Parent returns the lexical parent; the filesystem root is its own parent.

func (AbsolutePath) RelativeTo added in v2026.0.23 

func (p AbsolutePath) RelativeTo(base AbsolutePath) (RelativePath, error)

RelativeTo expresses p as a path relative to base.

It is the inverse of JoinRelative and exists for the same reason: products hold a rooted capability plus an absolute path and need the relative path between them, which they otherwise compute with filepath.Rel on two strings and re-parse.

A result that climbs out of base is refused, and refused by RelativePath's own admission rule rather than by a second check here. That keeps one place deciding what a relative path may be; a local guard would be a branch no test could ever fail, since nothing that escapes can be parsed at all.

func (AbsolutePath) Resolve added in v2026.0.22 

func (p AbsolutePath) Resolve(names ...string) (AbsolutePath, error)

Resolve joins names below an absolute path, admitting each as its own component.

This is the shape every product actually needs: a root plus a handful of compiler-owned name constants. Written with filepath.Join it produces one string that is validated only at the end, so a name that was never a legal component can still yield a legal-looking path. Here each name is refused where it is introduced, and the caller gets one error instead of one per segment.

func (AbsolutePath) ResolveText added in v2026.0.38 

func (p AbsolutePath) ResolveText(value string) (AbsolutePath, error)

ResolveText resolves operator-supplied path text against this base.

Command lines and environment variables hand a product text that may be absolute, relative, dotted, or climbing, and the product needs the one absolute path that text names. Written directly that is filepath.Abs and a re-parse, and filepath.Abs asks the kernel for a working directory, so an ingress that should be pure text arithmetic becomes a hidden real-world touch. Here the caller supplies the base, usually process.WorkingDirectory, and resolution is exactly lexical: absolute text is cleaned and admitted as itself, everything else is cleaned and admitted against the base, with climbs clamped at the filesystem root by the same rule the kernel uses. Empty text is refused rather than silently meaning the base itself.

func (AbsolutePath) String 

func (p AbsolutePath) String() string

String returns the validated native path.

func (*AbsolutePath) UnmarshalJSON 

func (p *AbsolutePath) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts one canonical native absolute path.

func (AbsolutePath) Validate 

func (p AbsolutePath) Validate() error

Validate rejects the unset zero value.

func (AbsolutePath) WithSuffix added in v2026.0.25 

func (p AbsolutePath) WithSuffix(suffix string) (AbsolutePath, error)

WithSuffix names the sibling whose final component carries suffix.

Products mark related state beside a directory: a lease marker, a custody sidecar, a quarantined generation. Written as string concatenation the result is never revalidated, so a suffix carrying a separator silently produces a path in another directory. Here the joined name is admitted as a component before it becomes a path, so it can only ever name a sibling.

type ArchitectureCatalog 

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

ArchitectureCatalog is the complete, validated Primitive package graph.

func PrimitiveArchitecture 

func PrimitiveArchitecture() ArchitectureCatalog

PrimitiveArchitecture returns the complete compiler-owned package catalog.

func (ArchitectureCatalog) ContainsDirectImport added in v2026.0.3 

func (c ArchitectureCatalog) ContainsDirectImport(target DirectImportContract) bool

ContainsDirectImport reports membership in the admitted production graph.

func (ArchitectureCatalog) ContainsDirectTestImport added in v2026.0.3 

func (c ArchitectureCatalog) ContainsDirectTestImport(target DirectTestImportContract) bool

ContainsDirectTestImport reports membership in the admitted test-only graph.

func (ArchitectureCatalog) DirectImports 

func (c ArchitectureCatalog) DirectImports() iter.Seq[DirectImportContract]

DirectImports yields every admitted direct import edge in catalog order.

func (ArchitectureCatalog) DirectTestImports added in v2026.0.3 

func (c ArchitectureCatalog) DirectTestImports() iter.Seq[DirectTestImportContract]

DirectTestImports yields every admitted test-only edge in catalog order.

func (ArchitectureCatalog) Lookup 

func (c ArchitectureCatalog) Lookup(identity PackageIdentity) (PackageContract, bool)

Lookup returns the contract for identity.

func (ArchitectureCatalog) Packages 

func (c ArchitectureCatalog) Packages() iter.Seq[PackageContract]

Packages yields every package contract in catalog order.

func (ArchitectureCatalog) Validate 

func (c ArchitectureCatalog) Validate() error

Validate rejects incomplete, duplicate, cyclic, or over-coupled catalogs.

type BuildCommit added in v2026.0.3 

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

BuildCommit is a canonical SHA-1 or SHA-256 Git object name.

func ParseBuildCommit added in v2026.0.3 

func ParseBuildCommit(value string) (BuildCommit, error)

ParseBuildCommit accepts canonical lower hexadecimal at a supported Git object-name width.

func (BuildCommit) MarshalJSON added in v2026.0.3 

func (c BuildCommit) MarshalJSON() ([]byte, error)

MarshalJSON emits canonical lower hexadecimal.

func (BuildCommit) String added in v2026.0.3 

func (c BuildCommit) String() string

String returns canonical lower hexadecimal, or empty text when invalid.

func (*BuildCommit) UnmarshalJSON added in v2026.0.3 

func (c *BuildCommit) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts a canonical supported Git object name.

func (BuildCommit) Validate added in v2026.0.3 

func (c BuildCommit) Validate() error

Validate proves supported width and zero padding.

type BuildIdentity added in v2026.0.3 

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

BuildIdentity identifies immutable release bytes without claiming that the current process embeds those facts.

func NewBuildIdentity added in v2026.0.3 

func NewBuildIdentity(request BuildIdentityRequest) (BuildIdentity, error)

NewBuildIdentity validates and constructs immutable build facts.

func (BuildIdentity) Commit added in v2026.0.3 

func (i BuildIdentity) Commit() BuildCommit

Commit returns the source commit.

func (BuildIdentity) MarshalJSON added in v2026.0.3 

func (i BuildIdentity) MarshalJSON() ([]byte, error)

MarshalJSON emits the exact typed build-identity projection.

func (BuildIdentity) Offering added in v2026.0.3 

func (i BuildIdentity) Offering() Offering

Offering returns the product identity.

func (BuildIdentity) Platform added in v2026.0.3 

func (i BuildIdentity) Platform() Platform

Platform returns the compiled target.

func (*BuildIdentity) UnmarshalJSON added in v2026.0.3 

func (i *BuildIdentity) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts one bounded strict build-identity projection.

func (BuildIdentity) Validate added in v2026.0.3 

func (i BuildIdentity) Validate() error

Validate proves every owned build-identity field.

func (BuildIdentity) Version added in v2026.0.3 

func (i BuildIdentity) Version() ReleaseVersion

Version returns the release version.

type BuildIdentityRequest added in v2026.0.3 

type BuildIdentityRequest struct {
	// Offering identifies the released product without Primitive interpreting it.
	Offering Offering
	// Version identifies the ordered product release.
	Version ReleaseVersion
	// Commit identifies the exact source commit.
	Commit BuildCommit
	// Platform identifies the compiled target.
	Platform Platform
}

BuildIdentityRequest carries the immutable facts shared by Release and Upgrade.

type ByteCount 

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

ByteCount is a strictly positive byte quantity. Its zero value is invalid.

func NewByteCount 

func NewByteCount(value uint64) (ByteCount, error)

NewByteCount constructs a positive byte count.

func (ByteCount) Int64 

func (c ByteCount) Int64() (int64, error)

Int64 returns the validated count when it fits in int64.

func (ByteCount) MarshalJSON 

func (c ByteCount) MarshalJSON() ([]byte, error)

MarshalJSON emits the positive count as a canonical JSON integer.

func (ByteCount) Uint64 

func (c ByteCount) Uint64() (uint64, error)

Uint64 returns the validated count.

func (*ByteCount) UnmarshalJSON 

func (c *ByteCount) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts a canonical positive unsigned JSON integer.

func (ByteCount) Validate 

func (c ByteCount) Validate() error

Validate rejects a zero byte count.

type ByteLength 

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

ByteLength is a non-negative byte length in Go's signed size domain; unlike ByteCount, zero is meaningful. The upper bound matches the int64 quantities exposed by the standard library for file, stream, and HTTP body sizes.

func NewByteLength 

func NewByteLength(value uint64) (ByteLength, error)

NewByteLength constructs a non-negative byte length.

func (ByteLength) Int64 

func (l ByteLength) Int64() (int64, error)

Int64 returns the length when it fits in int64.

func (ByteLength) MarshalJSON 

func (l ByteLength) MarshalJSON() ([]byte, error)

MarshalJSON emits the length as a canonical JSON integer.

func (ByteLength) Uint64 

func (l ByteLength) Uint64() uint64

Uint64 returns the length.

func (*ByteLength) UnmarshalJSON 

func (l *ByteLength) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts a canonical non-negative unsigned JSON integer.

func (ByteLength) Validate added in v2026.0.3 

func (l ByteLength) Validate() error

Validate rejects lengths outside Go's signed size domain.

type CPUArchitecture 

type CPUArchitecture uint8

CPUArchitecture is a closed set of CPU architectures supported by Primitive. 

const (

	// CPUArchitectureAMD64 identifies amd64.
	CPUArchitectureAMD64 CPUArchitecture
	// CPUArchitectureARM64 identifies arm64.
	CPUArchitectureARM64
)

func (CPUArchitecture) IsValid 

func (a CPUArchitecture) IsValid() bool

IsValid reports whether a belongs to the closed architecture domain.

func (CPUArchitecture) MarshalJSON 

func (a CPUArchitecture) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical architecture token.

func (CPUArchitecture) String 

func (a CPUArchitecture) String() string

String returns the canonical lowercase architecture token.

func (*CPUArchitecture) UnmarshalJSON 

func (a *CPUArchitecture) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only a canonical admitted architecture token.

func (CPUArchitecture) Validate 

func (a CPUArchitecture) Validate() error

Validate rejects architectures outside the closed domain.

type CRC32C 

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

CRC32C is a set CRC32C checksum. Its zero value is invalid.

func NewCRC32C 

func NewCRC32C(value uint32) CRC32C

NewCRC32C constructs a set checksum, including the numeric value zero.

func (CRC32C) Base64 

func (c CRC32C) Base64() (string, error)

Base64 returns canonical padded standard Base64 in big-endian byte order.

func (CRC32C) MarshalJSON 

func (c CRC32C) MarshalJSON() ([]byte, error)

MarshalJSON emits canonical padded Base64 as a JSON string.

func (CRC32C) Uint32 

func (c CRC32C) Uint32() (uint32, error)

Uint32 returns the checksum after validating that it is set.

func (*CRC32C) UnmarshalJSON 

func (c *CRC32C) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only canonical padded standard Base64.

func (*CRC32C) UnmarshalText added in v2026.0.3 

func (c *CRC32C) UnmarshalText(data []byte) error

UnmarshalText accepts canonical padded standard Base64 without mutating the receiver on failure.

func (CRC32C) Validate 

func (c CRC32C) Validate() error

Validate rejects an unset checksum.

type CatalogContinuationState added in v2026.0.55 

type CatalogContinuationState uint8

CatalogContinuationState closes the shared end-or-more response domain. 

const (
	// CatalogContinuationUnknown is the invalid zero continuation state.
	CatalogContinuationUnknown CatalogContinuationState = iota
	// CatalogContinuationEnd states that no later page exists.
	CatalogContinuationEnd
	// CatalogContinuationMore states that another page exists.
	CatalogContinuationMore
)

func (CatalogContinuationState) IsValid added in v2026.0.55 

func (s CatalogContinuationState) IsValid() bool

IsValid reports whether s is one published continuation state.

func (CatalogContinuationState) MarshalJSON added in v2026.0.55 

func (s CatalogContinuationState) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical continuation token.

func (CatalogContinuationState) String added in v2026.0.55 

func (s CatalogContinuationState) String() string

String returns the canonical token or empty text for an invalid state.

func (*CatalogContinuationState) UnmarshalJSON added in v2026.0.55 

func (s *CatalogContinuationState) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only an admitted continuation token.

func (CatalogContinuationState) Validate added in v2026.0.55 

func (s CatalogContinuationState) Validate() error

Validate rejects continuation states outside the closed domain.

type CatalogPageLimit added in v2026.0.55 

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

CatalogPageLimit is a positive caller-selected page bound shared by every Primitive catalog protocol.

func NewCatalogPageLimit added in v2026.0.55 

func NewCatalogPageLimit(value uint16) (CatalogPageLimit, error)

NewCatalogPageLimit closes a caller-selected page bound.

func (CatalogPageLimit) MarshalJSON added in v2026.0.55 

func (l CatalogPageLimit) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical unsigned decimal page bound.

func (CatalogPageLimit) Uint16 added in v2026.0.55 

func (l CatalogPageLimit) Uint16() uint16

Uint16 returns the validated page bound.

func (*CatalogPageLimit) UnmarshalJSON added in v2026.0.55 

func (l *CatalogPageLimit) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only the canonical unsigned decimal page bound.

func (CatalogPageLimit) Validate added in v2026.0.55 

func (l CatalogPageLimit) Validate() error

Validate refuses zero and values wider than one bounded page.

type CatalogPositionKind added in v2026.0.55 

type CatalogPositionKind uint8

CatalogPositionKind closes the shared first-page-or-after-cursor domain. 

const (
	// CatalogPositionUnknown is the invalid zero position.
	CatalogPositionUnknown CatalogPositionKind = iota
	// CatalogPositionStart requests the first page.
	CatalogPositionStart
	// CatalogPositionAfter requests the page after a cursor.
	CatalogPositionAfter
)

func (CatalogPositionKind) IsValid added in v2026.0.55 

func (k CatalogPositionKind) IsValid() bool

IsValid reports whether k is one published catalog position kind.

func (CatalogPositionKind) MarshalJSON added in v2026.0.55 

func (k CatalogPositionKind) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical position token.

func (CatalogPositionKind) String added in v2026.0.55 

func (k CatalogPositionKind) String() string

String returns the canonical token or empty text for an invalid kind.

func (*CatalogPositionKind) UnmarshalJSON added in v2026.0.55 

func (k *CatalogPositionKind) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only an admitted position token.

func (CatalogPositionKind) Validate added in v2026.0.55 

func (k CatalogPositionKind) Validate() error

Validate rejects positions outside the closed domain.

type CatalogSelectionKind added in v2026.0.55 

type CatalogSelectionKind uint8

CatalogSelectionKind closes the shared all-or-specific query domain. 

const (
	// CatalogSelectionUnknown is the invalid zero selection.
	CatalogSelectionUnknown CatalogSelectionKind = iota
	// CatalogSelectionAll selects every item in one scope.
	CatalogSelectionAll
	// CatalogSelectionSpecific selects one exact item.
	CatalogSelectionSpecific
)

func (CatalogSelectionKind) IsValid added in v2026.0.55 

func (k CatalogSelectionKind) IsValid() bool

IsValid reports whether k is one published catalog selection kind.

func (CatalogSelectionKind) MarshalJSON added in v2026.0.55 

func (k CatalogSelectionKind) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical selection token.

func (CatalogSelectionKind) String added in v2026.0.55 

func (k CatalogSelectionKind) String() string

String returns the canonical token or empty text for an invalid kind.

func (*CatalogSelectionKind) UnmarshalJSON added in v2026.0.55 

func (k *CatalogSelectionKind) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only an admitted selection token.

func (CatalogSelectionKind) Validate added in v2026.0.55 

func (k CatalogSelectionKind) Validate() error

Validate rejects selection kinds outside the closed domain.

type Comparison added in v2026.0.3 

type Comparison uint8

Comparison is the shared closed result of ordering two values. 

const (
	// ComparisonUnknown is the invalid zero comparison.
	ComparisonUnknown Comparison = iota
	// ComparisonLess reports that the left value is less than the right.
	ComparisonLess
	// ComparisonEqual reports that both values are equal.
	ComparisonEqual
	// ComparisonGreater reports that the left value is greater than the right.
	ComparisonGreater
)

func (Comparison) IsValid added in v2026.0.3 

func (c Comparison) IsValid() bool

IsValid reports whether c belongs to the closed comparison domain.

func (Comparison) OffWireEnum added in v2026.0.3 

func (Comparison) OffWireEnum()

OffWireEnum declares Comparison as an off-wire enum. The declaration binds Comparison to OffWireEnum in validation_witnesses, so the marker is compiler-checked rather than a bare method name matched by convention.

func (Comparison) String added in v2026.0.3 

func (c Comparison) String() string

String returns a diagnostic projection of c.

func (Comparison) Validate added in v2026.0.3 

func (c Comparison) Validate() error

Validate rejects values outside the closed comparison domain. It refuses a zero row too, so a member that is added to the table with no diagnostic can never be admitted by the range check alone.

type DigestWriter added in v2026.0.20 

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

DigestWriter accumulates streamed bytes into one SHA-256 digest and the exact count of the bytes that produced it.

Hashing a stream is not a product decision, and everything that moves bytes has to do it: to content-address an object, to bind an artifact to its manifest, to seal a canonical body. Written separately each time it arrives as a private struct around crypto/sha256, each with its own count type and its own idea of when the digest becomes final. Core owns the mechanic so the digest and the count are always two facts about exactly the same bytes.

Bounds are deliberately absent. A maximum belongs to whoever knows what is being hashed; one baked in here would be wrong for one caller and silently generous for another. A caller that needs a ceiling enforces it above and keeps the reason with it. A caller that needs the same stream elsewhere composes io.MultiWriter, which is why this is an ordinary io.Writer and not a private accumulator with a bespoke feed method.

func NewDigestWriter added in v2026.0.20 

func NewDigestWriter() *DigestWriter

NewDigestWriter returns a writer positioned over an empty stream. The digest of no bytes is a real answer, so an empty stream seals rather than failing; whether emptiness is acceptable is the caller's rule, not this one's.

It is the one constructor. A zero DigestWriter holds no sha256 state, so every method refuses it the same way it refuses a nil receiver, rather than dereferencing the missing hash and taking the process down for a caller defect the writer can report.

func (*DigestWriter) Digest added in v2026.0.36 

func (w *DigestWriter) Digest() (SHA256Digest, ByteLength, error)

Digest reports the digest and byte count of the bytes written so far without ending the stream.

It is the running-total companion to Seal, the way hash.Hash.Sum reads the current digest without closing the hash. A writer that must expose its content hash while still open, such as a file whose SHA-256 is read before it is closed, peeks with Digest and keeps writing; the answer moves as more bytes arrive. Reading is not a mutation, so a peek never latches, and a peek after Seal returns the same sealed answer.

func (*DigestWriter) Reset added in v2026.0.36 

func (w *DigestWriter) Reset() error

Reset returns the writer to the empty-stream state so one writer can hash a succession of independent streams instead of allocating a fresh sha256 state for each. It discards the bytes written, clears the seal, and clears a latched refusal, so the next stream starts from the digest of no bytes and is unrelated to the last. This is the reuse hash.Hash.Reset exists for; it is not a way to resume a sealed stream, because the discarded bytes are gone.

func (*DigestWriter) Seal added in v2026.0.20 

func (w *DigestWriter) Seal() (SHA256Digest, ByteLength, error)

Seal ends the stream and returns the digest and byte count of exactly the bytes written.

Sealing is one-way. A later write is refused rather than producing a second digest that disagrees with the first about the same writer, so a caller holding the pair can be certain no byte arrived after the answer was taken. Sealing twice returns the same answer, because asking again is not a mutation. The digest is exactly what Digest would report at this instant; Seal only adds the latch that no further byte may change it.

func (*DigestWriter) Write added in v2026.0.20 

func (w *DigestWriter) Write(data []byte) (int, error)

Write accumulates data into the running digest.

The hash is not asked whether it succeeded, because hash.Hash documents that Write never returns an error and always consumes every byte, and this writer always holds the sha256 implementation it constructed. Checking anyway would add a branch no test could ever fail, and an unfailable branch is a claim nobody is keeping. The one refusal that is real — writing to a sealed writer — is latched, so a caller cannot resume a stream whose answer was taken.

type DirectImportContract 

type DirectImportContract struct {
	// Importer is the package that owns the import declaration.
	Importer PackageIdentity
	// Imported is the directly imported Primitive package.
	Imported PackageIdentity
}

DirectImportContract admits one direct importer-to-imported package edge.

func (DirectImportContract) Validate 

func (c DirectImportContract) Validate() error

Validate enforces a legal direct package relationship.

type DirectTestImportContract added in v2026.0.3 

type DirectTestImportContract struct {
	// Importer is the package whose test sources own the import declaration.
	Importer PackageIdentity
	// Imported is the directly imported Primitive package.
	Imported PackageIdentity
}

DirectTestImportContract admits one test-only importer-to-imported edge.

A test-only edge exists when a package's tests require either the real substrate that produces an ingress value or the typed Testserial declaration for a process-wide isolation fact. It grants no production dependency: production sources that import the edge remain an undeclared production edge, and a declared test edge that no test file uses is a ceremonial import and equally rejected.

func (DirectTestImportContract) Validate added in v2026.0.3 

func (c DirectTestImportContract) Validate() error

Validate enforces a legal test-only package relationship.

A test edge obeys the identical relationship legality as a production edge: both endpoints are admitted packages and a package never imports itself or is imported by Core. Unlike a production edge, a test edge may target the test-support package, because declaring test isolation is exactly what test sources do.

type Ed25519PublicKey 

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

Ed25519PublicKey is an owned, set Ed25519 public key.

func NewEd25519PublicKey 

func NewEd25519PublicKey(value ed25519.PublicKey) (Ed25519PublicKey, error)

NewEd25519PublicKey copies a standard-library key of the exact required size.

func (Ed25519PublicKey) Bytes 

func (k Ed25519PublicKey) Bytes() (ed25519.PublicKey, error)

Bytes returns an independent standard-library public-key copy.

func (Ed25519PublicKey) Hex 

func (k Ed25519PublicKey) Hex() (string, error)

Hex returns canonical lowercase hexadecimal.

func (Ed25519PublicKey) MarshalJSON 

func (k Ed25519PublicKey) MarshalJSON() ([]byte, error)

MarshalJSON emits canonical lowercase hexadecimal as a JSON string.

func (*Ed25519PublicKey) UnmarshalJSON 

func (k *Ed25519PublicKey) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only canonical lowercase hexadecimal.

func (*Ed25519PublicKey) UnmarshalText added in v2026.0.5 

func (k *Ed25519PublicKey) UnmarshalText(text []byte) error

UnmarshalText accepts exactly one canonical lowercase hexadecimal public key through encoding.TextUnmarshaler. The receiver is unchanged on rejection.

func (Ed25519PublicKey) Validate 

func (k Ed25519PublicKey) Validate() error

Validate rejects an unset public key.

The all-zero key is deliberately admitted here. This type is a container for thirty-two bytes and a derivation over it is total, so refusing the value would break identity derivations that legitimately span every byte string. Whether a key may be *trusted* is a different question with a different owner: Attest refuses the all-zero small-order point at the trust boundary.

type ErrorIdentity 

type ErrorIdentity uint16

ErrorIdentity is a stable, closed error identity usable with errors.Is. 

const (
	// ErrUnknown is the invalid zero identity.
	ErrUnknown ErrorIdentity = iota
	// ErrPrimitiveContract identifies a shared Primitive contract violation.
	ErrPrimitiveContract
	// ErrJSONContract identifies strict JSON boundary failure.
	ErrJSONContract
	// ErrNumericOverflow identifies a checked numeric overflow.
	ErrNumericOverflow
	// ErrSecretMaterialAllZero identifies secret material whose bytes are all
	// zero. Core owns this rejection, so a caller that must distinguish a failed
	// entropy source from a structural violation asks Core through errors.Is
	// instead of re-deriving the rule over the same buffer.
	ErrSecretMaterialAllZero

	// ErrAttestContract identifies an attest input or state violation.
	ErrAttestContract
	// ErrAttestVerification identifies failed attestation verification.
	ErrAttestVerification

	// ErrContextStateContract identifies a context-state contract violation.
	ErrContextStateContract
	// ErrNilContext identifies a required context that is nil.
	ErrNilContext
	// ErrContextObservation identifies failed context observation.
	ErrContextObservation

	// ErrLineIOContract identifies a bounded line-scanner contract violation.
	ErrLineIOContract
	// ErrLineIOScan identifies failure while advancing a bounded line stream.
	ErrLineIOScan
	// ErrManualContract identifies invalid shared manual facts or requests.
	ErrManualContract
	// ErrManualWrite identifies failed human or machine manual output.
	ErrManualWrite

	// ErrCurrencyContract identifies a currency contract violation.
	ErrCurrencyContract
	// ErrCurrencyMismatch identifies incompatible currencies.
	ErrCurrencyMismatch
	// ErrCurrencyOverflow identifies currency arithmetic overflow.
	ErrCurrencyOverflow
	// ErrCurrencyDecimal identifies rejected decimal currency input.
	ErrCurrencyDecimal

	// ErrKeygenContract identifies a key-generation contract violation.
	ErrKeygenContract
	// ErrKeygenEntropy identifies failed key-generation entropy acquisition.
	ErrKeygenEntropy

	// ErrTestIsolationContract identifies a test-isolation violation.
	ErrTestIsolationContract

	// ErrFilestoreContract identifies a file-store contract violation.
	ErrFilestoreContract
	// ErrFilestoreSize identifies a rejected file-store size.
	ErrFilestoreSize
	// ErrFilestoreSource identifies a file-store source failure.
	ErrFilestoreSource
	// ErrFilestoreDestination identifies a file-store destination failure.
	ErrFilestoreDestination
	// ErrFilestoreConflict identifies a file-store namespace conflict.
	ErrFilestoreConflict
	// ErrFilestoreActivation identifies failed file-store activation.
	ErrFilestoreActivation
	// ErrFilestoreActivationIndeterminate identifies uncertain activation state.
	ErrFilestoreActivationIndeterminate
	// ErrFilestoreCleanup identifies failed file-store cleanup.
	ErrFilestoreCleanup

	// ErrHostFacts identifies the neutral host-facts error family.
	ErrHostFacts
	// ErrHostFactsContract identifies a host-facts contract violation.
	ErrHostFactsContract
	// ErrHostFactsObservation identifies a failed host observation.
	ErrHostFactsObservation
	// ErrHostFactsUnsupported identifies an unsupported host observation.
	ErrHostFactsUnsupported
	// ErrHostFactsPressure identifies a reached caller-supplied pressure policy.
	ErrHostFactsPressure
	// ErrHostFactsEvidence identifies invalid persisted host evidence.
	ErrHostFactsEvidence
	// ErrDiskCapacityUnsupported identifies unsupported disk-capacity observation.
	ErrDiskCapacityUnsupported
	// ErrTreeMeasurementUnsupported identifies unsupported tree measurement.
	ErrTreeMeasurementUnsupported
	// ErrDiskFloorReached identifies insufficient available disk capacity.
	ErrDiskFloorReached
	// ErrMemoryLimitReached identifies reached Go-managed-memory pressure.
	ErrMemoryLimitReached

	// ErrTemporalContract identifies a temporal contract violation.
	ErrTemporalContract
	// ErrTemporalOverflow identifies temporal arithmetic outside its exact
	// representable domain.
	ErrTemporalOverflow

	// ErrExchangeContract identifies an exchange contract violation.
	ErrExchangeContract
	// ErrExchangeRequest identifies a rejected exchange request.
	ErrExchangeRequest
	// ErrExchangeResponse identifies a rejected exchange response.
	ErrExchangeResponse
	// ErrExchangeBodyLimit identifies an exceeded exchange body limit.
	ErrExchangeBodyLimit
	// ErrExchangeContentType identifies a rejected exchange content type.
	ErrExchangeContentType
	// ErrExchangeCancelled identifies exchange cancellation.
	ErrExchangeCancelled
	// ErrExchangeRedirect identifies a rejected redirect.
	ErrExchangeRedirect
	// ErrExchangeTransport identifies a transport failure.
	ErrExchangeTransport
	// ErrExchangeRetryExhausted identifies exhausted retry policy.
	ErrExchangeRetryExhausted
	// ErrExchangeWrite identifies an exchange write failure.
	ErrExchangeWrite

	// ErrFuzzFinderContract identifies a fuzz-finder contract violation.
	ErrFuzzFinderContract
	// ErrFuzzFinderFormat identifies an unsupported Go fuzz-artifact format.
	ErrFuzzFinderFormat
	// ErrFuzzFinderObservation identifies failed fuzz-artifact observation.
	ErrFuzzFinderObservation

	// ErrLeaseContract identifies a lease contract violation.
	ErrLeaseContract
	// ErrLeaseVerification identifies failed lease verification.
	ErrLeaseVerification
	// ErrLeaseRollback identifies rejected lease rollback.
	ErrLeaseRollback
	// ErrLeaseConflict identifies a lease identity conflict.
	ErrLeaseConflict
	// ErrLeaseScope identifies a verified lease for a different subject.
	ErrLeaseScope
	// ErrLeaseClock identifies a local clock contradiction.
	ErrLeaseClock

	// ErrGateContract identifies a new-work Gate contract violation.
	ErrGateContract
	// ErrGateDenied identifies an authentic Lease state that denies new work.
	ErrGateDenied

	// ErrProcessContract identifies a process contract violation.
	ErrProcessContract
	// ErrProcessStart identifies failure to start a process.
	ErrProcessStart
	// ErrProcessStream identifies a process stream failure.
	ErrProcessStream
	// ErrProcessOutputLimit identifies a reached process output bound.
	ErrProcessOutputLimit
	// ErrProcessWait identifies failure while waiting for a process.
	ErrProcessWait
	// ErrProcessObservation identifies a failed process observation.
	ErrProcessObservation
	// ErrProcessUnsupported identifies an unsupported process operation.
	ErrProcessUnsupported

	// ErrReleaseContract identifies a release contract violation.
	ErrReleaseContract
	// ErrReleaseManifest identifies a rejected release manifest.
	ErrReleaseManifest
	// ErrReleaseVerification identifies failed release verification.
	ErrReleaseVerification
	// ErrReleaseLatest identifies a rejected latest-release decision.
	ErrReleaseLatest
	// ErrReleaseRollback identifies rejected release rollback.
	ErrReleaseRollback
	// ErrReleaseConflict identifies a release identity conflict.
	ErrReleaseConflict
	// ErrDeployContract identifies a release-deployment contract violation.
	ErrDeployContract
	// ErrDistributionContract identifies an authenticated software-distribution
	// agreement violation.
	ErrDistributionContract
	// ErrDistributionVerification identifies a distribution document or nested
	// release authority that failed authentication.
	ErrDistributionVerification
	// ErrDistributionBinding identifies a valid distribution fact attached to
	// the wrong request, capability, release, or lifetime.
	ErrDistributionBinding

	// ErrShutdownContract identifies a shutdown contract violation.
	ErrShutdownContract
	// ErrShutdownStepFailure identifies a cleanup step that returned failure.
	ErrShutdownStepFailure
	// ErrShutdownStepTimeout identifies a cleanup step whose budget expired.
	ErrShutdownStepTimeout
	// ErrShutdownStepPanic identifies a cleanup step whose panic was contained.
	ErrShutdownStepPanic
	// ErrShutdownTotalTimeout identifies cleanup work stopped or skipped by
	// total budget expiry.
	ErrShutdownTotalTimeout
	// ErrShutdownSignalSource identifies failed signal observation.
	ErrShutdownSignalSource
	// ErrShutdownSignalReceived identifies authentic observed shutdown signal.
	ErrShutdownSignalReceived

	// ErrObjectStoreContract identifies an object-store contract violation.
	ErrObjectStoreContract
	// ErrObjectStoreExpired identifies an expired object-store target.
	ErrObjectStoreExpired
	// ErrObjectStoreIntegrity identifies failed object integrity.
	ErrObjectStoreIntegrity
	// ErrObjectStoreSource identifies an object-store source failure.
	ErrObjectStoreSource
	// ErrObjectStoreDestination identifies an object-store destination failure.
	ErrObjectStoreDestination
	// ErrObjectStoreConflict identifies an object-store write conflict.
	ErrObjectStoreConflict
	// ErrObjectStoreSize identifies a rejected object size.
	ErrObjectStoreSize
	// ErrObjectStoreAbsent identifies an absent object.
	ErrObjectStoreAbsent

	// ErrTimeProofContract identifies a time-proof contract violation.
	ErrTimeProofContract
	// ErrTimeProofRefused identifies a valid authority refusal.
	ErrTimeProofRefused
	// ErrTimeProofInvalid identifies evidence that failed verification.
	ErrTimeProofInvalid
	// ErrCloudIdentityContract identifies a cloud-identity violation.
	ErrCloudIdentityContract
	// ErrUpgradeContract identifies an upgrade contract violation.
	ErrUpgradeContract
	// ErrUpgradeDownload identifies a candidate download failure.
	ErrUpgradeDownload
	// ErrUpgradeCapacity identifies insufficient admitted candidate capacity.
	ErrUpgradeCapacity
	// ErrUpgradeVerification identifies candidate or primary bytes that do not
	// match their authenticated Release artifact.
	ErrUpgradeVerification
	// ErrUpgradeTrial identifies a candidate rejected by its product-owned
	// trial.
	ErrUpgradeTrial
	// ErrUpgradePromotion identifies a rejected primary-selection change.
	ErrUpgradePromotion
	// ErrUpgradePersistence identifies unreadable or uncommitted upgrade
	// metadata.
	ErrUpgradePersistence
	// ErrUpgradeCleanup identifies an obsolete slot that could not be removed.
	ErrUpgradeCleanup
	// ErrUpgradeConflict identifies concurrent or stale upgrade authority.
	ErrUpgradeConflict

	// ErrLifecycleIdentityContract identifies an invalid lifecycle identity.
	ErrLifecycleIdentityContract
	// ErrReceiptContract identifies a Receipt contract violation.
	ErrReceiptContract
	// ErrReceiptVerification identifies evidence that failed authentication.
	ErrReceiptVerification
	// ErrReceiptScope identifies authentic evidence for a different expected scope.
	ErrReceiptScope
	// ErrReceiptRollback identifies a rejected watermark rollback.
	ErrReceiptRollback
	// ErrReceiptConflict identifies incompatible watermark histories or scopes.
	ErrReceiptConflict
	// ErrChitContract identifies an invalid customer custody ticket, manifest,
	// catalog snapshot, or selection.
	ErrChitContract
	// ErrChitVerification identifies a chit or catalog fact that failed
	// authority authentication.
	ErrChitVerification
	// ErrChitConflict identifies contradictory collection versions, manifest
	// ordering, catalog pagination, or custody state.
	ErrChitConflict
	// ErrRetrievalContract identifies a download authorization contract failure.
	ErrRetrievalContract
	// ErrRetrievalBinding identifies a signed retrieval grant that does not bind
	// its exact request, object, capability, or lifetime.
	ErrRetrievalBinding
	// ErrPaymentContract identifies an invalid payment-history fact or catalog.
	ErrPaymentContract
	// ErrPaymentVerification identifies payment history that failed authority
	// authentication.
	ErrPaymentVerification

	// ErrControlWireContract identifies a control-wire scalar contract violation.
	ErrControlWireContract
	// ErrControlWireRevision identifies an unsupported control-wire revision.
	ErrControlWireRevision
	// ErrControlWireNonce identifies a rejected control-wire request nonce.
	ErrControlWireNonce
	// ErrControlWireToken identifies a rejected control-wire registration token.
	ErrControlWireToken
	// ErrControlWirePolicyCursor identifies a rejected control-wire policy cursor.
	ErrControlWirePolicyCursor
	// ErrControlWireRoute identifies a rejected control-plane route contract.
	ErrControlWireRoute
	// ErrControlWireProtocolSupport identifies an invalid support set or a
	// compatibility assessment that does not name its exact route/revision pair.
	ErrControlWireProtocolSupport
	// ErrControlWireReplayConflict identifies reuse of one request nonce for a
	// different canonical control request.
	ErrControlWireReplayConflict
	// ErrControlPlaneContract identifies a control-plane document contract violation.
	ErrControlPlaneContract
	// ErrControlPlaneSigningDomain identifies a rejected control-plane signing domain.
	ErrControlPlaneSigningDomain
	// ErrControlPlaneProductStatus identifies a rejected commercial product status.
	ErrControlPlaneProductStatus
	// ErrControlPlaneUsageWatermark identifies a rejected usage watermark.
	ErrControlPlaneUsageWatermark
	// ErrControlPlaneResponseHeader identifies a rejected response header.
	ErrControlPlaneResponseHeader
	// ErrControlPlaneResponseDocument identifies a rejected authenticated
	// response document.
	ErrControlPlaneResponseDocument
	// ErrControlPlaneResponseBinding identifies a response that does not bind to
	// the exact request that produced it.
	ErrControlPlaneResponseBinding
	// ErrControlPlaneUpgradeRequired identifies an authentic authority refusal
	// requiring the caller to upgrade before it can consume a product body.
	ErrControlPlaneUpgradeRequired
	// ErrControlPlaneProviderTimeRollback identifies an authority instant that
	// moved backward from a previously trusted one.
	ErrControlPlaneProviderTimeRollback
	// ErrControlPlaneRegistration identifies a rejected registration document.
	ErrControlPlaneRegistration
	// ErrControlPlaneInstallationBinding identifies an installation identity that
	// its own device key does not derive.
	ErrControlPlaneInstallationBinding
	// ErrControlPlaneDecisionConsistency identifies signed facts that disagree
	// with each other inside one authenticated document.
	ErrControlPlaneDecisionConsistency
	// ErrControlPlaneCheckIn identifies a rejected check-in request document.
	ErrControlPlaneCheckIn
	// ErrControlPlaneCheckInResponse identifies a rejected check-in response.
	ErrControlPlaneCheckInResponse
	// ErrControlPlaneUsageWindow identifies a rejected reported usage window.
	ErrControlPlaneUsageWindow

	// ErrFileLockUnavailable identifies a file-lock effect the operating system
	// refused for a reason other than contention. Contention is a typed outcome
	// rather than an error, so this is how a caller tells a filesystem that
	// cannot lock at all apart from another process that is simply running.
	// Contract violations in that package use ErrPrimitiveContract, because the
	// identity space is one slot from its compiler-witnessed ceiling and this is
	// the distinction a caller acts on at run time.
	ErrFileLockUnavailable

	// ErrIDContract identifies a time-ordered identifier contract violation.
	ErrIDContract
)

func (ErrorIdentity) Error 

func (i ErrorIdentity) Error() string

Error returns the stable diagnostic text for i.

func (ErrorIdentity) Is 

func (i ErrorIdentity) Is(target error) bool

Is implements error matching through the typed parent graph.

func (ErrorIdentity) IsValid 

func (i ErrorIdentity) IsValid() bool

IsValid reports whether i belongs to the closed error domain.

func (ErrorIdentity) MarshalJSON 

func (i ErrorIdentity) MarshalJSON() ([]byte, error)

MarshalJSON emits the stable identity text as a JSON string.

func (ErrorIdentity) Matches 

func (i ErrorIdentity) Matches(target ErrorIdentity) bool

Matches reports whether i is target or descends from target.

func (ErrorIdentity) String 

func (i ErrorIdentity) String() string

String returns the stable diagnostic text for i.

func (*ErrorIdentity) UnmarshalJSON 

func (i *ErrorIdentity) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only the stable text of an admitted identity.

func (ErrorIdentity) Validate 

func (i ErrorIdentity) Validate() error

Validate rejects identities outside the closed error domain.

type HTTPEndpoint added in v2026.0.3 

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

HTTPEndpoint is one absolute, credential-free HTTP or HTTPS URL. It retains the standard library's parsed representation and returns value copies to callers.

func ParseHTTPEndpoint added in v2026.0.3 

func ParseHTTPEndpoint(value string) (HTTPEndpoint, error)

ParseHTTPEndpoint parses and confines one absolute HTTP target.

func (HTTPEndpoint) HTTPURL added in v2026.0.3 

func (e HTTPEndpoint) HTTPURL() url.URL

HTTPURL returns a value copy of the parsed standard-library URL.

func (HTTPEndpoint) MarshalJSON added in v2026.0.3 

func (e HTTPEndpoint) MarshalJSON() ([]byte, error)

MarshalJSON emits one absolute endpoint.

func (HTTPEndpoint) SameOrigin added in v2026.0.3 

func (e HTTPEndpoint) SameOrigin(other HTTPEndpoint) bool

SameOrigin reports whether both endpoints share one HTTP origin after normalizing scheme and host case and the default HTTP/HTTPS ports.

func (HTTPEndpoint) String added in v2026.0.3 

func (e HTTPEndpoint) String() string

String returns the standard-library URL projection.

func (*HTTPEndpoint) UnmarshalJSON added in v2026.0.3 

func (e *HTTPEndpoint) UnmarshalJSON(data []byte) error

UnmarshalJSON parses one absolute endpoint without mutating on failure.

func (HTTPEndpoint) Validate added in v2026.0.3 

func (e HTTPEndpoint) Validate() error

Validate rejects unset, relative, credential-bearing, fragmented, or otherwise unusable HTTP targets.

type HTTPHeaderName 

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

HTTPHeaderName is a canonical MIME-style HTTP field name.

func HTTPHeaderAccept 

func HTTPHeaderAccept() HTTPHeaderName

HTTPHeaderAccept returns the validated Accept field name.

func HTTPHeaderAcceptEncoding 

func HTTPHeaderAcceptEncoding() HTTPHeaderName

HTTPHeaderAcceptEncoding returns the validated Accept-Encoding field name.

func HTTPHeaderContentEncoding 

func HTTPHeaderContentEncoding() HTTPHeaderName

HTTPHeaderContentEncoding returns the validated Content-Encoding field name.

func HTTPHeaderContentLength 

func HTTPHeaderContentLength() HTTPHeaderName

HTTPHeaderContentLength returns the validated Content-Length field name.

func HTTPHeaderContentType 

func HTTPHeaderContentType() HTTPHeaderName

HTTPHeaderContentType returns the validated Content-Type field name.

func HTTPHeaderIdempotencyKey added in v2026.0.3 

func HTTPHeaderIdempotencyKey() HTTPHeaderName

HTTPHeaderIdempotencyKey returns the validated Idempotency-Key field name.

func ParseHTTPHeaderName 

func ParseHTTPHeaderName(value string) (HTTPHeaderName, error)

ParseHTTPHeaderName validates HTTP token syntax and canonicalizes letter case.

func (HTTPHeaderName) MarshalJSON 

func (n HTTPHeaderName) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical MIME-style field name.

func (HTTPHeaderName) String 

func (n HTTPHeaderName) String() string

String returns the canonical field name.

func (*HTTPHeaderName) UnmarshalJSON 

func (n *HTTPHeaderName) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts HTTP token syntax and stores canonical MIME-style text.

func (HTTPHeaderName) Validate 

func (n HTTPHeaderName) Validate() error

Validate rejects the unset zero value.

type HTTPMediaType 

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

HTTPMediaType is one canonical standard-library-parsed media type, including any parameters. Its zero value is unset. It is deliberately not a closed enum: HTTP protocols and providers define legitimate vendor media types.

func HTTPMediaTypeOctetStream 

func HTTPMediaTypeOctetStream() HTTPMediaType

HTTPMediaTypeOctetStream returns canonical application/octet-stream.

func ParseHTTPMediaType 

func ParseHTTPMediaType(value string) (HTTPMediaType, error)

ParseHTTPMediaType parses standard media-type syntax and stores the canonical standard-library projection.

func (HTTPMediaType) Base added in v2026.0.3 

func (m HTTPMediaType) Base() (string, error)

Base returns the normalized type/subtype without parameters.

func (HTTPMediaType) IsValid 

func (m HTTPMediaType) IsValid() bool

IsValid reports whether m is a canonical parsed media type.

func (HTTPMediaType) IsZero added in v2026.0.3 

func (m HTTPMediaType) IsZero() bool

IsZero reports whether no media type is set.

func (HTTPMediaType) MarshalJSON 

func (m HTTPMediaType) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical media type.

func (HTTPMediaType) SameBase added in v2026.0.3 

func (m HTTPMediaType) SameBase(other HTTPMediaType) (bool, error)

SameBase reports whether two media types share a normalized type/subtype.

func (HTTPMediaType) String 

func (m HTTPMediaType) String() string

String returns the canonical media type and parameters.

func (*HTTPMediaType) UnmarshalJSON 

func (m *HTTPMediaType) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts standard media-type syntax and stores its admitted base.

func (HTTPMediaType) Validate 

func (m HTTPMediaType) Validate() error

Validate rejects unset or noncanonical media types.

type HTTPStatusCode 

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

HTTPStatusCode is an integer in the inclusive range 100 through 599.

func HTTPStatusOK added in v2026.0.47 

func HTTPStatusOK() HTTPStatusCode

HTTPStatusOK returns the validated 200 OK success status: the one code a caller that accepts exactly one response shape names as its expected status.

func (*HTTPStatusCode) AdmitInt added in v2026.0.47 

func (s *HTTPStatusCode) AdmitInt(value int) error

AdmitInt validates value as a status code and stores it on the receiver. It is the one admission door for a numeric code arriving from outside, such as a transport response; a code a caller expects by contract is a named constructor instead. The receiver is unchanged on rejection.

func (HTTPStatusCode) Int 

func (s HTTPStatusCode) Int() (int, error)

Int returns the validated status code as int.

func (HTTPStatusCode) IsClientError 

func (s HTTPStatusCode) IsClientError() bool

IsClientError reports whether s is in the 4xx class.

func (HTTPStatusCode) IsConflict added in v2026.0.119 

func (s HTTPStatusCode) IsConflict() bool

IsConflict reports the exact 409 state-conflict status.

func (HTTPStatusCode) IsInformational 

func (s HTTPStatusCode) IsInformational() bool

IsInformational reports whether s is in the 1xx class.

func (HTTPStatusCode) IsNotFound added in v2026.0.119 

func (s HTTPStatusCode) IsNotFound() bool

IsNotFound reports the exact 404 resource-absence status.

func (HTTPStatusCode) IsPreconditionFailed added in v2026.0.119 

func (s HTTPStatusCode) IsPreconditionFailed() bool

IsPreconditionFailed reports the exact 412 precondition refusal status.

func (HTTPStatusCode) IsRedirect 

func (s HTTPStatusCode) IsRedirect() bool

IsRedirect reports whether s is in the 3xx class.

func (HTTPStatusCode) IsServerError 

func (s HTTPStatusCode) IsServerError() bool

IsServerError reports whether s is in the 5xx class.

func (HTTPStatusCode) IsSuccess 

func (s HTTPStatusCode) IsSuccess() bool

IsSuccess reports whether s is in the 2xx class.

func (HTTPStatusCode) MarshalJSON 

func (s HTTPStatusCode) MarshalJSON() ([]byte, error)

MarshalJSON emits the status as a canonical JSON integer.

func (HTTPStatusCode) PermitsResponseBody added in v2026.0.3 

func (s HTTPStatusCode) PermitsResponseBody() bool

PermitsResponseBody reports whether the status alone permits a response body. Informational responses, 204, and 304 never carry one. Request-method rules, such as HEAD suppressing a body that the status otherwise permits, remain the HTTP operation owner's decision.

func (*HTTPStatusCode) UnmarshalJSON 

func (s *HTTPStatusCode) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts a canonical JSON integer from 100 through 599.

func (HTTPStatusCode) Validate 

func (s HTTPStatusCode) Validate() error

Validate rejects unset or out-of-range status codes.

type OffWireEnum added in v2026.0.3 

type OffWireEnum interface {
	Validatable
	OffWireEnum()
}

OffWireEnum is the compiler-visible positive declaration that a validated closed enum is intentionally off wire. Go interfaces cannot express method absence, so each declaring package separately proves that its enum implements no marshaler. This interface owns the marker method instead of leaving its name as an informal convention repeated across packages.

type Offering added in v2026.0.3 

type Offering struct {
	// Token is the consumer-owned canonical product identity.
	Token string
}

Offering carries one bounded consumer-owned product identity. Primitive validates its transport shape but never enumerates or interprets products.

func (Offering) IsValid added in v2026.0.3 

func (o Offering) IsValid() bool

IsValid reports whether o carries a canonical consumer-owned identity.

func (Offering) MarshalJSON added in v2026.0.3 

func (o Offering) MarshalJSON() ([]byte, error)

MarshalJSON emits canonical offering text.

func (Offering) String added in v2026.0.3 

func (o Offering) String() string

String returns canonical offering text, or empty text when invalid.

func (*Offering) UnmarshalJSON added in v2026.0.3 

func (o *Offering) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only canonical offering text.

func (*Offering) UnmarshalText added in v2026.0.3 

func (o *Offering) UnmarshalText(text []byte) error

UnmarshalText accepts one canonical offering through encoding.TextUnmarshaler.

func (Offering) Validate added in v2026.0.3 

func (o Offering) Validate() error

Validate rejects unset or non-canonical product identities.

type OperatingSystem 

type OperatingSystem uint8

OperatingSystem is a closed set of operating systems supported by Primitive. 

const (

	// OperatingSystemDarwin identifies Darwin.
	OperatingSystemDarwin OperatingSystem
	// OperatingSystemLinux identifies Linux.
	OperatingSystemLinux
	// OperatingSystemWindows identifies Windows.
	OperatingSystemWindows
)

func (OperatingSystem) IsValid 

func (o OperatingSystem) IsValid() bool

IsValid reports whether o belongs to the closed operating-system domain.

func (OperatingSystem) MarshalJSON 

func (o OperatingSystem) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical operating-system token.

func (OperatingSystem) String 

func (o OperatingSystem) String() string

String returns the canonical lowercase operating-system token.

func (*OperatingSystem) UnmarshalJSON 

func (o *OperatingSystem) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only a canonical admitted operating-system token.

func (OperatingSystem) Validate 

func (o OperatingSystem) Validate() error

Validate rejects operating systems outside the closed domain.

type PackageContract 

type PackageContract struct {
	// Identity is the catalog package.
	Identity PackageIdentity
	// Kind is the package's production or test-support classification.
	Kind PackageKind
}

PackageContract binds a package identity to its admitted kind.

func (PackageContract) Validate 

func (c PackageContract) Validate() error

Validate enforces the identity-to-kind classification.

type PackageIdentity 

type PackageIdentity uint8

PackageIdentity is a closed identity for a package in Primitive's catalog. 

const (
	// PackageUnknown is the invalid zero package identity.
	PackageUnknown PackageIdentity = iota
	// PackageCore identifies the shared core package.
	PackageCore
	// PackageAttest identifies the attestation package.
	PackageAttest
	// PackageContextState identifies the context-state package.
	PackageContextState
	// PackageCurrency identifies the currency package.
	PackageCurrency
	// PackageKeygen identifies the key-generation package.
	PackageKeygen
	// PackageTestSerial identifies the serial test-support package.
	PackageTestSerial
	// PackageFileLock identifies the advisory file-lock package.
	PackageFileLock
	// PackageFilestore identifies the file-store package.
	PackageFilestore
	// PackageHostFacts identifies the host-facts package.
	PackageHostFacts
	// PackageTemporal identifies the temporal package.
	PackageTemporal
	// PackageExchange identifies the HTTP exchange package.
	PackageExchange
	// PackageFuzzFinder identifies the fuzz-artifact finder package.
	PackageFuzzFinder
	// PackageLease identifies the lease package.
	PackageLease
	// PackageGate identifies the new-work authorization package.
	PackageGate
	// PackageReceipt identifies authenticated accepted-evidence facts and watermarks.
	PackageReceipt
	// PackageControlWire identifies the shared control-wire scalar package.
	PackageControlWire
	// PackageControlPlane identifies the signed control-plane document package.
	PackageControlPlane
	// PackageSubmission identifies evidence-submission authorization documents.
	PackageSubmission
	// PackageSubmissionAuth identifies installation-credential binding for one
	// evidence-submission request.
	PackageSubmissionAuth
	// PackageControlPlaneTest identifies real control-plane test fixtures.
	PackageControlPlaneTest
	// PackageProcess identifies the process package.
	PackageProcess
	// PackageRelease identifies the release package.
	PackageRelease
	// PackageShutdown identifies the shutdown package.
	PackageShutdown
	// PackageObjectStore identifies the object-store package.
	PackageObjectStore
	// PackageTimeProof identifies the time-proof package.
	PackageTimeProof
	// PackageCloudIdentity identifies the cloud-identity package.
	PackageCloudIdentity
	// PackageDeploy identifies exact release publication to GCS.
	PackageDeploy
	// PackageUpgrade identifies the upgrade package.
	PackageUpgrade
	// PackageGCSObjects identifies the authenticated Cloud Storage package.
	PackageGCSObjects
	// PackageID identifies the time-ordered identifier package.
	PackageID
	// PackageChit identifies immutable custody tickets and bounded catalogs.
	PackageChit
	// PackageChitAuth identifies installation binding for chit catalog queries.
	PackageChitAuth
	// PackageRetrieval identifies authenticated exact-object retrieval grants.
	PackageRetrieval
	// PackageRetrievalAuth identifies installation binding for retrieval requests.
	PackageRetrievalAuth
	// PackagePayment identifies signed payment receipts and bounded catalogs.
	PackagePayment
	// PackagePaymentAuth identifies installation binding for payment catalog queries.
	PackagePaymentAuth
	// PackageDistribution identifies signed software publication, update, and
	// upgrade agreements shared by release authorities and installed tools.
	PackageDistribution
	// PackageDistributionAuth identifies installation binding for update and upgrade requests.
	PackageDistributionAuth
	// PackageWiring identifies bounded runtime component-graph proof.
	PackageWiring
	// PackageLineIO identifies bounded line scanning over one reader.
	PackageLineIO
	// PackageManual identifies bounded human and machine manual projection.
	PackageManual
)

func ParsePackageIdentity 

func ParsePackageIdentity(value string) (PackageIdentity, error)

ParsePackageIdentity parses one canonical package name.

func (PackageIdentity) ImportPath 

func (p PackageIdentity) ImportPath() (string, error)

ImportPath returns the canonical full Go import path.

func (PackageIdentity) IsValid 

func (p PackageIdentity) IsValid() bool

IsValid reports whether p belongs to the closed package domain.

func (PackageIdentity) MarshalJSON 

func (p PackageIdentity) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical package name as a JSON string.

func (PackageIdentity) Name 

func (p PackageIdentity) Name() (string, error)

Name returns the canonical package name after validation.

func (PackageIdentity) String 

func (p PackageIdentity) String() string

String returns the canonical package name, or an empty string when invalid.

func (*PackageIdentity) UnmarshalJSON 

func (p *PackageIdentity) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only a canonical admitted package name.

func (PackageIdentity) Validate 

func (p PackageIdentity) Validate() error

Validate rejects identities outside the closed package domain.

type PackageKind 

type PackageKind uint8

PackageKind classifies a catalog package as production or test support. 

const (
	// PackageKindUnknown is the invalid zero package kind.
	PackageKindUnknown PackageKind = iota
	// PackageKindProduction identifies a runtime library package.
	PackageKindProduction
	// PackageKindTestSupport identifies a package used only by tests.
	PackageKindTestSupport
)

func (PackageKind) IsValid 

func (k PackageKind) IsValid() bool

IsValid reports whether k belongs to the closed package-kind domain.

func (PackageKind) MarshalJSON 

func (k PackageKind) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical package-kind string.

func (PackageKind) String 

func (k PackageKind) String() string

String returns the canonical kind text, or an empty string when invalid.

func (*PackageKind) UnmarshalJSON 

func (k *PackageKind) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only a canonical package-kind string.

func (PackageKind) Validate 

func (k PackageKind) Validate() error

Validate rejects kinds outside the closed package-kind domain.

type PathComponent 

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

PathComponent is one canonical, nonempty native filesystem component.

func ParsePathComponent 

func ParsePathComponent(value string) (PathComponent, error)

ParsePathComponent validates one component without touching the filesystem.

func (PathComponent) MarshalJSON 

func (c PathComponent) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical component as a JSON string.

func (PathComponent) String 

func (c PathComponent) String() string

String returns the validated component text.

func (*PathComponent) UnmarshalJSON 

func (c *PathComponent) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts one canonical native path component.

func (PathComponent) Validate 

func (c PathComponent) Validate() error

Validate rejects the unset zero value.

type Platform 

type Platform struct {
	// OperatingSystem is the platform operating system.
	OperatingSystem OperatingSystem
	// Architecture is the platform CPU architecture.
	Architecture CPUArchitecture
}

Platform pairs one admitted operating system and CPU architecture.

func (Platform) MarshalJSON 

func (p Platform) MarshalJSON() ([]byte, error)

MarshalJSON emits canonical platform text as a JSON string.

func (Platform) String 

func (p Platform) String() string

String returns canonical platform text, or empty text when invalid.

func (*Platform) UnmarshalJSON 

func (p *Platform) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only canonical admitted platform text.

func (*Platform) UnmarshalText added in v2026.0.3 

func (p *Platform) UnmarshalText(text []byte) error

UnmarshalText accepts canonical platform text through encoding.TextUnmarshaler.

func (Platform) Validate 

func (p Platform) Validate() error

Validate enforces both closed enum members.

type RelativePath 

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

RelativePath is one lexically clean native path confined by an os.Root. The value "." names the root itself.

func ParseRelativePath 

func ParseRelativePath(value string) (RelativePath, error)

ParseRelativePath validates native root-relative path form without filesystem I/O.

func (RelativePath) Join added in v2026.0.21 

func (p RelativePath) Join(component PathComponent) (RelativePath, error)

Join appends one validated component to a relative path.

Building a nested path out of filepath.Join and re-parsing the result is the shape this replaces. That round trip validates only the finished string, so a component that was never a legal component on its own could still produce a legal-looking path; here each part is admitted by the type that owns it before it is joined.

func (RelativePath) Resolve added in v2026.0.22 

func (p RelativePath) Resolve(names ...string) (RelativePath, error)

Resolve joins names below a relative path, admitting each as its own component. It is Resolve's counterpart for paths already confined to a root.

func (RelativePath) String 

func (p RelativePath) String() string

String returns the validated native path.

func (RelativePath) Validate 

func (p RelativePath) Validate() error

Validate rejects the unset zero value.

type ReleaseVersion added in v2026.0.3 

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

ReleaseVersion is one exact three-component release order.

func NewReleaseVersion added in v2026.0.3 

func NewReleaseVersion(major, minor, patch uint32) ReleaseVersion

NewReleaseVersion constructs the complete uint32 release-version domain.

func (ReleaseVersion) Compare added in v2026.0.3 

func (v ReleaseVersion) Compare(other ReleaseVersion) (Comparison, error)

Compare orders two validated release versions.

func (ReleaseVersion) MarshalJSON added in v2026.0.3 

func (v ReleaseVersion) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical version as a JSON string.

func (ReleaseVersion) String added in v2026.0.3 

func (v ReleaseVersion) String() string

String returns the canonical decimal release version.

func (*ReleaseVersion) UnmarshalJSON added in v2026.0.3 

func (v *ReleaseVersion) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only canonical version text.

func (*ReleaseVersion) UnmarshalText added in v2026.0.3 

func (v *ReleaseVersion) UnmarshalText(text []byte) error

UnmarshalText accepts canonical release-version text through encoding.TextUnmarshaler.

func (ReleaseVersion) Validate added in v2026.0.3 

func (v ReleaseVersion) Validate() error

Validate proves the version crossed a constructor or decode boundary.

type SHA256Digest 

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

SHA256Digest is a set SHA-256 digest. Its zero value is invalid.

func NewSHA256Digest 

func NewSHA256Digest(value [SHA256DigestBytes]byte) SHA256Digest

NewSHA256Digest constructs a set digest from all 32 bytes.

func SHA256Of added in v2026.0.34 

func SHA256Of(data []byte) SHA256Digest

SHA256Of returns the digest of one complete in-memory buffer.

It is the whole-buffer companion to DigestWriter. A caller that already holds every byte does not need a streaming writer to hash them, and threading one buffer through io.Writer plumbing to reach the same answer is ceremony, not safety. The streaming path stays for bytes that arrive over time or must be teed; this is for bytes that are already here. A whole-buffer hash cannot fail: len(data) is an int, so the byte count is always a legal length.

func (SHA256Digest) Bytes 

func (d SHA256Digest) Bytes() ([SHA256DigestBytes]byte, error)

Bytes returns the digest bytes after validating that the value is set.

func (SHA256Digest) Hex 

func (d SHA256Digest) Hex() (string, error)

Hex returns canonical lowercase hexadecimal.

func (SHA256Digest) MarshalJSON 

func (d SHA256Digest) MarshalJSON() ([]byte, error)

MarshalJSON emits canonical lowercase hexadecimal as a JSON string.

func (*SHA256Digest) UnmarshalJSON 

func (d *SHA256Digest) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only canonical lowercase hexadecimal.

func (*SHA256Digest) UnmarshalText added in v2026.0.5 

func (d *SHA256Digest) UnmarshalText(text []byte) error

UnmarshalText accepts exactly one canonical lowercase hexadecimal digest through encoding.TextUnmarshaler. The receiver is unchanged on rejection.

func (SHA256Digest) Validate 

func (d SHA256Digest) Validate() error

Validate rejects an unset digest.

type SecretMaterial 

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

SecretMaterial is a shared handle to an owned 16-to-64-byte nonzero value whose formatter is always redacted. Copying the handle does not copy the bytes: every copy observes destruction of the same Core-owned storage. Its zero value is invalid.

func NewSecretMaterial 

func NewSecretMaterial(value []byte) (SecretMaterial, error)

NewSecretMaterial validates and copies value into fixed-capacity storage.

func (SecretMaterial) ByteCount 

func (m SecretMaterial) ByteCount() (ByteCount, error)

ByteCount returns the validated material length.

func (SecretMaterial) CopyBytes 

func (m SecretMaterial) CopyBytes() ([]byte, error)

CopyBytes returns an independent caller-owned copy after validating the material. Destroy cannot zero copies already returned to a caller.

func (SecretMaterial) Destroy 

func (m SecretMaterial) Destroy() error

Destroy zeros Core-owned storage and invalidates every copied handle that shares it. Repeated destruction is an idempotent success.

func (SecretMaterial) Format 

func (m SecretMaterial) Format(state fmt.State, _ rune)

Format writes RedactedValueText for every formatting verb.

func (SecretMaterial) MarshalJSON 

func (m SecretMaterial) MarshalJSON() ([]byte, error)

MarshalJSON refuses to serialize secret material through the JSON boundary.

func (SecretMaterial) Validate 

func (m SecretMaterial) Validate() error

Validate enforces active state, length, nonzero content, and zero padding.

type StrictJSONLimits 

type StrictJSONLimits struct {
	// DocumentMaximumBytes bounds the complete encoded document.
	DocumentMaximumBytes ByteCount
	// NestingDepthMaximum bounds simultaneously open arrays and objects.
	NestingDepthMaximum uint16
	// ObjectFieldMaximum bounds fields in each object.
	ObjectFieldMaximum uint16
	// ArrayItemMaximum bounds items in each array.
	ArrayItemMaximum uint32
}

StrictJSONLimits supplies positive, caller-owned bounds for one JSON operation. The limits bound the input and Core's structural scan; they cannot bound work performed by T's UnmarshalJSON or Validate methods. Callers may choose limits at or below the package maxima.

func DefaultStrictJSONLimits 

func DefaultStrictJSONLimits() StrictJSONLimits

DefaultStrictJSONLimits returns the documented bounded JSON policy.

func (StrictJSONLimits) Validate 

func (l StrictJSONLimits) Validate() error

Validate rejects zero or globally unsupported JSON limits.

type TestIsolationDeclaration 

type TestIsolationDeclaration struct {
	// Hazard identifies the shared-state behavior under test.
	Hazard TestIsolationHazard
	// Scope identifies the boundary that must remain non-parallel.
	Scope TestIsolationScope
}

TestIsolationDeclaration binds one generic hazard to its exact enforced concurrency scope.

func (TestIsolationDeclaration) Validate 

func (d TestIsolationDeclaration) Validate() error

Validate rejects incomplete declarations and mismatched hazard/scope pairs.

type TestIsolationHazard 

type TestIsolationHazard uint8

TestIsolationHazard identifies a generic shared-state hazard that prevents a Go test from safely running in parallel. 

const (
	// TestIsolationHazardUnknown is the invalid zero hazard.
	TestIsolationHazardUnknown TestIsolationHazard = iota
	// TestIsolationHazardProcessEnvironment identifies process environment mutation.
	TestIsolationHazardProcessEnvironment
	// TestIsolationHazardProcessWorkingDirectory identifies working-directory mutation.
	TestIsolationHazardProcessWorkingDirectory
	// TestIsolationHazardProcessSignal identifies process signal-handler mutation.
	TestIsolationHazardProcessSignal
	// TestIsolationHazardProcessOutput identifies process output redirection.
	TestIsolationHazardProcessOutput
	// TestIsolationHazardProcessLogger identifies process-global logger mutation.
	TestIsolationHazardProcessLogger
	// TestIsolationHazardGlobalRegistry identifies a mutable package-global registry.
	TestIsolationHazardGlobalRegistry
	// TestIsolationHazardRuntimeAllocation identifies process-wide allocation observation.
	TestIsolationHazardRuntimeAllocation
	// TestIsolationHazardSiblingOrder identifies deliberately ordered sibling subtests.
	TestIsolationHazardSiblingOrder
)

func (TestIsolationHazard) GoIdentifier 

func (h TestIsolationHazard) GoIdentifier() string

GoIdentifier returns the exact Core constant identifier recognized by the pinned test-isolation analyzer.

func (TestIsolationHazard) IsValid 

func (h TestIsolationHazard) IsValid() bool

IsValid reports whether h belongs to the closed hazard domain.

func (TestIsolationHazard) OffWireEnum added in v2026.0.3 

func (TestIsolationHazard) OffWireEnum()

OffWireEnum declares TestIsolationHazard as analyzer policy rather than a wire encoding.

func (TestIsolationHazard) String added in v2026.0.3 

func (h TestIsolationHazard) String() string

String returns the compiler-owned diagnostic label for h.

func (TestIsolationHazard) Validate 

func (h TestIsolationHazard) Validate() error

Validate rejects hazards outside the closed domain.

type TestIsolationScope 

type TestIsolationScope uint8

TestIsolationScope identifies the concurrency boundary protected by a test isolation declaration. 

const (
	// TestIsolationScopeUnknown is the invalid zero scope.
	TestIsolationScopeUnknown TestIsolationScope = iota
	// TestIsolationScopeSiblingTable protects ordering among sibling subtests.
	TestIsolationScopeSiblingTable
	// TestIsolationScopePackageProcess protects process-global state shared by package tests.
	TestIsolationScopePackageProcess
)

func (TestIsolationScope) GoIdentifier 

func (s TestIsolationScope) GoIdentifier() string

GoIdentifier returns the exact Core constant identifier recognized by the pinned test-isolation analyzer.

func (TestIsolationScope) IsValid 

func (s TestIsolationScope) IsValid() bool

IsValid reports whether s belongs to the closed scope domain.

func (TestIsolationScope) OffWireEnum added in v2026.0.3 

func (TestIsolationScope) OffWireEnum()

OffWireEnum declares TestIsolationScope as analyzer policy rather than a wire encoding.

func (TestIsolationScope) String added in v2026.0.3 

func (s TestIsolationScope) String() string

String returns the compiler-owned diagnostic label for s.

func (TestIsolationScope) Validate 

func (s TestIsolationScope) Validate() error

Validate rejects scopes outside the closed domain.

type Validatable 

type Validatable interface {
	Validate() error
}

Validatable is implemented by values that own a boundary invariant.

type ValidatedJSONMarshaler 

type ValidatedJSONMarshaler interface {
	Validatable
	json.Marshaler
}

ValidatedJSONMarshaler is a value with an explicit JSON representation and an owner-enforced invariant. Requiring json.Marshaler prevents opaque typed values from silently encoding as empty objects.

type ValidatedJSONProjection added in v2026.0.96 

type ValidatedJSONProjection interface {
	ValidatedJSONMarshaler
	ValidateJSONProjection([]byte, StrictJSONLimits) error
}

ValidatedJSONProjection is an intentionally one-way JSON value whose owner can prove that its exact emitted bytes satisfy the strict wire contract.

EncodeValidatedJSON normally proves stability by decoding back into the producer type. That is deliberately impossible for issue-only bearer projections: only their distinct receive-only document may admit external bytes. This contract keeps those directions separate without weakening the encoder's strict grammar, resource, or exact-projection proof.

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.