receipt

type Drift struct {
	Kind     DriftKind `json:"kind"`
	Task     string    `json:"task,omitempty"`
	Expected string    `json:"expected,omitempty"`
	Actual   string    `json:"actual,omitempty"`
	Detail   string    `json:"detail"`
}

type DriftKind string

type Receipt struct {
	// ReceiptVersion is Version at build time.
	ReceiptVersion int `json:"receipt_version"`

	// RunID, JobID and JobAlias identify the run this receipt attests. They are
	// metadata for humans and lookups; they are NOT folded into ReceiptDigest
	// (two runs of byte-identical inputs produce the same digest, which is the
	// point — the digest addresses *what ran*, not *which run instance*).
	RunID    uuid.UUID `json:"run_id"`
	JobID    uuid.UUID `json:"job_id"`
	JobAlias string    `json:"job_alias,omitempty"`

	// GitCommit is the provenance commit SHA the manifest was applied from
	// (empty for non-GitOps applies). Folded into ReceiptDigest.
	GitCommit string `json:"git_commit,omitempty"`

	// ManifestContentHash is the content hash of the DAG topology the run
	// executed (from the matching dag_snapshot). Folded into ReceiptDigest so a
	// changed manifest yields a changed receipt.
	ManifestContentHash string `json:"manifest_content_hash,omitempty"`

	// Tasks are the per-task entries, sorted by TaskName. Folded into
	// ReceiptDigest in that order.
	Tasks []TaskEntry `json:"tasks"`

	// Degraded is true iff any task is Degraded — i.e. the run is NOT fully
	// reproducible (at least one mutable, unpinned tag, or a task with no
	// identity hash). When true, callers must not present this receipt as a
	// reproducibility guarantee.
	Degraded bool `json:"degraded"`

	// DegradedTasks lists the names of every degraded task, for a concise
	// honest summary.
	DegradedTasks []string `json:"degraded_tasks,omitempty"`

	// ReceiptDigest is the sha256 hex Merkle aggregate over the canonical
	// per-task lines + manifest content hash + git commit. It is the receipt's
	// content address and the value `verify` re-derives.
	ReceiptDigest string `json:"receipt_digest"`
}

type TaskEntry struct {
	// TaskName is the stable, human-meaningful name of the task within the job.
	// It is the sort key for deterministic aggregation.
	TaskName string `json:"task_name"`

	// Partition is the fan-out instance key this entry attests, empty for an
	// unfanned task. A fanned step executes N instances with N DISTINCT identity
	// hashes; collapsing them to one entry would attest a single arbitrary
	// partition and silently drop the other N-1 from the receipt. So a fanned
	// step contributes one entry per partition, discriminated by this field.
	//
	// It is omit-when-empty in both the JSON and the canonical digest line, so
	// receipts for unfanned runs keep byte-identical digests and need no Version
	// bump.
	Partition string `json:"partition,omitempty"`

	// IdentityHash is the persisted TaskRun.Hash — the content-addressed cache
	// key computed by internal/cache.HashInput.Compute. Empty when the task
	// never had a hash computed (caching disabled for it); such a task cannot
	// be attested and forces Degraded.
	IdentityHash string `json:"identity_hash"`

	// Image is the literal image reference (tag) the task ran with, recorded
	// for human readability and as the fallback identity when no digest was
	// resolved.
	Image string `json:"image"`

	// ResolvedImageDigest is the content digest (sha256:...) the tag resolved
	// to when digest pinning was on. Empty when pinning was off or a
	// Podman/k8s path fell back to the tag.
	ResolvedImageDigest string `json:"resolved_image_digest,omitempty"`

	// DigestPinned is true iff ResolvedImageDigest is non-empty — i.e. the
	// image identity is tamper-evident for this task.
	DigestPinned bool `json:"digest_pinned"`

	// Degraded is true when this task cannot be soundly attested as
	// reproducible: either its image was not digest-pinned (mutable tag) or it
	// has no identity hash at all. Such a task is honestly surfaced rather than
	// silently attested.
	Degraded bool `json:"degraded"`

	// DegradedReason is a short human-readable explanation set when Degraded is
	// true (e.g. "image not digest-pinned: mutable tag 'myimage:latest'").
	DegradedReason string `json:"degraded_reason,omitempty"`
}

type VerifyResult struct {
	// RunID echoes the run that was re-derived.
	RunID uuid.UUID `json:"run_id"`

	// Match is true iff the re-derived receipt digest equals the committed one
	// AND the run is not degraded. A degraded run never reports a clean
	// reproducibility match even when the digests are equal, because an
	// unpinned tag could have moved without changing the (tag-only) digest —
	// the very condition the receipt cannot attest against.
	Match bool `json:"match"`

	// Degraded is true iff the re-derived receipt is degraded (any task ran on
	// an unpinned, mutable tag, or had no identity hash). When true, the
	// receipt cannot soundly attest reproducibility regardless of digest
	// equality; Drifts will include the degraded tasks via the rederived
	// receipt's DegradedTasks.
	Degraded bool `json:"degraded"`

	// DegradedTasks lists the tasks that make the run unverifiable.
	DegradedTasks []string `json:"degraded_tasks,omitempty"`

	// ExpectedDigest is the committed receipt's digest; ActualDigest is the
	// freshly re-derived one.
	ExpectedDigest string `json:"expected_digest"`
	ActualDigest   string `json:"actual_digest"`

	// Drifts enumerates every divergence found, empty when Match is true.
	Drifts []Drift `json:"drifts,omitempty"`

	// Rederived is the receipt Build produced from current state, for callers
	// that want to inspect or re-commit it.
	Rederived *Receipt `json:"rederived"`
}