cachemeta

package
v0.31.0 Latest Latest
Warning

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

 Go to latest Published: Jun 22, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package cachemeta defines the metadata contract for first-class cache entries.

It intentionally stores no payloads and owns no cache. The package only names reusable objects, their validity/security/residency metadata, and typed lookup verdicts that callers can fold without collapsing every non-hit into "false".

Tier: foundation (1) - see internal/architest. This package may import only packages whose tier is <= 1. Higher cache planes adapt their local objects down to these records instead of making this package depend on them.

Index

Constants

This section is empty.

Variables

View Source 
var ErrBadVDSOKey = errors.New("cachemeta: bad vdso key")

Functions

func AttentionIndexBindingDigest 

func AttentionIndexBindingDigest(a AttentionIndex) string

AttentionIndexBindingDigest is the deterministic identity for the DSA index binding. It covers the GLM-5.2 axes called out in the architecture memo: model, tokenizer, position convention, prefix digest, indexer version, layer group, layer consumers, and the digest of the computed index decisions.

func AttentionIndexReferences 

func AttentionIndexReferences(e Entry, kv EntryID) bool

AttentionIndexReferences reports whether an attention_index entry depends on a K/V span. kvmmu/external-engine bridges can use this predicate when a poisoned span is quarantined: any referencing DSA index must be invalidated with it.

func DigestBytes 

func DigestBytes(b []byte) string

func DigestIntentKey 

func DigestIntentKey(k IntentKey) string

DigestIntentKey is the deterministic identity for an intent entry.

func DigestMemoryView 

func DigestMemoryView(viewID, viewType string, sources []EntryID) string

func DigestPlanTemplate 

func DigestPlanTemplate(p PlanTemplate) string

DigestPlanTemplate is the deterministic identity over a plan template's binding axes. Length counts steps (advisory); the digest is the reuse key.

func DigestTokenIDs 

func DigestTokenIDs(ids []int) string

func IsProviderPrefixHit 

func IsProviderPrefixHit(e Entry) bool

IsProviderPrefixHit reports whether an entry is a provider-resident prompt-prefix cache hit — the shape FromProviderCache produces. The goal language for #112 names this as plane=prompt_prefix, residency=provider; the shipped entry carries MediaType=prompt_prefix with provider residency, so this predicate identifies it regardless of the Plane label other code already keys on (PlaneProvider vs the PlanePrompt="prompt_prefix" alias). Callers and benchmarks use this to route an entry to the provider counter, never the local one.

func IsProviderResidency 

func IsProviderResidency(e Entry) bool

IsProviderResidency reports whether an entry's payload lives on a remote provider (Anthropic/OpenAI/etc.) rather than in a locally-owned cache tier. A provider-resident entry is cost/latency telemetry only; its tokens were never re-served by a fak-local cache, so they must not be attributed to a local reuse win.

func LocalReuseTokens 

func LocalReuseTokens(e Entry) int64

LocalReuseTokens returns the prefill tokens an entry may be credited to a LOCAL reuse win, and zero for any provider-resident entry. This is the double-count guard: a token-counting benchmark that sums LocalReuseTokens over a mixed entry stream can never count a provider hit's cached_tokens as a local saving, because a provider entry contributes 0 here. The same provider tokens are still observable via ProviderReadTokens for the distinct provider metric.

func ManifestBindingDigest 

func ManifestBindingDigest(m KVManifest) string

ManifestBindingDigest is the deterministic sha256 over every binding axis of a KVManifest. It is what a signature MUST cover, so a checker can detect tampering of any field a resident span is allowed to reuse against.

func ProviderReadTokens 

func ProviderReadTokens(e Entry) int64

ProviderReadTokens returns the provider-reported cache-read (cached) tokens for a provider-resident prompt-prefix entry, and zero otherwise. This is the counterpart to LocalReuseTokens: a metrics sink credits these to the provider cache counter, kept DISTINCT from the local KV/tool reuse total. A local entry contributes 0 here, so the two accumulators partition the token stream with no overlap.

func ShapeGLMTurn 

func ShapeGLMTurn(turn []PromptSegment, deps []PrefixDependency, world map[string]string) (shaped []PromptSegment, directive PrefixBreakDirective, report StabilityReport)

ShapeGLMTurn is the hosted-GLM coherence front-end's single entry point — the one call a gateway / OpenAI-proxy makes per GLM turn. It runs the §A4 coherence check over the turn's provider-prefix dependencies against the current world and, if a witness is refuted, returns the turn with the break marker injected ahead of the stale span (so the provider cannot serve a now-stale cached prefix); otherwise it returns the turn unchanged. The directive records WHAT was done (for metrics/audit); the report is the §A3 stability of the SHAPED turn — what the provider will actually be able to cache after coherence shaping. This is the seam the live gateway plugs into; everything below it (decision, injection, stability) is already witnessed.

func ShapeGLMTurnRevoked 

func ShapeGLMTurnRevoked(turn []PromptSegment, deps []PrefixDependency, revoked func(witness string) bool) (shaped []PromptSegment, directive PrefixBreakDirective, report StabilityReport)

