cache

type Config struct {
	Enabled       bool
	TTL           time.Duration
	PruneInterval time.Duration
	MaxEntries    int
	// PinDigests is the global default for image-digest pinning. A job or step
	// may still override it via cache.pinDigests.
	PinDigests bool
	// DigestTTL bounds how long a resolved tag->digest mapping is reused.
	DigestTTL time.Duration
}

type Entry struct {
	Hash             string
	JobID            uuid.UUID
	TaskName         string
	Result           string
	Output           map[string]string
	BranchSelections []string
	RunID            uuid.UUID
	TaskRunID        uuid.UUID
	// ResolvedImageDigest is the content digest folded into Hash when the
	// originating task ran with digest pinning on. Empty when pinning was off.
	ResolvedImageDigest string
	// HashInputBlob is the canonical, secret-redacted decomposition of the
	// HashInput that produced Hash (see cache.HashInput.CanonicalJSON). Stored
	// on the cache entry so a cache hit can be explained field-by-field, not
	// only attested by the opaque digest. nil when not computed.
	HashInputBlob []byte
	// Partitions is the normalized partition list a fan-out producer emitted.
	// It is what lets a CACHED producer still expand its group: the fan-out
	// expansion needs the list, and a cache hit skips the container that would
	// have printed it.
	//
	// nil vs a non-nil empty slice is a meaningful distinction here, and it is
	// established at the SOURCE, not invented at this layer: pkgtask.Markers
	// (pkg/task/partition.go's partitionAccumulator.finish) returns a non-nil
	// []Partition{} when a producer's log explicitly parsed a
	// `##caesium::partitions [...]` line — even `[]`, the documented way to
	// declare an empty work list — and nil when no such line was ever seen.
	// Both writer sites (internal/job/job.go, internal/worker/runtime_executor.go)
	// assign that value straight onto this field, and Put/Get preserve it end to
	// end (see entryToModel/modelToEntry). So: nil means no partition list was
	// ever RECORDED for this entry — every task that is not a fan-out producer,
	// and every entry written before this field existed — while a non-nil
	// (possibly zero-length) slice means the producer's execution genuinely
	// determined the list, even if it came out empty. A cache-hit call site
	// facing nil cannot tell "not a producer" from "a pre-fan-out entry for a
	// producer whose consumer now expects a group", so it must check separately
	// (run.Store.HasFanOutSuccessor) before trusting an empty read as onEmpty.
	Partitions []pkgtask.Partition `json:"partitions,omitempty"`
	CreatedAt  time.Time
	ExpiresAt  *time.Time
}

type HashInput struct {
	JobAlias string
	TaskName string
	Image    string
	// ResolvedImageDigest is the content digest (sha256:...) the Image tag
	// resolved to when digest pinning is enabled. It is empty when pinning is
	// off, in which case the hash is byte-identical to the pre-pinning era and
	// only the mutable tag contributes. When set, the digest is folded into the
	// key in addition to the tag, so a tag that moves to a new digest yields a
	// different hash — a cache miss, never a stale hit.
	ResolvedImageDigest string
	Command             []string
	// Env is the step-declared environment after ${CAESIUM_PARAM_*}
	// interpolation and predecessor-output injection, and before secret://
	// resolution. The substituted values (not the tokens) are what Compute
	// folds in, so two runs that differ only in a referenced param miss.
	Env                  map[string]string
	WorkDir              string
	Mounts               []container.Mount
	ResolvedVolumeMounts []container.VolumeMount
	Kubernetes           *container.KubernetesSpec
	PredecessorHashes    []string
	PredecessorOutputs   map[string]map[string]string
	RunParams            map[string]string
	// Partition is the instance key. Hashed only when non-empty so unfanned
	// tasks and pre-fan-out hashes stay byte-identical (no CacheVersion bump).
	Partition string
	// PartitionFingerprint is the optional per-unit content address.
	// Hashed only when non-empty. dependsOn is NOT hashed.
	PartitionFingerprint string
	// PartitionAttributes are free-form scalar attributes, hashed with sorted
	// keys only when the map is non-empty.
	PartitionAttributes map[string]string
	// Chain selects whether PredecessorHashes enter the key: ChainTransitive
	// (the default, and what an empty string means) or ChainValues. It carries
	// the resolved jobdef cache config's Chain and is threaded through every
	// HashInput construction site so the local, worker and replay lanes cannot
	// disagree about one task's identity.
	Chain        string
	CacheVersion int
}

