fhelium.residency.model

Logical value identities and storage specifications for residency management.

This module defines tensor-free handles, immutable specifications, and the synchronous reconstruction requirements used by ResidencyManager to validate managed values, replica behavior, recoverability, and storage charges.

Recoverability

class View source

Recoverability()

Bases: StrEnum

Whether a managed value may lose its final materialization.

Attributes

Name	Type	Default/value
RECONSTRUCTIBLE		'reconstructible'
MUST_PRESERVE		'must-preserve'

ReplicaMode

class View source

ReplicaMode()

Bases: StrEnum

Constraint on simultaneous materializations of one managed value.

Attributes

Name	Type	Default/value
REPLICABLE		'replicable'
EXCLUSIVE		'exclusive'

ResidencyHandle

class View source

ResidencyHandle(manager_id: str, handle_id: str, value_type: type[ValueT_co])

Bases: Generic[ValueT_co]

Manager-issued tensor-free identity of one typed managed value.

Handles are immutable and hashable, and therefore remain valid dictionary keys independently of every materialization's device and lifetime. The value_type field preserves the expected runtime class without retaining a tensor-bearing value. manager_id prevents accidental cross-manager use, while handle_id is an opaque identity generated for each ResidencyManager.adopt or ResidencyManager.register_source call. Moving, copying, or dropping a materialization does not change the handle.

Parameters

• manager_id: Non-empty identity of the manager that issued the handle.
• handle_id: Non-empty opaque identity generated by the manager.
• value_type: Expected concrete or base TensorResident runtime class.

Attributes

Name	Type	Default/value
manager_id	str
handle_id	str
value_type	type[ValueT_co]

ResidencySource

class View source

ResidencySource()

Bases: Protocol[ValueT_co]

Synchronous reconstruction source for one exact managed value.

Sources are registered directly with residency state and return a ready TensorResident value when invoked. The manager validates its runtime type, byte accounting, and initial location. The source is trusted to return the exact contents and CKKS state registered for that handle; the source owns content-identity correctness. Each call must return independent tensor storage whose logical alias ownership transfers to the manager; a source must not retain or later mutate the returned materialization.

load

method

def load() -> ValueT_co: ...

Synchronously reconstruct and return the exact registered value.

ResidencyValueSpec

class View source

ResidencyValueSpec(value_type: type[ValueT_co], logical_nbytes: int, storage_nbytes: int, replica_mode: ReplicaMode, recoverability: Recoverability)

Bases: Generic[ValueT_co]

Immutable storage specification for one managed value.

logical_nbytes is the value's tensor payload size, while storage_nbytes is the fixed conservative charge used for each physical residency admission. A moved view may use less actual backing storage but may not exceed this registered ceiling; accounting still debits the full charge. This model requires the storage charge to be at least the logical payload size. Implementations with overlapping tensor views must therefore charge the full logical extent rather than deduct shared backing storage; this conservative rule makes admission accounting independent of alias analysis.

Parameters

• value_type: Expected TensorResident runtime class.
• logical_nbytes: Non-negative logical tensor payload bytes.
• storage_nbytes: Non-negative physical residency charge, greater than or equal to logical_nbytes.
• replica_mode: Whether simultaneous replicas are permitted.
• recoverability: Whether the final materialization may be discarded.

Attributes

Name	Type	Default/value
value_type	type[ValueT_co]
logical_nbytes	int
storage_nbytes	int
replica_mode	ReplicaMode
recoverability	Recoverability