adk_context_cache (erlang_adk v0.7.0)

View Source

Owner-bound registry for provider-managed model-request prefix caches.

Entries are scoped by application, user, model, policy, provider, prefix, and TTL policy. Concurrent misses for the same key use one provider create operation. Provider resource names remain private behind runtime leases; public results contain only versioned, JSON-safe lifecycle and telemetry metadata. This module never stores or returns a model response.

Summary

Types

lease/0
policy/0

Functions

acquire(Cache, Provider, Scope, Prefix, Opts)

Acquire or create a private prefix-cache lease.

capabilities()
code_change(OldVersion, State, Extra)
compile(Opts)
handle_call(Request, From, State0)
handle_cast(Message, State)
handle_info(Message, State0)
init(_)
invalidate(Cache, Provider, Scope)

Invalidate all entries and in-flight creates for one provider scope.

invalidate(Cache, Provider, Scope, Prefix)

Invalidate one provider scope and sanitized prefix, across TTLs.

invalidate_scope(Cache, Provider, Scope, Opts)

Invalidate one exact provider scope with an absolute deadline.

resolve(Cache, Lease)

Resolve a lease for immediate provider-adapter use.

scope_status(Cache, Provider, Scope, Opts)

Return content-free lifecycle counts for one exact provider scope.

start(Opts)
start_link(Opts)
status(Cache)
stop(Cache)
terminate(Reason, State)
version()

Types

lease/0

-type lease() :: {adk_context_cache_lease, pid(), binary(), pos_integer()}.

policy/0

-type policy() :: map().

Functions

acquire(Cache, Provider, Scope, Prefix, Opts)

-spec acquire(pid(), module(), map(), map(), map()) ->
                 {ok, lease(), map()} | {bypass, map()} | {error, term()}.

Acquire or create a private prefix-cache lease.

Scope must contain exactly app, user, model, and policy. Prefix is secret-pruned before hashing or provider delivery. Options are ttl_ms, an absolute monotonic deadline_ms, and optional provider estimated_tokens.

capabilities()

-spec capabilities() -> map().

code_change(OldVersion, State, Extra)

compile(Opts)

-spec compile(map()) -> {ok, policy()} | {error, term()}.

handle_call(Request, From, State0)

handle_cast(Message, State)

handle_info(Message, State0)

init(_)

invalidate(Cache, Provider, Scope)

-spec invalidate(pid(), module(), map()) -> {ok, map()} | {error, term()}.

Invalidate all entries and in-flight creates for one provider scope.

invalidate(Cache, Provider, Scope, Prefix)

-spec invalidate(pid(), module(), map(), map()) -> {ok, map()} | {error, term()}.

Invalidate one provider scope and sanitized prefix, across TTLs.

invalidate_scope(Cache, Provider, Scope, Opts)

-spec invalidate_scope(pid(), module(), map(), map()) -> {ok, map()} | {error, term()}.

Invalidate one exact provider scope with an absolute deadline.

This is intentionally distinct from the compatibility invalidate/3 API so checked administrative callers can fail closed if a queued request reaches the registry after its authorization window has expired.

resolve(Cache, Lease)

-spec resolve(pid(), lease()) -> {ok, binary()} | {error, term()}.

Resolve a lease for immediate provider-adapter use.

The returned resource name is runtime-private and must never be persisted in events, telemetry, logs, checkpoints, or developer API results.

scope_status(Cache, Provider, Scope, Opts)

-spec scope_status(pid(), module(), map(), map()) -> {ok, map()} | {error, term()}.

Return content-free lifecycle counts for one exact provider scope.

Filtering stays inside the private registry. The result never includes a cache pid, lease, provider resource name, prefix, policy value, or credential. deadline_ms is an absolute monotonic deadline and is checked again by the registry before it examines its entries.

start(Opts)

-spec start(map()) -> {ok, pid()} | {error, term()}.

start_link(Opts)

-spec start_link(map()) -> {ok, pid()} | {error, term()}.

status(Cache)

-spec status(pid()) -> {ok, map()}.

stop(Cache)

-spec stop(pid()) -> ok.

terminate(Reason, State)

version()

-spec version() -> pos_integer().