ShapeGLMTurnRevoked is ShapeGLMTurn wired to the live revocation bus: the gateway passes `vdso.Default.Revoked` (or any revocation predicate over the recall layer's per-page trust witnesses) and gets back the coherence-shaped turn. This is the exact call the live OpenAI-proxy makes per GLM turn — deps come from the recorded prefix's witnessed pages, `revoked` from the vdso/gateway bus. The cachemeta layer stays decoupled (it takes a predicate, never imports vdso).

func ShapeGLMTurnSegmentWitnessed 

func ShapeGLMTurnSegmentWitnessed(turn []PromptSegment, revoked func(witness string) bool) (shaped []PromptSegment, directive PrefixBreakDirective, report StabilityReport)

ShapeGLMTurnSegmentWitnessed is the simplest live-path form: the turn's segments carry their own trust witnesses (PromptSegment.Witness), so no separate deps list and no page-vs-prompt coordinate alignment is needed. The live OpenAI-proxy builds segments from the request messages (attaching each tool-result segment's witness from the recorded page that produced it) and calls this with vdso.Default.Revoked. A revoked witness breaks the prefix at that segment.

func TurnsFromConversation 

func TurnsFromConversation(parts []ConvPart) [][]PromptSegment

TurnsFromConversation builds the cumulative per-turn prefixes AnalyzeStability consumes. Each "assistant" part is a model request, so the prompt for that request is every part strictly before it (the running system + tool-schema + prior messages + tool results). The result is one turn per assistant request, in order.

Types

type AdmissionVerdict 

type AdmissionVerdict string

AdmissionVerdict is the cache-facing form of the admission decision that let this entry be stored or reused. 

const (
	AdmissionUnknown        AdmissionVerdict = ""
	AdmissionAllow          AdmissionVerdict = "allow"
	AdmissionTransform      AdmissionVerdict = "transform"
	AdmissionQuarantine     AdmissionVerdict = "quarantine"
	AdmissionRequireWitness AdmissionVerdict = "require_witness"
	AdmissionDeny           AdmissionVerdict = "deny"
	AdmissionDefer          AdmissionVerdict = "defer"
)

func AdmissionFromVerdict 

func AdmissionFromVerdict(k abi.VerdictKind) AdmissionVerdict

type AttentionIndex 

type AttentionIndex struct {
	PrefixDigest      string
	Tokens            []int
	PrefixLength      int64
	ModelID           string
	TokenizerID       string
	PositionMode      PositionMode
	IndexerID         string
	LayerGroup        string
	Layers            []int
	DecisionDigest    string
	ParentKV          EntryID
	Owner             string
	Lease             string
	Causal            bool
	CausalityWitness  string
	QualityDeltaProbe float64
}

AttentionIndex is the payload-free metadata for a dynamic-sparse-attention index artifact. GLM-5.2's DSA/IndexShare path computes content-dependent key selections that can be shared across a layer group; cachemeta records the binding axes and dependency graph, never the index payload itself.

type AttentionIndexRequest 

type AttentionIndexRequest struct {
	PrefixDigest    string
	Tokens          []int
	PrefixLength    int64
	ModelID         string
	TokenizerID     string
	PositionMode    PositionMode
	IndexerID       string
	LayerGroup      string
	DecisionDigest  string
	ParentKV        EntryID
	MaxQualityDelta float64
	AllowNonCausal  bool
}

AttentionIndexRequest is the set of axes a lookup must match before a DSA index may be reused. A non-causal candidate fails closed unless AllowNonCausal is explicit, because prefix exactness depends on the indexer being determined only by tokens at positions <= the query position.

type Coherence 

type Coherence struct {
	Consumers        []Consumer
	Parents          []EntryID
	InvalidationMode InvalidationMode
}

Coherence records dependency and invalidation metadata.

type Consumer 

type Consumer struct {
	Kind    string
	ID      string
	AgentID string
	TraceID string
}

Consumer identifies a session, agent, or derived entry that consumed a shared cache entry. Shared entries need this graph for causal invalidation.

type ContextPage 

type ContextPage struct {
	SessionID   string
	Step        int
	Role        string
	Descriptor  string
	Digest      string
	Len         int64
	Taint       abi.TaintLabel
	Quarantined bool
	QID         string
	Reason      string
	Witness     string
	TrustEpoch  uint64
}

ContextPage is the field-only shape a durable recall/context-page adapter lowers into. It mirrors the metadata needed from recall.Page without making cachemeta import recall.

type ConvPart 

type ConvPart struct {
	Role     string // "system" | "tool_schema" | "user" | "assistant" | "tool_result"
	Content  []byte
	Tokens   int64 // 0 => estimated from Content (~4 bytes/token)
	Sealed   bool  // the ctxmmu write-time gate quarantined this part
	Volatile bool  // caller flags known-volatile metadata (timestamp / request id / nonce)
}

ConvPart is one ordered piece of a recorded conversation.

type Derivation 

type Derivation struct {
	Producer     string
	Tool         string
	ArgsDigest   string
	ModelID      string
	TokenizerID  string
	SerializerID string
	PositionMode PositionMode
	SourceRefs   []EntryID
}

Derivation records how an entry was made and which semantic axes must match.

type Entry 

type Entry struct {
	ID         EntryID
	Plane      Plane
	Derivation Derivation
	Validity   Validity
	Security   Security
	Residency  Residency
	Coherence  Coherence
	Metrics    Metrics
	Labels     map[string]string
}

Entry is the metadata record for a cacheable object. It carries enough context to decide whether a hit may be served, but never carries the payload itself.

func FromAttentionIndex 

func FromAttentionIndex(a AttentionIndex, opts ...Option) Entry

FromAttentionIndex lowers a DSA/IndexShare index artifact into the attention_index plane. Consumers name the layers that share this index; ParentKV points at the K/V span whose eviction must invalidate the index too.

func FromContextPage 

func FromContextPage(p ContextPage, opts ...Option) Entry

func FromIntentKey 

