cache

type Backend interface {
	// Get returns a payload copy and explicit presence; failures are not misses.
	Get(context.Context, string) (Record, bool, error)
	// Set atomically applies condition and owns stored payload bytes on success.
	Set(context.Context, string, Record, Condition) (bool, error)
	// Delete atomically removes a key and reports presence, not value contents.
	Delete(context.Context, string) (bool, error)
}

type BulkResult[K, V any] struct {
	// Key is the input key at the corresponding position.
	Key K
	// Result is the embedded lookup outcome; inspect Err before using it.
	Result[V]
	// Err is this key's failure; the bulk-level error only reports admission failure.
	Err error
}

type Cache[K, V any] struct {
	// contains filtered or unexported fields
}

type Clock interface {
	// Now returns the time used for wall-clock deadlines; calls must be bounded.
	Now() time.Time
}

type Codec[V any] interface {
	// Encode serializes a borrowed V; callers must not mutate it during encoding.
	Encode(V) ([]byte, error)
	// Decode reads borrowed bytes and returns V with codec-defined ownership.
	Decode([]byte) (V, error)
}

type Condition uint8

type Config[K, V any] struct {
	// Backend is a retained collaborator; Cache shutdown does not close it.
	Backend Backend
	// Keys must be built by NewKeySpace; New does not validate a zero key space.
	Keys KeySpace[K]
	// Codec is retained and may be called concurrently; callbacks are not panic-isolated.
	Codec Codec[V]
	// TTL sets positive-record freshness, hard staleness and optional sliding reads.
	TTL TTLPolicy
	// Clock is retained; its Now method must be safe for concurrent bounded calls.
	Clock Clock
	// MaxValue is the positive encoded payload limit, excluding a backend wire header.
	MaxValue int
	// MaxBatch bounds sequential bulk items; zero selects 1000.
	MaxBatch int
	// Load configures process-local flight, loader, stale and negative policy.
	Load LoadPolicy
	// Jitter optionally supplies concurrent TTL sampling; nil selects RandomJitter when needed.
	Jitter JitterSource
	// Observer optionally receives synchronous events; Cache owns no exporter lifecycle.
	Observer Observer
}

type Entry[K, V any] struct {
	// Key is the logical key, borrowed without generic deep copying.
	Key K
	// Value is borrowed for serialization during its sequential Set.
	Value V
}

type Error struct {
	// Kind selects a stable category; unknown values add no sentinel.
	Kind ErrorKind
	// Operation is included in diagnostics; callers must supply a safe action name.
	Operation Operation
	// contains filtered or unexported fields
}

type ErrorKind uint8

type Event struct {
	// Operation names the action; direct caller strings are not automatically redacted.
	Operation Operation
	// Outcome names the result; bundled cache producers use the defined constants.
	Outcome Outcome
	// Duration is non-negative cache-clock elapsed time for bundled producers.
	Duration time.Duration
	// Size is payload bytes for reads/writes, or retained key+payload bytes for removals.
	Size int
}

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

type JSONCodec[V any] struct {
	// Version is the schema byte; Encode rejects zero, Decode only compares it.
	Version byte
	// MaxEncodedSize bounds bytes including the version; non-positive selects 1 MiB.
	MaxEncodedSize int
}

type JitterSource interface {
	// Duration chooses TTL subtraction; custom results must be within the requested bound.
	Duration(time.Duration) time.Duration
}

type KeyEncoder[K any] interface {
	// EncodeKey returns deterministic borrowed key bytes or an error; size/work are caller-bounded.
	EncodeKey(K) ([]byte, error)
}

type KeySpace[K any] struct {
	// contains filtered or unexported fields
}

