FHElium

Appearance

fhelium.artifacts.store ​

Transactional local artifact catalog built on exact value serialization.

T ​

constant View source

python
T = TypeVar('T', bound=TensorResident)

U ​

constant View source

python
U = TypeVar('U', bound=TensorResident)

ArtifactStore ​

class View source

python
ArtifactStore(root: str | os.PathLike[str])

Store one active exact-value generation per local logical name.

SQLite owns the namespace, metadata transaction, stale-generation checks, and process concurrency. Immutable safetensors files under objects/ own the large tensor payloads. A writer makes a new payload durable before its catalog row commits; a crash can therefore leave only unreachable temporary or orphan files, never a committed row pointing to a partially written payload. Store opening removes such unreachable files under an exclusive catalog transaction.

Readers retain one rollback-journal read transaction through payload validation and reconstruction. Writer commit consequently waits for active readers before an overwritten or deleted payload is removed. Writers are serialized by SQLite. overwrite=True publishes the last successfully committed generation and makes every older ArtifactRef stale.

Version 1 requires SQLite 3.37 or later and supports one trusted host on a local POSIX filesystem with ordinary SQLite locking, same-filesystem publication, and file/directory fsync. NFS, SMB, FUSE/object-store mounts, multi-host access, hostile writers that bypass this API, encryption at rest, and authenticated integrity are not supported. The SHA-256 digest detects accidental payload corruption but an attacker able to modify both catalog and payload can replace both.

Parameters

  • root: Local directory that owns the catalog and immutable payloads. A missing or empty directory is initialized. A non-empty directory without a recognized catalog is rejected rather than migrated.

collection ​

method

python
def collection(name: str) -> ArtifactCollection: ...

Return a logical namespace view rooted at name.

put ​

method

python
def put(name: str, value: T, *, sensitivity: ArtifactSensitivity | None=None, allow_secret: bool=False, overwrite: bool=False) -> ArtifactRef[T]: ...

Persist and atomically publish a new active generation.

A writer transaction spans staging and catalog publication. Existing readers may continue loading the previous immutable payload; commit waits for them before that payload becomes eligible for removal. Publication snapshots the supported exact value state but does not move, mutate, offload, or release the caller's live value.

Parameters

  • name: Normalized store-relative logical name.
  • value: Exact tensor-resident FHElium value.
  • sensitivity: Descriptive public/confidential/secret label. It does not provide encryption or access control.
  • allow_secret: Explicitly permit unencrypted SecretKey persistence.
  • overwrite: Replace the name's active generation. The old reference becomes stale and no history is retained.

Returns

A tensor-free ArtifactRef identifying the newly published generation. The reference is not a materialized copy of value; pass it to get to reconstruct that exact generation.

get ​

method

python
def get(ref_or_name: ArtifactRef[Any], *, device: torch.device | str='cpu', expected_type: type[U], expected_context_id: str | None=None, verify_checksum: bool=True) -> U: ...
def get(ref_or_name: ArtifactRef[T], *, device: torch.device | str='cpu', expected_type: None=None, expected_context_id: str | None=None, verify_checksum: bool=True) -> T: ...
def get(ref_or_name: str, *, device: torch.device | str='cpu', expected_type: type[U], expected_context_id: str | None=None, verify_checksum: bool=True) -> U | None: ...
def get(ref_or_name: str, *, device: torch.device | str='cpu', expected_type: None=None, expected_context_id: str | None=None, verify_checksum: bool=True) -> TensorResident | None: ...

Get a repository value while holding a catalog read snapshot.

A logical name that has no current generation returns None. An ArtifactRef is generation-specific, so a missing, replaced, deleted, or cross-store reference raises fhelium.errors.StaleArtifactReferenceError instead. Catalog, checksum, type, context, and payload failures are never converted to None.

This is a repository lookup, not a file-codec operation. fhelium.load_value reads one caller-selected value-file path; get resolves a catalog name or checked generation, verifies store policy, and then reconstructs the exact value.

Parameters

  • ref_or_name: Logical name for the optional current generation, or a generation-specific checked reference.
  • device: Device on which to reconstruct the exact value. Defaults to CPU and is not inherited from the saved value.
  • expected_type: Optional concrete value type required both in the file metadata and after reconstruction.
  • expected_context_id: Optional context identity required before payload materialization.
  • verify_checksum: Whether to verify the repository payload digest before reconstruction.

Returns

The reconstructed exact value. Returns None only when a string logical name has no current generation.

inspect ​

method

python
def inspect(ref_or_name: ArtifactRef[Any] | str) -> ArtifactMetadata: ...

Validate current catalog metadata and payload headers.

exists ​

method

python
def exists(name: str) -> bool: ...

Return whether name has a catalog row and present payload file.

This is a lightweight availability probe. It does not checksum or inspect the payload; use inspect for structural validation.

list ​

method

python
def list(*, prefix: str | None=None) -> list[ArtifactRef[Any]]: ...

Return structurally validated current references sorted by name.

delete ​

method

python
def delete(ref_or_name: ArtifactRef[Any] | str) -> None: ...

Delete the one active generation, optionally compare-and-delete.

ArtifactCollection ​

class View source

python
ArtifactCollection(store: ArtifactStore, prefix: str)

A logical namespace for independently materializable artifacts.

put ​

method

python
def put(name: str, value: T, **kwargs: Any) -> ArtifactRef[T]: ...

Persist value under this collection prefix.

get ​

method

python
def get(ref_or_name: ArtifactRef[Any], *, device: torch.device | str='cpu', expected_type: type[U], expected_context_id: str | None=None, verify_checksum: bool=True) -> U: ...
def get(ref_or_name: ArtifactRef[T], *, device: torch.device | str='cpu', expected_type: None=None, expected_context_id: str | None=None, verify_checksum: bool=True) -> T: ...
def get(ref_or_name: str, *, device: torch.device | str='cpu', expected_type: type[U], expected_context_id: str | None=None, verify_checksum: bool=True) -> U | None: ...
def get(ref_or_name: str, *, device: torch.device | str='cpu', expected_type: None=None, expected_context_id: str | None=None, verify_checksum: bool=True) -> TensorResident | None: ...

Get a checked ref or optional collection-relative current value.

A missing string name returns None. A missing or replaced ArtifactRef remains a stale-reference error.

inspect ​

method

python
def inspect(name: str) -> ArtifactMetadata: ...

Inspect a collection-relative artifact without loading tensors.

exists ​

method

python
def exists(name: str) -> bool: ...

Return whether a collection-relative current artifact exists.

list ​

method

python
def list() -> list[ArtifactRef[Any]]: ...

List current artifacts nested under this collection prefix.

delete ​

method

python
def delete(ref_or_name: ArtifactRef[Any] | str) -> None: ...

Delete an artifact constrained to this collection.

Towards full-stack encrypted execution infrastructures

Released under the MIT License. Copyright VisualDust and FHElium contributors