func FromIntentKey(k IntentKey, opts ...Option) Entry

FromIntentKey lowers a semantic-intent entry onto the semantic_intent plane. Like a plan template, it is advisory (Defer) and may never directly execute effects (refusal rule 4: a semantic cache may suggest; it may not bypass adjudication).

func FromKVManifest 

func FromKVManifest(m KVManifest, opts ...Option) Entry

FromKVManifest lowers a (verified) manifest into a cachemeta entry on the kv_artifact plane. Callers should prefer CheckResidentClaim for the gating verdict; this helper is the entry shape a sink observes once a claim passes.

func FromKVPrefix 

func FromKVPrefix(p KVPrefix, opts ...Option) Entry

func FromKVTransfer 

func FromKVTransfer(t KVTransfer, opts ...Option) Entry

FromKVTransfer normalizes a live-engine KV residency event into a cache entry on the kv_transfer plane. Residency records where the span now lives (ToTier); the outcome is carried in Labels so an observing sink can separate ok/missed/fault without re-deriving it.

func FromMemoryView 

func FromMemoryView(v MemoryView, opts ...Option) Entry

func FromPlanTemplate 

func FromPlanTemplate(p PlanTemplate, opts ...Option) Entry

FromPlanTemplate lowers an advisory plan template into a cachemeta entry on the plan_template plane. The entry is admitted as Defer (a candidate awaiting re-adjudication), never Allow-as-execution-permit.

func FromProviderCache 

func FromProviderCache(p ProviderCache, opts ...Option) Entry

FromProviderCache folds provider prompt-cache telemetry into a cachemeta entry. The entry lives on the provider plane and marks residency=provider; its metrics carry cached/write tokens so a metrics sink can separate provider savings from local hits. It is intentionally NOT admission-Allow for re-serving: a provider residency is observational, and ProviderCacheVerdict makes the non-serveability mechanical.

func FromRef 

func FromRef(r abi.Ref, opts ...Option) Entry

FromRef describes an abi.Ref as a byte/blob entry. Digest is identity only; the returned Security record preserves the ref's taint/scope but does not pretend that digest alone proves permission.

func FromVDSOKey 

func FromVDSOKey(key string, payload abi.Ref, opts ...Option) (Entry, error)

FromVDSOKey adapts a tier-2 vDSO key plus its payload Ref into a tool-result cache entry. It does not import vdso, keeping the metadata layer below the hot-path implementation.

type EntryID 

type EntryID struct {
	Digest    string
	MediaType MediaType
	Length    int64
	Unit      LengthUnit
}

EntryID is stable identity for a reusable object, independent of residency.

func (EntryID) Valid 

func (id EntryID) Valid() bool

type ExternalInvalidationDirective 

type ExternalInvalidationDirective struct {
	Kind      ExternalInvalidationKind
	Entry     EntryID
	Plane     Plane
	Residency Residency
	Provider  string
	Engine    string
	Reason    string
}

ExternalInvalidationDirective is the provider/engine-facing invalidation plan for a cachemeta entry. cachemeta still never calls an engine API; concrete SGLang/vLLM/llama.cpp adapters translate these directives into their wire calls.

func PlanExternalInvalidations 

func PlanExternalInvalidations(poisonedKV EntryID, entries []Entry) []ExternalInvalidationDirective

PlanExternalInvalidations returns the engine-cache entries that must be dropped when a K/V span is poisoned. It covers the DSA-specific dependency: any attention_index entry whose ParentKV references the poisoned span is invalidated with the K/V. Provider prompt-cache telemetry is deliberately ignored because it is cost-only metadata, not an engine-owned reusable K/V handle.

type ExternalInvalidationKind 

type ExternalInvalidationKind string

ExternalInvalidationKind names the kind of remote-engine cache object that must be dropped when fak has quarantined or refuted a parent K/V span. 

const (
	ExternalInvalidateKVSpan         ExternalInvalidationKind = "kv_span"
	ExternalInvalidateAttentionIndex ExternalInvalidationKind = "attention_index"
)

type IntentCacheRequest 

type IntentCacheRequest struct {
	IntentDigest string
}

IntentCacheRequest is what the current call asks of the intent cache.

type IntentKey 

type IntentKey struct {
	IntentDigest       string
	PrecisionThreshold float64 // cluster precision required to act on a hit
	Precision          float64 // measured precision of this particular match
	Producer           string
	PolicyVersion      string
	Scope              abi.ShareScope
	TTLMillis          int64
}

IntentKey is the field-only shape for a semantic/intent-cache entry. Intent canonicalization fails when keys optimize for generic similarity instead of precision; this record carries a measured precision and a threshold so the lookup can abstain (Structured Intent Canonicalization).

type InvalidationMode 

type InvalidationMode string
const (
	InvalidationNone               InvalidationMode = ""
	InvalidationLRU                InvalidationMode = "lru"
	InvalidationTTL                InvalidationMode = "ttl"
	InvalidationWriteEpoch         InvalidationMode = "write_epoch"
	InvalidationExternalRefutation InvalidationMode = "external_refutation"
	InvalidationPolicy             InvalidationMode = "policy"
)

type KVManifest 

type KVManifest struct {
	SourceDigest       string // digest of the source text the KV was prefilled from
	SpanDigest         string // identity of the KV span
	Tokens             int64  // span length in positions
	ModelID            string
	TokenizerID        string
	AdapterID          string       // LoRA / adapter id ("" = base)
	Precision          string       // "fp16" | "int8" | "fp8" | ...
	PositionConvention PositionMode // how positions were encoded
	Producer           string
	ProducerKeyID      string
	IntegrityChecksum  string // producer-stated checksum over the KV bytes
	Signature          ManifestSignature
}

