Help us shape the future of Go! Take the 2026 Go Developer Survey

evidence

package
v0.1.26 Latest Latest
Warning

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

 Go to latest Published: Oct 31, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package evidence verifies provider current-evidence claims against caller-owned immutable target bytes or observations of an explicitly selected live source. It intentionally has no publication, storage, repair, provider, filesystem, or Git dependencies.

Index

Constants

View Source 
const LiveNoChangeLimitation = "The selected source contains no review candidates."

LiveNoChangeLimitation is the shared wire statement for provider-free live results.

View Source 
const LiveSourceIdentityVersion = "mulgae-live-source.v1"

Variables

This section is empty.

Functions

func SourceConsistency added in v0.1.25 

func SourceConsistency(identity LiveSourceIdentity) string

func SourceImageArtifactPath added in v0.1.25 

func SourceImageArtifactPath(sessionID domain.SessionID, runID domain.RunID, digest, mediaType string) (ports.SafeRelativePath, error)

func VerifyLiveSourceArtifacts added in v0.1.25 

func VerifyLiveSourceArtifacts(live *LiveSourceMetadata, sessionID domain.SessionID, runID domain.RunID, artifacts map[string]ports.ImmutablePublicationArtifact) error

Types

type CurrentClaim 

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

CurrentClaim is an immutable, canonical current-evidence claim. Its target identity comes from the application, never from a provider verification assertion.

func NewCurrentClaim 

func NewCurrentClaim(input CurrentClaimInput) (CurrentClaim, error)

NewCurrentClaim validates and canonicalizes one current-evidence claim. TargetSHA256 accepts either lower-case hexadecimal or sha256:<hex> and is stored as sha256:<hex>. Path is converted to ports.SafeRelativePath only after UTF-8 NFC and logical-target-path checks succeed.

func NewLiveClaim added in v0.1.25 

func NewLiveClaim(identity LiveSourceIdentity, side Side, path string, lineStart, lineEnd int, quote string) (CurrentClaim, error)

NewLiveClaim binds a provider location/quote to trusted source metadata. The digest asserts source selection, never the contents of a mutable source.

func (CurrentClaim) ExcerptSHA256 

func (claim CurrentClaim) ExcerptSHA256(excerpt []byte) (string, error)

ExcerptSHA256 computes the canonical source/current excerpt identity for exact bytes under this claim. It does not assert that the bytes were read from an immutable target; callers must retain a verifier-owned receipt for that authority.

func (CurrentClaim) IdentitySHA256 added in v0.1.25 

func (claim CurrentClaim) IdentitySHA256() string

IdentitySHA256 returns the digest bound to the explicitly typed claim.

func (CurrentClaim) IsLiveSource added in v0.1.25 

func (claim CurrentClaim) IsLiveSource() bool

func (CurrentClaim) LineEnd 

func (claim CurrentClaim) LineEnd() int

LineEnd returns the one-based inclusive final line.

func (CurrentClaim) LineStart 

func (claim CurrentClaim) LineStart() int

LineStart returns the one-based inclusive first line.

func (CurrentClaim) Path 

func (claim CurrentClaim) Path() ports.SafeRelativePath

Path returns the canonical relative logical target path.

func (CurrentClaim) Quote 

func (claim CurrentClaim) Quote() string

Quote returns the exact UTF-8 quote text. It does not trim or normalize it.

func (CurrentClaim) QuoteBytes 

func (claim CurrentClaim) QuoteBytes() []byte

QuoteBytes returns a defensive copy of the exact quote bytes.

func (CurrentClaim) Side 

func (claim CurrentClaim) Side() Side

Side returns the claimed provider-wire source side.

func (CurrentClaim) SourceIdentitySHA256 added in v0.1.25 

func (claim CurrentClaim) SourceIdentitySHA256() string

SourceIdentitySHA256 returns selection metadata identity for live evidence. It never asserts that the source's complete contents were hashed.

func (CurrentClaim) TargetSHA256 

func (claim CurrentClaim) TargetSHA256() string

TargetSHA256 returns the captured-content identity, or empty for live evidence.

type CurrentClaimInput 

type CurrentClaimInput struct {
	TargetSHA256 string
	Side         Side
	Path         string
	LineStart    int
	LineEnd      int
	Quote        string
}

CurrentClaimInput contains only a provider's untrusted location-and-quote claim plus a target SHA-256 supplied by trusted application code. There is deliberately no provider-supplied verification, excerpt digest, or source reference field.

type CurrentReceipt 

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

CurrentReceipt is an immutable system-owned result. Claim preserves the canonical input identity. ExcerptSHA256 is populated only after source bytes selected a valid line range; Excerpt exposes bytes only when verified.

func (CurrentReceipt) Claim 

func (receipt CurrentReceipt) Claim() CurrentClaim

Claim returns the canonical current claim identity that was verified.

func (CurrentReceipt) Excerpt 

func (receipt CurrentReceipt) Excerpt() []byte

