fhelium.residency.policy

Pure deterministic policy inputs and built-in eviction ordering.

Policies receive only frozen tensor-free candidates that have already passed manager-invariant filtering. They rank candidates and expose configured fallback tiers; they never inspect concrete values or execute residency actions.

DeterministicTieredLRU

class View source

DeterministicTieredLRU(fallback_tiers: Mapping[ResidencyLocation, Sequence[ResidencyLocation]] | None=None)

Deterministic priority-aware LRU ordering over configured tier edges.

Fallback locations are never inferred. An omitted source location has no spill path. Candidate order is lower priority, then older access epoch, then application stable key or manager registration order. Wall-clock time, UUID text, allocator free-memory readings, and random state are not inputs.

name

property

name: str

Stable diagnostic policy name.

config_identity

property

config_identity: tuple[tuple[str, object], ...]

Frozen fallback-tier configuration recorded in decisions.

fallback_locations

method

def fallback_locations(location: ResidencyLocation) -> tuple[ResidencyLocation, ...]: ...

Return configured destinations in caller-specified order.

order_candidates

method

def order_candidates(candidates: Sequence[ResidencyEvictionCandidate]) -> tuple[ResidencyEvictionCandidate, ...]: ...

Rank candidates without observing or mutating manager state.

ResidencyEvictionCandidate

class View source

ResidencyEvictionCandidate(handle: ResidencyHandle[Any], location: ResidencyLocation, charged_nbytes: int, registration_index: int, last_access_epoch: int | None, metadata: ResidencyPolicyMetadata)

One invariant-filtered materialization eligible for policy ranking.

Attributes

Name	Type	Default/value
handle	ResidencyHandle[Any]
location	ResidencyLocation
charged_nbytes	int
registration_index	int
last_access_epoch	int | None
metadata	ResidencyPolicyMetadata

ResidencyPolicy

class View source

ResidencyPolicy()

Bases: Protocol

Pure deterministic policy interface used by a residency controller.

name

property

name: str

Stable diagnostic policy name.

config_identity

property

config_identity: tuple[tuple[str, object], ...]

Frozen tensor-free configuration evidence for decisions.

fallback_locations

method

def fallback_locations(location: ResidencyLocation) -> tuple[ResidencyLocation, ...]: ...

Return configured spill tiers for location.

order_candidates

method

def order_candidates(candidates: Sequence[ResidencyEvictionCandidate]) -> tuple[ResidencyEvictionCandidate, ...]: ...

Return every supplied candidate in deterministic eviction order.

ResidencyPolicyMetadata

class View source

ResidencyPolicyMetadata(priority: int = 0, stable_key: str | None = None)

Controller-owned eviction hints for one manager handle.

Higher priority values retain a value before lower-priority values. stable_key is an optional application-stable tie breaker and diagnostic identity. Neither field changes logical value identity or manager ownership.

Attributes

Name	Type	Default/value
priority	int	0
stable_key	str | None	None