KVManifest is the self-describing, importable record for a precomputed KV artifact — the "Can I Buy Your KV Cache?" / thaw / market-KV shape. It binds the identity axes a resident span MUST match before reuse (source digest, model, tokenizer, adapter, precision, position convention, producer) plus a producer- stated integrity checksum over the KV bytes and a detached signature over the binding digest. §2.4's gap: no signed/importable KV manifest existed in-tree.

cachemeta never sees the KV bytes; IntegrityChecksum is producer-stated. What a signature covers is ManifestBindingDigest — the metadata binding, recomputable here — so a resident-claim checker can prove the binding was not tampered with without paging in terabytes of KV.

type KVPrefix 

type KVPrefix struct {
	TokenDigest string
	Tokens      []int
	Length      int
	ModelID     string
	TokenizerID string
	Owner       string
}

KVPrefix is the field-only shape a KV-prefix cache adapter lowers into.

type KVTransfer 

type KVTransfer struct {
	Direction    KVTransferDirection
	SpanDigest   string // identity of the KV span being moved/restored/routed
	Tokens       int64  // span length in positions
	ModelID      string
	TokenizerID  string
	PositionMode PositionMode
	FromTier     ResidencyTier
	ToTier       ResidencyTier
	Owner        string
	Lease        string
	Outcome      KVTransferOutcome
	FaultReason  string // free-text when Outcome == fault
	BytesMoved   int64
}

KVTransfer is the field-only shape a live-engine KV-residency adapter lowers into. It describes a residency transition for a KV span, keeping residency tier and owner separate from the payload (§2.2: "residency tier and owner recorded separately from payload").

type KVTransferDirection 

type KVTransferDirection string

KVTransferDirection names a live-engine KV residency event: offload (HBM->DRAM/ disk/remote), restore (a tier re-materializing a span the engine wants), route (a KV-aware router pinning a request to the replica holding the span), or migrate (moving residency between instances). §2.2's gap was that these events were not in the same cache-entry stream as tool/context entries. 

const (
	KVOffload KVTransferDirection = "offload"
	KVRestore KVTransferDirection = "restore"
	KVRoute   KVTransferDirection = "route"
	KVMigrate KVTransferDirection = "migrate"
)

type KVTransferOutcome 

type KVTransferOutcome string

KVTransferOutcome records whether a residency transition succeeded. A restore that found nothing usable is a typed MISS, and a load/restore error is a typed FAULT — never silent recompute (§2.2 parity requirement). 

const (
	KVTransferOK     KVTransferOutcome = "ok"
	KVTransferMissed KVTransferOutcome = "missed"
	KVTransferFault  KVTransferOutcome = "fault"
)

type LayoutLint 

type LayoutLint struct {
	EarliestVolatileSeg  int   // index of the first volatile segment, or -1 if none
	StrandedStableTokens int64 // stable/tool-schema tokens after the earliest volatile segment
	Fixable              bool  // StrandedStableTokens > 0
}

LayoutLint flags the single most impactful fixable ordering bug in one turn: a volatile segment sitting AHEAD of stable/tool-schema content. Everything after the earliest volatile segment is uncacheable purely because of ordering.

func LintPrefixLayout 

func LintPrefixLayout(turn []PromptSegment) LayoutLint

LintPrefixLayout reports the volatile-ahead-of-stable ordering bug for one turn.

type LayoutRecommendation 

type LayoutRecommendation struct {
	Reordered       []PromptSegment // volatile segments hoisted to the tail; others keep original order
	MovedVolatile   int
	BeforeCacheable int64
	AfterCacheable  int64
	PredictedUplift int64
	Changed         bool
}

LayoutRecommendation is the §A3 "recommended layout" output for one turn: the cache-optimal re-ordering plus the predicted cacheable-token uplift.

func RecommendLayout 

func RecommendLayout(turn []PromptSegment) LayoutRecommendation

RecommendLayout produces the cache-optimal re-ordering for one turn: every volatile segment is hoisted to the tail (volatile content is position-independent metadata — a timestamp / request id — so moving it preserves semantics), while every non-volatile segment keeps its original relative order (so conversation messages, tool results, and sealed spans are never reordered among themselves). The predicted uplift is the extra contiguous front-prefix tokens the provider can then cache. A sealed segment still caps the run wherever it sits (refusal rule 3 stays enforced).

type LengthUnit 

type LengthUnit string

LengthUnit says what EntryID.Length counts. 

const (
	UnitBytes     LengthUnit = "bytes"
	UnitTokens    LengthUnit = "tokens"
	UnitPositions LengthUnit = "positions"
)

type LookupKind 

type LookupKind string
const (
	LookupHit        LookupKind = "hit"
	LookupMiss       LookupKind = "miss"
	LookupRevalidate LookupKind = "revalidate"
	LookupTransform  LookupKind = "transform"
	LookupQuarantine LookupKind = "quarantine"
	LookupFault      LookupKind = "fault"
)

type LookupReason 

