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 eligible candidates and expose configured fallback tiers for controller decisions.
DeterministicTieredLRU
class View source
DeterministicTieredLRU(fallback_tiers: Mapping[ResidencyLocation, Sequence[ResidencyLocation]] | None=None)Rank eviction candidates by priority and logical recency over configured fallback tiers.
Candidates are ordered by lower priority, older access epoch, then application stable key or manager registration order. The configured edges determine available spill paths; a source with no edge has no spill destination.
name
property
name: strStable 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: strStable 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 |