Excerpt returns a defensive copy of the verified excerpt. It returns nil for stale, invalid, and unverifiable receipts even if a range was selected.

func (CurrentReceipt) ExcerptSHA256 

func (receipt CurrentReceipt) ExcerptSHA256() string

ExcerptSHA256 returns the canonical excerpt digest only when source bytes selected a valid range. A quote mismatch has a digest but never exposes its selected bytes.

func (CurrentReceipt) ReasonCode 

func (receipt CurrentReceipt) ReasonCode() ReasonCode

ReasonCode returns the system-computed safe diagnostic code.

func (CurrentReceipt) SourceFileSHA256 added in v0.1.26 

func (receipt CurrentReceipt) SourceFileSHA256() string

SourceFileSHA256 identifies only the cited file bytes already read for a verified claim. It is an observation, not an atomic source-tree fingerprint.

func (CurrentReceipt) Status 

func (receipt CurrentReceipt) Status() ReceiptStatus

Status returns the system-computed closed verification status.

type ImmutableTargetAvailability 

type ImmutableTargetAvailability string

ImmutableTargetAvailability is the typed result of looking up immutable target bytes. Readers must return Available only for the exact requested target identity. Stale and Unavailable never authorize byte verification. 

const (
	ImmutableTargetAvailable   ImmutableTargetAvailability = "available"
	ImmutableTargetStale       ImmutableTargetAvailability = "stale"
	ImmutableTargetUnavailable ImmutableTargetAvailability = "unavailable"
)

func (ImmutableTargetAvailability) Valid 

func (availability ImmutableTargetAvailability) Valid() bool

Valid reports whether availability is a closed immutable-reader fact.

type ImmutableTargetReader 

type ImmutableTargetReader interface {
	ReadImmutableTarget(context.Context, string, Side, ports.SafeRelativePath) (ImmutableTargetAvailability, []byte, error)
}

ImmutableTargetReader is the consumer-owned port for exact immutable file bytes. The returned bytes must be newly allocated and owned by the caller. It receives the canonical target SHA-256, side, and SafeRelativePath that define the requested immutable file. A reader reports stale or unavailable lookup facts through ImmutableTargetAvailability rather than inferring them from provider output.

type LiveBinaryObservation added in v0.1.25 

type LiveBinaryObservation struct {
	Side         string `json:"side"`
	Path         string `json:"path"`
	SHA256       string `json:"sha256"`
	MediaType    string `json:"media_type"`
	ByteLength   int    `json:"byte_length"`
	ArtifactPath string `json:"artifact_path"`
}

type LiveBinaryReceipt added in v0.1.25 

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

LiveBinaryReceipt retains one explicitly selected raster observation. The source digest is metadata identity; FileSHA256 hashes only these image bytes.

func (LiveBinaryReceipt) Bytes added in v0.1.25 

func (receipt LiveBinaryReceipt) Bytes() []byte

func (LiveBinaryReceipt) FileSHA256 added in v0.1.25 

func (receipt LiveBinaryReceipt) FileSHA256() string

func (LiveBinaryReceipt) MediaType added in v0.1.25 

func (receipt LiveBinaryReceipt) MediaType() string

func (LiveBinaryReceipt) Path added in v0.1.25 

func (receipt LiveBinaryReceipt) Path() ports.SafeRelativePath

func (LiveBinaryReceipt) Side added in v0.1.25 

func (receipt LiveBinaryReceipt) Side() Side

func (LiveBinaryReceipt) Source added in v0.1.25 

func (receipt LiveBinaryReceipt) Source() LiveSourceIdentity

func (LiveBinaryReceipt) Valid added in v0.1.25 

func (receipt LiveBinaryReceipt) Valid() bool

type LiveSourceChange added in v0.1.25 

type LiveSourceChange struct {
	Kind   string `json:"kind"`
	Before string `json:"before"`
	After  string `json:"after"`
}

type LiveSourceIdentity added in v0.1.25 

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

LiveSourceIdentity binds the declared selector and resolved Git operands. It does not identify workspace or index contents, an inventory, or a snapshot.

func DecodeLiveSourceIdentity added in v0.1.25 

func DecodeLiveSourceIdentity(data []byte) (LiveSourceIdentity, error)

DecodeLiveSourceIdentity accepts only the exact canonical metadata encoding.

func NewLiveSourceIdentity added in v0.1.25 

func NewLiveSourceIdentity(target ports.LiveSourceTarget) (LiveSourceIdentity, error)

func (LiveSourceIdentity) Bytes added in v0.1.25 

func (identity LiveSourceIdentity) Bytes() []byte

func (LiveSourceIdentity) RunTarget added in v0.1.25 

func (identity LiveSourceIdentity) RunTarget() (domain.TargetIdentity, error)

RunTarget preserves the distinction between selection and content identity.

func (LiveSourceIdentity) SHA256 added in v0.1.25 

func (identity LiveSourceIdentity) SHA256() string