type LookupReason string
const (
	ReasonNone              LookupReason = ""
	ReasonAbsent            LookupReason = "absent"
	ReasonCold              LookupReason = "cold"
	ReasonStale             LookupReason = "stale"
	ReasonExpiredTTL        LookupReason = "expired_ttl"
	ReasonRefutedWitness    LookupReason = "refuted_witness"
	ReasonScopeDenied       LookupReason = "scope_denied"
	ReasonTaintDenied       LookupReason = "taint_denied"
	ReasonModelMismatch     LookupReason = "model_mismatch"
	ReasonTokenizerMismatch LookupReason = "tokenizer_mismatch"
	ReasonPositionMismatch  LookupReason = "position_mismatch"
	ReasonPolicyMismatch    LookupReason = "policy_mismatch"
	ReasonApproxFault       LookupReason = "approximate_fault"
	ReasonResidencyFault    LookupReason = "residency_fault"
	ReasonRestoreMiss       LookupReason = "restore_miss"
	ReasonManifestMismatch  LookupReason = "manifest_mismatch"
	ReasonUnsignedArtifact  LookupReason = "unsigned_artifact"
	ReasonIndexMismatch     LookupReason = "index_mismatch"
	ReasonNonCausalIndex    LookupReason = "non_causal_index"
)

type LookupVerdict 

type LookupVerdict struct {
	Kind   LookupKind
	Reason LookupReason
	Entry  Entry
	Handle EntryID
	Meta   map[string]string
}

LookupVerdict is the typed result of asking whether an entry may be reused.

func AttentionIndexLookup 

func AttentionIndexLookup(req AttentionIndexRequest, candidate AttentionIndex) LookupVerdict

AttentionIndexLookup checks whether a candidate DSA index may serve a request. It is deliberately stricter than a plain KV-prefix lookup: both the token prefix and the computed decision digest must match, and non-causal candidates fault by default.

func CheckResidentClaim 

func CheckResidentClaim(claim ResidentClaim, manifest KVManifest) LookupVerdict

CheckResidentClaim decides whether a resident KV span may be reused as the performance material its manifest describes. It is FAULT (not silent recompute) when the binding disagrees or the signature is unverified, and HIT only when every binding axis matches AND the signature was verified. A hit is fleet-scoped, model-bound prefill material — never semantic proof (§2.4).

func Fault 

func Fault(e Entry, reason LookupReason) LookupVerdict

func Hit 

func Hit(e Entry) LookupVerdict

func IntentKeyLookup 

func IntentKeyLookup(req IntentCacheRequest, k IntentKey) LookupVerdict

IntentKeyLookup is the abstaining verdict for semantic-intent reuse. It HITs only on an exact intent digest AND precision at/above threshold; otherwise it abstains (MISS with approximate_fault for a sub-threshold near match, or absent for a digest mismatch). Abstention is the safe default — a false positive executes the wrong cached answer.

func KVTransferVerdict 

func KVTransferVerdict(e Entry) LookupVerdict

KVTransferVerdict turns a transfer entry's recorded outcome into a typed lookup verdict: fault -> FAULT (residency_fault), missed -> MISS (restore_miss), ok -> HIT. This is the §2.2 guarantee that a failed restore is never silent recompute.

func Miss 

func Miss(reason LookupReason) LookupVerdict

func PlanTemplateLookup 

func PlanTemplateLookup(req PlanCacheRequest, tpl PlanTemplate) LookupVerdict

PlanTemplateLookup is the abstaining verdict for plan-template reuse (Step 5):

  • exact task class + params + schema + tool manifest + policy, WITH a present state witness -> HIT (an advisory candidate; must re-enter plancfi).
  • exact binding but no state witness -> REVALIDATE (stale state).
  • any binding axis mismatch -> MISS.

A HIT is never permission to execute: the returned entry carries AdmissionDefer and the verdict Meta marks must_reenter_plancfi=true.

func ProviderCacheVerdict 

func ProviderCacheVerdict(e Entry) LookupVerdict

ProviderCacheVerdict is the typed answer to "may this provider cache entry be re-served as a local hit?": never. It returns a Transform verdict (non-serveable by CanServe) whose Meta marks the entry as cost/latency evidence only, so the refusal rule is enforced in code rather than relied upon in prose.

func Quarantine 

func Quarantine(e Entry, reason LookupReason) LookupVerdict

func Revalidate 

func Revalidate(e Entry, reason LookupReason) LookupVerdict

func Transform 

func Transform(e Entry, reason LookupReason) LookupVerdict

func (LookupVerdict) CanServe 

func (v LookupVerdict) CanServe() bool

type ManifestSignature 

type ManifestSignature struct {
	Algorithm string // "ed25519" | "hmac-sha256" | "none" | ""
	Value     string // hex-encoded signature
}

ManifestSignature is a detached signature over ManifestBindingDigest. The algorithm is named (not mandated) so tier-1 stays crypto-scheme-free; the integrator performs the actual verification and reports SignatureVerified on the resident claim.

type MediaType 

type MediaType string

MediaType names the physical shape of a reusable payload. 

const (
	MediaBytes          MediaType = "bytes"
	MediaTokenIDs       MediaType = "token_ids"
	MediaKVSpan         MediaType = "kv_span"
	MediaPromptPrefix   MediaType = "prompt_prefix"
	MediaRecallPage     MediaType = "recall_page"
	MediaMemoryView     MediaType = "memory_view"
	MediaPlanTemplate   MediaType = "plan_template"
	MediaIntentKey      MediaType = "intent_key"
	MediaAttentionIndex MediaType = "attention_index"
)

type MemoryView 

type MemoryView struct {
	ViewID            string
	ViewType          string
	Digest            string
	Length            int64
	SourceRefs        []EntryID
	Producer          string
	PolicyVersion     string
	Scope             abi.ShareScope
	Taint             abi.TaintLabel
	Coverage          float64
	FaithfulnessProbe float64
	Witness           string
	TTLMillis         int64
}