type HashInputBlob struct {
	// BlobVersion is HashInputBlobVersion at serialization time.
	BlobVersion int `json:"blobVersion"`
	// Hash is the Compute() digest this blob decomposes. Storing it inline lets
	// a reader confirm the blob matches the persisted TaskRun.Hash before
	// trusting the decomposition.
	Hash string `json:"hash"`

	JobAlias             string                       `json:"jobAlias,omitempty"`
	TaskName             string                       `json:"taskName,omitempty"`
	Image                string                       `json:"image,omitempty"`
	ResolvedImageDigest  string                       `json:"resolvedImageDigest,omitempty"`
	Command              []string                     `json:"command,omitempty"`
	Env                  map[string]envBlobValue      `json:"env,omitempty"`
	WorkDir              string                       `json:"workDir,omitempty"`
	Mounts               []container.Mount            `json:"mounts,omitempty"`
	ResolvedVolumeMounts []container.VolumeMount      `json:"resolvedVolumeMounts,omitempty"`
	Kubernetes           *container.KubernetesSpec    `json:"kubernetes,omitempty"`
	PredecessorHashes    []string                     `json:"predecessorHashes,omitempty"`
	PredecessorOutputs   map[string]map[string]string `json:"predecessorOutputs,omitempty"`
	RunParams            map[string]string            `json:"runParams,omitempty"`

	// Chain records the cache chain mode ONLY when it is ChainValues; the
	// default transitive mode writes nothing, so every blob produced before this
	// field existed stays byte-identical and HashInputBlobVersion stays 1. It is
	// what lets `caesium why` say "predecessor hashes excluded (chain: values)"
	// rather than reporting a predecessor-hash change that never discriminated
	// the two keys. PredecessorHashes are still recorded verbatim in values mode:
	// they are real provenance and useful to a reader, they simply did not enter
	// the digest.
	Chain string `json:"chain,omitempty"`

	// Partition / PartitionFingerprint / PartitionAttributes mirror, field by
	// field, the single framed partition_identity record Compute() folds in (see
	// HashInput.partitionIdentity). They are kept as three separate JSON fields
	// here rather than one nested object because `caesium why` diffs the blob
	// field-by-field and a nested object would report a whole-block change for a
	// single changed attribute. JSON object fields cannot alias one another, so
	// the blob was never subject to the delimiter-forging the hash's old
	// line-oriented form allowed — but the SET of fields must stay in lockstep
	// with partitionIdentity, or the blob would stop explaining the digest.
	// dependsOn appears in neither: it is scheduling, not an execution input.
	Partition            string            `json:"partition,omitempty"`
	PartitionFingerprint string            `json:"partitionFingerprint,omitempty"`
	PartitionAttributes  map[string]string `json:"partitionAttributes,omitempty"`

	CacheVersion int `json:"cacheVersion"`

	// Oversized is set (with Digest/EnvCount/PredecessorOutputCount populated
	// and the verbatim fields cleared) when the full decomposition exceeded
	// maxHashInputBlobBytes. A reader can still report "inputs changed" via the
	// digest but cannot diff field-by-field.
	Oversized *oversizedBlob `json:"oversized,omitempty"`
}

type PriorEntry struct {
	// Hash is the identity hash the prior successful execution committed to.
	Hash string
	// Output is the structured output that execution produced. For a
	// large-object reference (pkg/task.OutputRef) the value embeds the content
	// digest, so byte-equality of this map proves payload-content equality.
	Output map[string]string
	// CreatedAt orders candidates so the most recent proven-equal prior wins.
	CreatedAt int64
}

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