func (LiveSourceIdentity) SupportsSide added in v0.1.25 

func (identity LiveSourceIdentity) SupportsSide(side Side) bool

SupportsSide rejects sides that do not belong to this declared selector.

func (LiveSourceIdentity) Target added in v0.1.25 

func (identity LiveSourceIdentity) Target() ports.LiveSourceTarget

func (LiveSourceIdentity) Valid added in v0.1.25 

func (identity LiveSourceIdentity) Valid() bool

type LiveSourceMetadata added in v0.1.25 

type LiveSourceMetadata struct {
	Identity             json.RawMessage         `json:"identity"`
	SourceIdentitySHA256 string                  `json:"source_identity_sha256"`
	Changes              []LiveSourceChange      `json:"changes"`
	NoChange             bool                    `json:"no_change"`
	Consistency          string                  `json:"consistency"`
	ReplayAvailability   string                  `json:"replay_availability"`
	BinaryEvidence       []LiveBinaryObservation `json:"binary_evidence"`
}

type LiveSourceRead added in v0.1.25 

type LiveSourceRead struct {
	Identity       LiveSourceIdentity
	NoChange       bool
	Consistency    string
	BinaryEvidence []LiveBinaryObservation
}

LiveSourceRead describes verified source selection and retained observations. The metadata alone confers no publication authority.

func ValidateLiveSourceMetadata added in v0.1.25 

func ValidateLiveSourceMetadata(live *LiveSourceMetadata) (LiveSourceRead, error)

type ReasonCode 

type ReasonCode string

ReasonCode is a safe, closed diagnostic classification. It never embeds provider bytes, filesystem paths, or reader error strings. 

const (
	ReasonVerified                  ReasonCode = "verified"
	ReasonStaleTarget               ReasonCode = "stale_target"
	ReasonInvalidClaim              ReasonCode = "invalid_claim"
	ReasonInvalidPath               ReasonCode = "invalid_path"
	ReasonInvalidLineRange          ReasonCode = "invalid_line_range"
	ReasonLineRangeOutOfBounds      ReasonCode = "line_range_out_of_bounds"
	ReasonQuoteMismatch             ReasonCode = "quote_mismatch"
	ReasonTargetUnavailable         ReasonCode = "target_unavailable"
	ReasonReaderFailure             ReasonCode = "reader_failure"
	ReasonInvalidReaderAvailability ReasonCode = "invalid_reader_availability"
	ReasonNilReader                 ReasonCode = "nil_reader"
	ReasonNilContext                ReasonCode = "nil_context"
	ReasonContextCanceled           ReasonCode = "context_canceled"
)

func (ReasonCode) Valid 

func (code ReasonCode) Valid() bool

Valid reports whether code is a closed safe diagnostic classification.

type ReceiptStatus 

type ReceiptStatus string

ReceiptStatus is the closed verification outcome computed only by this package. Providers cannot construct receipts or set this status. 

const (
	ReceiptVerified     ReceiptStatus = "verified"
	ReceiptStale        ReceiptStatus = "stale"
	ReceiptInvalid      ReceiptStatus = "invalid"
	ReceiptUnverifiable ReceiptStatus = "unverifiable"
)

func (ReceiptStatus) Valid 

func (status ReceiptStatus) Valid() bool

Valid reports whether status is a closed verification outcome.

type Side 

type Side string

Side identifies one captured side of a current review target. 

const (
	SideBase     Side = "base"
	SideHead     Side = "head"
	SideWorktree Side = "worktree"
	SideIndex    Side = "index"
)

func (Side) Valid 

func (side Side) Valid() bool

Valid reports whether side is one of the closed current-target sides.

type Verifier 

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

Verifier uses either a captured-target reader or an explicit live-source reader.

func NewLiveVerifier added in v0.1.25 

func NewLiveVerifier(reader ports.LiveSourceReader) (*Verifier, error)

NewLiveVerifier reads the original source through the source-reader port. It owns no source copy and makes no immutable-tree or mutable-drift assertion.

func NewVerifier 

func NewVerifier(reader ImmutableTargetReader) (*Verifier, error)

NewVerifier creates a current-evidence verifier. A nil or typed-nil reader is rejected before it can weaken verification.

func (*Verifier) VerifyBinary added in v0.1.25 

func (verifier *Verifier) VerifyBinary(ctx context.Context, side Side, path ports.SafeRelativePath, expectedSHA256 string) (LiveBinaryReceipt, error)

VerifyBinary reads selected image evidence. Its verifier-owned receipt binds the exact bytes and source side; caller- or provider-created digests are not proof.

func (*Verifier) VerifyCurrent 

func (verifier *Verifier) VerifyCurrent(ctx context.Context, claim CurrentClaim) (CurrentReceipt, error)

VerifyCurrent validates the typed claim identity, obtains source bytes, and computes the receipt. Invalid evidence outcomes are returned as receipts; context and reader operation failures also return an error so callers retain cancellation and operational control flow while remaining fail-closed.

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.