MemoryView is the field-only shape for a derived context view. A view is a recomputable artifact over source pages/entries, not a replacement for raw memory.

type Metrics 

type Metrics struct {
	Hits               uint64
	Misses             uint64
	Fills              uint64
	Evictions          uint64
	PrefillTokensSaved int64
	BytesTransferred   int64
	FalseHitFaults     uint64
	QualityDeltaProbe  float64
	Coverage           float64
	FaithfulnessProbe  float64
}

Metrics are counters or probes associated with a cache entry. A zero value is simply "not yet observed".

type Option 

type Option func(*Entry)

Option mutates an Entry during adapter construction.

func WithAdmission 

func WithAdmission(v AdmissionVerdict, by string) Option

func WithConsumer 

func WithConsumer(c Consumer) Option

func WithEpoch 

func WithEpoch(epoch string) Option

func WithLabel 

func WithLabel(k, v string) Option

func WithModel 

func WithModel(modelID, tokenizerID string) Option

func WithParent 

func WithParent(id EntryID) Option

func WithPolicyVersion 

func WithPolicyVersion(v string) Option

func WithPositionMode 

func WithPositionMode(m PositionMode) Option

func WithResidency 

func WithResidency(t ResidencyTier, owner, lease string) Option

func WithSerializer 

func WithSerializer(id string) Option

func WithTTLMillis 

func WithTTLMillis(ms int64) Option

func WithTrustEpoch 

func WithTrustEpoch(epoch uint64) Option

func WithWitness 

func WithWitness(w string) Option

type PlanCacheRequest 

type PlanCacheRequest struct {
	TaskClass          string
	ParamsDigest       string
	PlanSchemaDigest   string
	ToolManifestDigest string
	PolicyVersion      string
	StateWitness       string // "" => current state/witness missing => REVALIDATE, not HIT
}

PlanCacheRequest is what the current task asks of the plan-template cache.

type PlanTemplate 

type PlanTemplate struct {
	TaskClass          string
	ParamsDigest       string
	PlanSchemaDigest   string
	ToolManifestDigest string
	PolicyVersion      string
	Steps              []string // candidate tool graph (advisory; not an execution permit)
	Producer           string
	TTLMillis          int64
	Scope              abi.ShareScope
}

PlanTemplate is the field-only shape for an advisory, reusable plan-template cache entry (Agentic Plan Caching). A template is keyed by task class, parameter digest, plan-schema digest, tool-manifest digest, and policy version. §2.6's gap: no PlanePlanTemplate / intent-key cache existed yet, and the first version must be read-only/advisory and abstain aggressively.

A cached plan is NEVER an execution permit (refusal rule 5): a HIT yields a candidate that must re-enter plancfi/adjudication before any tool effect. That is encoded mechanically via AdmissionDefer + the must_reenter_plancfi Meta flag.

type Plane 

type Plane string

Plane names the cache plane that produced or serves an entry. 

const (
	PlaneBlob           Plane = "blob"
	PlaneToolResult     Plane = "tool_result"
	PlaneContextPage    Plane = "context_page"
	PlaneKVPrefix       Plane = "kv_prefix"
	PlaneKVArtifact     Plane = "kv_artifact"
	PlaneKVTransfer     Plane = "kv_transfer"
	PlanePrompt         Plane = "prompt_prefix"
	PlanePolicy         Plane = "policy"
	PlaneProvider       Plane = "provider"
	PlanePlanTemplate   Plane = "plan_template"
	PlaneSemanticIntent Plane = "semantic_intent"
	PlaneMemoryView     Plane = "memory_view"
	PlaneAttentionIndex Plane = "attention_index"
)

type PositionMode 

type PositionMode string

PositionMode describes whether cached token/KV material can be relocated. 

const (
	PositionUnknown           PositionMode = ""
	PositionPrefixAligned     PositionMode = "prefix_aligned"
	PositionRelocatable       PositionMode = "relocatable"
	PositionRecomputeRequired PositionMode = "recompute_required"
)

type PrefixBreakDirective 

type PrefixBreakDirective struct {
	Break        bool
	RefutedKeys  []string      // witnesses whose current value diverged or is unconfirmable
	BreakAtToken int64         // token offset of the earliest stale span
	Marker       PromptSegment // the volatile marker to inject ahead of the stale span
	Reason       string
}

PrefixBreakDirective is the typed coherence answer for the next GLM turn.

func EvaluatePrefixCoherence 

func EvaluatePrefixCoherence(deps []PrefixDependency, current map[string]string) PrefixBreakDirective

EvaluatePrefixCoherence checks a provider-cached prefix's dependencies against the current world (witness-key -> current value). A dependency is REFUTED when its current value differs from the recorded value OR is absent — fail-closed: an unconfirmable witness is treated as stale, because a coherence layer must never serve a prefix it cannot prove fresh. When any dependency is refuted the directive breaks at the EARLIEST refuted span and supplies a volatile marker derived from the refuted (key,newValue) pairs: deterministic for a given refutation, but guaranteed to differ from the cached prefix so the provider cannot serve the stale span.

func EvaluatePrefixCoherenceRevoked 

func EvaluatePrefixCoherenceRevoked(deps []PrefixDependency, revoked func(witness string) bool) PrefixBreakDirective