type LoadPolicy struct {
	// MaxConcurrent bounds running loaders; zero selects 64.
	MaxConcurrent int
	// MaxFlights bounds distinct-key flights, including queued loads and
	// completed flights retained by an explicit mutation. Zero defaults to 1024.
	MaxFlights int
	// MaxWaitersPerKey bounds attached foreground callers per flight; zero selects 1024.
	MaxWaitersPerKey int
	// NegativeTTL is absence retention; zero disables storage of negative load
	// results unless the loader returns a non-zero LoadResult.Expiry.
	NegativeTTL time.Duration
	// StaleWhileRevalidate serves stale data and admits a shared background refresh.
	StaleWhileRevalidate bool
	// StaleIfError returns the originally read stale value with a foreground refresh error.
	StaleIfError bool
	// RefreshJitter is the maximum loaded-value TTL subtraction; it must be below TTL.
	RefreshJitter time.Duration
	// Timeout bounds each loader call from the moment it acquires a loader
	// slot; zero adds no bound and negative values are rejected. A loader
	// error after expiry matches ErrLoader and ErrLoadTimeout. Loaders that
	// ignore cancellation are not abandoned, and a late success is published.
	Timeout time.Duration
	// InheritValues exposes the context values, never the cancellation or
	// deadline, of the caller that admitted the flight to its loader. Joiners'
	// values are not visible. A stale-while-revalidate refresh inherits from
	// the stale reader that started it. The admitting context is retained
	// until the flight finishes. Use inherited values only for diagnostics
	// such as correlation and tracing: the result is shared by every waiter
	// and stored for later readers, so anything that changes it, such as a
	// tenant or principal, belongs in the key.
	InheritValues bool
}

type LoadResult[V any] struct {
	// Value is the loader result, shared without deep copying among waiters.
	Value V
	// Found distinguishes a present zero/nil value from authoritative absence.
	Found bool
	// Expiry optionally replaces the fresh TTL and jitter (found) or NegativeTTL
	// (absent) for this entry; zero keeps the cache policy. A non-zero Expiry on
	// an absent result is stored even when NegativeTTL is zero. A passed
	// deadline deletes the key; waiters still receive this result.
	Expiry Expiry
}

type Loader[K, V any] func(context.Context, K) (LoadResult[V], error)

type MutationResult[K any] struct {
	// Key is the input key at the corresponding position.
	Key K
	// Err is this mutation's failure; other items are still attempted.
	Err error
}

type Observer interface {
	// Observe receives an event synchronously; returned errors and panics are ignored by cache notification.
	Observe(context.Context, Event) error
}

type Operation string

type Outcome string

type OwnershipBackend interface {
	Backend
	// SetIfOwned compares ownership and publishes atomically, or reports loss/failure.
	SetIfOwned(context.Context, string, Record, OwnershipGuard) error
}

type OwnershipGuard interface {
	// StorageKey returns the external lease storage coordinate; it may be sensitive.
	StorageKey() string
	// Owner returns the opaque identity to compare with the active owner.
	Owner() string
	// Token returns the opaque fencing identity to compare, not a numeric order.
	Token() string
}

type RandomJitter struct{}

type Record struct {
	// Payload is caller-owned mutable encoded data; Clone isolates its bytes.
	Payload []byte
	// ExpiresAt is the first instant the value is no longer fresh.
	ExpiresAt time.Time
	// StaleAt is the hard usability deadline, at or after ExpiresAt.
	StaleAt time.Time
	// Negative marks authoritative absence and requires an empty payload.
	Negative bool
}

type Result[V any] struct {
	// State is Hit, Miss or Stale on success; inspect the error before zero state.
	State State
	// Value is usable for Hit/Stale; generic references are not deep copied.
	Value V
	// Negative marks a cached or just-loaded authoritative-absence miss.
	Negative bool
}

type State uint8

type StringKeyEncoder struct{}

type SystemClock struct{}

type TTLPolicy struct {
	// TTL is the strictly positive fresh duration.
	TTL time.Duration
	// StaleFor is additional non-negative hard-retention time after freshness.
	StaleFor time.Duration
	// Sliding rewrites fresh records on hit with IfPresent, not record-version CAS.
	Sliding bool
}