fhelium.residency.controller

Inspectable deterministic automation over explicit residency mechanisms.

A controller owns no tensor materializations. It decides state-bound placement from declarative requests and delegates all validation, copying, accounting, and lifetime enforcement to one ResidencyManager.

ResidencyController

class View source

ResidencyController(manager: ResidencyManager, *, policy: ResidencyPolicy | None=None, search_state_limit: int=100000)

Deterministic optional automation bound to one residency manager.

The manager remains the only materialization owner and transition executor. This controller stores only policy metadata and logical access epochs. It decides only when called, emits an inspectable decision, and never runs background eviction, waits for protected victims, retries a failed source, rolls back completed actions, or silently replans a stale decision.

manager

property

manager: ResidencyManager

The sole state and materialization authority used by this controller.

policy

property

policy: ResidencyPolicy

Pure policy used to rank invariant-filtered candidates.

set_policy_metadata

method

def set_policy_metadata(handle: ResidencyHandle[Any], *, priority: int=0, stable_key: str | None=None) -> None: ...

Set controller-local eviction metadata for one known handle.

decide

method

def decide(request: ResidencyRequest) -> ResidencyDecision: ...

Derive an inspectable decision without executing residency actions.

scope

method

def scope(decision: ResidencyDecision, *, transfer_streams: TransferStreams | None=None) -> ResidencyScope: ...

Return a scope that version-checks and commits decision on entry.

use

method

def use(request: ResidencyRequest, *, consumer_streams: ConsumerStreams | None=None, transfer_streams: TransferStreams | None=None) -> ResidencyUse: ...

Return a context that derives, admits, and borrows one decision.

Values remain cached after the use scope. Later admission may reclaim them under policy. No exit eviction, hidden synchronization, or background work is performed.

ResidencyDecision

class View source

ResidencyDecision(manager_id: str, expected_state_version: int, explored_states: int, request: ResidencyRequest, plan: ResidencyPlan, policy_name: str, policy_config: tuple[tuple[str, object], ...], evictions: tuple[ResidencyEviction, ...], explanation: ResidencyPlanExplanation)

Immutable state-bound result of automatic residency decision-making.

A decision is valid only for the issuing manager at expected_state_version. It is process-local evidence, not a serialized or distributed execution artifact. Entering the associated manager scope atomically rechecks the version before any reclaim action or reservation.

Attributes

Name	Type	Default/value
manager_id	str
expected_state_version	int
explored_states	int
request	ResidencyRequest
plan	ResidencyPlan
policy_name	str
policy_config	tuple[tuple[str, object], ...]
evictions	tuple[ResidencyEviction, ...]
explanation	ResidencyPlanExplanation

ResidencyEviction

class View source

ResidencyEviction(action: DropResident[TensorResident] | MoveResident[TensorResident], rank: int, released_location: ResidencyLocation, released_nbytes: int, reason: str)

One controller-selected reclaim action and its policy evidence.

Attributes

Name	Type	Default/value
action	DropResident[TensorResident] | MoveResident[TensorResident]
rank	int
released_location	ResidencyLocation
released_nbytes	int
reason	str

ResidencyUse

class View source

ResidencyUse(*, controller: ResidencyController, request: ResidencyRequest, consumer_streams: ConsumerStreams | None, transfer_streams: TransferStreams | None)

Single-use automatic admission, borrow, and reservation lifetime.

decision

property

decision: ResidencyDecision

State-bound decision after successful context entry.

values

property

values: Mapping[ResidencyRequirement, TensorResident]

Borrowed values keyed by exact requirement during this context.

value

method

def value(handle: ResidencyHandle[Any], *, at: ResidencyLocation) -> TensorResident: ...

Return the borrow for one exact (handle, location) endpoint.

report

property

report: ResidencyPlanReport | None

Completed plan report after successful scope close.

exit_error

property

exit_error: BaseException | None

Structured plan cleanup failure retained by the underlying scope.