EvaluatePrefixCoherenceRevoked is the REVOCATION-PREDICATE form of the coherence check — the shape that wires directly to the live vdso / gateway revocation bus. A dependency is refuted when `revoked(witness)` reports its trust witness has been revoked (the recall layer's Page.Witness + vdso.Default.Revoked model). This is what the live OpenAI-proxy path uses; EvaluatePrefixCoherence is the value-comparison form for offline transcript analysis. Both break at the earliest refuted span with a world-sensitive volatile marker. A nil predicate refutes nothing (fail-OPEN is the caller's explicit choice when there is no revocation bus to consult).

func EvaluateSegmentCoherence 

func EvaluateSegmentCoherence(segs []PromptSegment, revoked func(witness string) bool) PrefixBreakDirective

EvaluateSegmentCoherence is the SEGMENT-LEVEL §A4 check — the form that dissolves the page-vs-prompt token-coordinate problem by carrying the trust witness ON each segment (PromptSegment.Witness) instead of in a separate offset-indexed deps list. It refutes every segment whose witness is revoked and breaks at the earliest one (its cumulative token offset). This is the form the LIVE proxy uses: when converting request messages to segments, attach each segment's witness from the recorded page that produced its content, then call this — no coordinate alignment between two byte sources required.

type PrefixDependency 

type PrefixDependency struct {
	Witness    string // "git_sha:path" | "blob_hash:id" | "lease_epoch:id"
	Value      string // value witnessed when the prefix was built
	TokenStart int64
}

PrefixDependency ties a span of a provider-cached prefix to a world witness it depends on. TokenStart is the token offset where the dependent span begins.

type PromptSegment 

type PromptSegment struct {
	Kind    SegmentKind
	Tokens  int64
	Content []byte
	// Witness is the OPTIONAL external trust witness this segment's content depends on
	// (a git SHA / blob hash / lease epoch carried from the recorded page that produced
	// it). It lets §A4 break the prefix at the SEGMENT level when the witness is revoked,
	// avoiding any page-vs-prompt token-coordinate alignment — the witness travels with
	// the segment. Empty for segments with no external dependency. Ignored by the §A3
	// prefix-matching math (which compares only Content).
	Witness string
}

PromptSegment is one ordered piece of a turn's prompt. Content is the exact serialized bytes the provider hashes for prefix matching; Tokens is the count the provider bills for the segment.

func InjectBreakMarker 

func InjectBreakMarker(turn []PromptSegment, d PrefixBreakDirective) []PromptSegment

InjectBreakMarker APPLIES a PrefixBreakDirective to a turn's segments: it inserts the volatile break marker immediately AHEAD of the stale span (the first segment whose cumulative start offset reaches BreakAtToken), so the provider cache misses the stale prefix while the fresh prefix before the break still hits. A non-break directive returns the turn unchanged. This is the actionable output a live gateway / OpenAI proxy applies to the next GLM request after a world witness is refuted — the bridge between the A4 decision and the wire.

func SegmentsFromParts 

func SegmentsFromParts(parts []ConvPart) []PromptSegment

SegmentsFromParts maps one turn's ordered parts into the PromptSegment list A3 analyzes, wiring the ctxmmu seal decision into SegSealed.

type ProviderCache 

type ProviderCache struct {
	Provider       string // "openai" | "anthropic" | "gemini" | "bedrock"
	ModelID        string
	CachedTokens   int64  // cache-read tokens reported by the provider
	WriteTokens    int64  // cache-write/create tokens
	PromptTokens   int64  // total prompt tokens the prefix covers
	SerializerID   string // prompt serializer hash (deterministic serialization)
	BreakpointMode string // "auto" | "explicit" | "implicit" | ""
	Retention      string // "5m" | "1h" | ttl/retention mode where known
	FirstDivergeAt int64  // offline first-divergence token offset (<=0 = unknown)
	Owner          string

	// Endpoint and ReasoningMode are GLM-5.2 (Z.AI) Vary axes per
	// GLM52-HOSTED-CACHE-COHERENCE-2026-06-19.md §A2: the Coding-Plan vs general
	// endpoint and the reasoning_effort/thinking toggle are SILENT cache-breakers.
	// Folding them into the entry identity records a mode/endpoint switch as a
	// distinct provider-prefix cache-write rather than an invisible miss, so a
	// metrics sink does not blend two different request shapes into one hit rate.
	// They are additive and provider-agnostic (empty = no axis contributed).
	Endpoint      string // "general" | "coding" | upstream endpoint label
	ReasoningMode string // "max" | "enabled" | "disabled" | reasoning_effort/thinking label
}

ProviderCache is the field-only shape a provider-usage adapter lowers into. A provider prompt-cache event is COST/LATENCY telemetry about a prefix the remote engine kept resident — it is never authority that a local result may be re-served (refusal rule 6: "provider prompt-cache hit treated as trust evidence"). This record exists so fleet benchmarks cannot accidentally count provider savings as local wins; the cachemeta plane for it is plane=provider, residency=provider.

type Residency 

type Residency struct {
	Tier  ResidencyTier
	Owner string
	Lease string
}

Residency records where the payload currently lives. It is advisory metadata; the package does not fetch or store the payload.

type ResidencyTier 

type ResidencyTier string
const (
	TierUnknown   ResidencyTier = ""
	TierHBM       ResidencyTier = "hbm"
	TierDRAM      ResidencyTier = "dram"
	TierDisk      ResidencyTier = "disk"
	TierRemote    ResidencyTier = "remote"
	TierProvider  ResidencyTier = "provider"
	TierRecompute ResidencyTier = "recompute"
)

type ResidentClaim 

type ResidentClaim struct {
	ModelID            string
	TokenizerID        string
	AdapterID          string
	Precision          string
	PositionConvention PositionMode
	Producer           string
	SpanDigest         string
	Tokens             int64
	IntegrityChecksum  string
	SignatureVerified  bool // integrator verified manifest.Signature over ManifestBindingDigest
}

ResidentClaim is what a resident KV span PURPORTS to be. The integrator resolves the resident span's declared axes and performs the signature verification, then hands the claim to CheckResidentClaim. Refusal rule 8: a KV artifact imported from digest alone is refused — model/tokenizer/position/producer AND a verified signature are all required.

type SavingsSplit 

type SavingsSplit struct {
	LocalReuseTokens   int64 // tokens re-served by a fak-local cache (a real local win)
	ProviderReadTokens int64 // provider-reported cached tokens (cost telemetry, NOT a local win)
	ProviderHits       int64 // count of provider prompt-prefix hits observed
}

SavingsSplit partitions a stream of cache entries into local-reuse tokens and provider-cache tokens with no double counting: every entry contributes to at most one side. A benchmark folds its observed entries through this to get the two totals it may report — a local reuse win and a (separately-labeled) provider cost saving — without ever conflating them.

func (*SavingsSplit) Add 

func (s *SavingsSplit) Add(e Entry)

Add folds one entry into the split, honoring the double-count guard. A provider-resident entry's tokens land only in ProviderReadTokens; a locally-resident entry's tokens land only in LocalReuseTokens.

type Security 

type Security struct {
	Taint            abi.TaintLabel
	Scope            abi.ShareScope
	AdmissionVerdict AdmissionVerdict
	AdmittedBy       string
	Reason           string
}

Security carries the authority and admission claim for serving an entry.

type SegmentKind 

type SegmentKind string

SegmentKind classifies a prompt part for layout advice. Only SegSealed changes the divergence math (it stops the cacheable prefix); the rest inform the lint. 

const (
	SegStable     SegmentKind = "stable"      // system prompt, static instructions — should be byte-identical every turn
	SegToolSchema SegmentKind = "tool_schema" // tool/function definitions — stable, belongs in the prefix
	SegVolatile   SegmentKind = "volatile"    // timestamp, request id, nonce — known to change every turn
	SegToolResult SegmentKind = "tool_result" // an inbound tool result — stable once appended, but tail content
	SegMessage    SegmentKind = "message"     // a conversation message — tail content
	SegSealed     SegmentKind = "sealed"      // a span fak quarantined — MUST NOT be re-served via the provider cache
)

type StabilityReport 

type StabilityReport struct {
	Turns             int
	CacheableTokens   int64
	LostTokens        int64
	BrokeAtTurn       int   // first turn (>=1) whose prefix diverged within the shared span; -1 if never
	RecoverableTokens int64 // sum of LintPrefixLayout.StrandedStableTokens — predicted reorder uplift
}

StabilityReport rolls a recorded session (one prompt per turn) into the §A3 headline: how many provider-cacheable tokens survive across the session, how many are re-billed, and the SPECIFIC turn where the prefix first broke.

func AnalyzeStability 

func AnalyzeStability(turns [][]PromptSegment) StabilityReport

AnalyzeStability computes the §A3 report over an ordered list of turns (each turn is the full serialized prompt for that request).

type TurnDivergence 

type TurnDivergence struct {
	// FirstDivergeSeg is the index into `next` of the first segment that is NOT part of
	// the cacheable common prefix (a content mismatch, a length overrun, or a sealed
	// segment). It equals len(next) when every segment of next is a cacheable
	// continuation of prev (a pure append — the whole overlap hit).
	FirstDivergeSeg int
	// StableTokens is the provider-cacheable prefix length in tokens. This is the
	// FirstDivergeAt token offset the §A2 ProviderCache entry records.
	StableTokens int64
	// LostTokens is next's prompt tokens at/after the break — re-billed at full price.
	LostTokens int64
	// Identical is true when next is byte-identical to prev.
	Identical bool
	// SealedStop is true when the cacheable prefix was cut short by a sealed segment
	// rather than a content divergence (refusal rule 3 forbids re-serving it).
	SealedStop bool
}

TurnDivergence reports where turn `next`'s prompt prefix stops matching turn `prev`'s, and the provider-cache consequence in billed tokens.

func Diverge 

func Diverge(prev, next []PromptSegment) TurnDivergence

Diverge computes the cacheable common prefix between two consecutive turns' prompts. It walks segments in order: while next[i] is byte-identical to prev[i] AND not sealed, the segment's tokens stay cacheable; the first content mismatch, length overrun, or sealed segment ends the cacheable prefix. A sealed segment stops the prefix even when its bytes match (refusal rule 3).

func (TurnDivergence) FirstDivergeTokenOffset 

func (d TurnDivergence) FirstDivergeTokenOffset() int64

FirstDivergeTokenOffset is the token offset where the provider prefix first breaks — exactly the value the §A2 ProviderCache.FirstDivergeAt field carries. It returns 0 when the whole prompt is cacheable (no divergence in next's span).

type VDSOKey 

type VDSOKey struct {
	Tool       string
	ArgsDigest string
	EpochStamp string
}

VDSOKey is the parsed form of vDSO's tier-2 key: tool:args-digest:epoch-stamp.

func ParseVDSOKey 

func ParseVDSOKey(key string) (VDSOKey, error)

type Validity 

type Validity struct {
	Witness         string
	AdmittedAtEpoch string
	TrustEpoch      uint64
	TTLMillis       int64
	PolicyVersion   string
}

Validity names the witness and epochs that bound freshness/integrity.

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.