1 lightning.finite_horizon.studies.archive

lightning.finite_horizon.studies.archive

Transport sealed scorer-study bytes without revising execution provenance.

The manifest binds original source paths to portable payload paths. Its digest must come from an external trusted receipt: a digest stored inside the same archive cannot authenticate that archive. Verification establishes byte integrity only; scientific admission belongs to schema-specific study readers.

1.1 Classes

Name Description
ReceiptError A retained result does not meet its frozen identity/support contract.
ScorerArchiveFile Authenticated historical identity and portable location of one file.
ScorerStudyArchive Immutable verified transport metadata, separate from scientific admission.

1.1.1 ReceiptError

lightning.finite_horizon.studies.archive.ReceiptError()

A retained result does not meet its frozen identity/support contract.

1.1.2 ScorerArchiveFile

lightning.finite_horizon.studies.archive.ScorerArchiveFile(
    logical_path,
    source_path,
    sha256,
    size_bytes,
)

Authenticated historical identity and portable location of one file.

1.1.2.1 Attributes

Name Description
logical_path Canonical relative identity selected by the exporting campaign.
source_path Original absolute execution/source path; never opened during readback.
sha256 SHA256 of the preserved file bytes.
size_bytes Exact byte length, including empty evidence files.

1.1.3 ScorerStudyArchive

lightning.finite_horizon.studies.archive.ScorerStudyArchive(
    root,
    source_revision,
    manifest_sha256,
    files,
)

Immutable verified transport metadata, separate from scientific admission.

Payload files remain filesystem resources. resolve revalidates them so a mutation after initial admission cannot silently become new evidence. Callers must consume returned paths promptly; concurrent hostile filesystem changes after return are outside this path-based interface’s guarantee.

1.1.3.1 Attributes

Name Description
root Current absolute archive location, independent of historical execution.
source_revision Historical source revision asserted by the externally pinned manifest.
manifest_sha256 Externally supplied manifest digest verified during admission.
files Immutable file identities in canonical logical-path order.

1.1.3.2 Methods

Name Description
resolve Return a currently verified payload path or reject missing/tampered bytes.
historical_path Return original path identity without requiring that path to exist.
1.1.3.2.1 resolve
lightning.finite_horizon.studies.archive.ScorerStudyArchive.resolve(
    logical_path,
)

Return a currently verified payload path or reject missing/tampered bytes.

1.1.3.2.2 historical_path
lightning.finite_horizon.studies.archive.ScorerStudyArchive.historical_path(
    logical_path,
)

Return original path identity without requiring that path to exist.

1.2 Functions

Name Description
archive_study_directory Resolve a portable study only after every present payload is authenticated.
read_scorer_archive Verify a portable archive against an externally pinned manifest digest.
write_scorer_archive Copy explicit scorer evidence sources and return the manifest SHA256.

1.2.1 archive_study_directory

lightning.finite_horizon.studies.archive.archive_study_directory(
    archive,
    prefix,
)

Resolve a portable study only after every present payload is authenticated.

Extra files would change failed/unlaunched dispositions and are rejected. Original execution paths come exclusively from externally pinned metadata.

1.2.2 read_scorer_archive

lightning.finite_horizon.studies.archive.read_scorer_archive(
    root,
    *,
    expected_manifest_sha256,
)

Verify a portable archive against an externally pinned manifest digest.

Reject duplicate JSON keys, ambiguous logical identities, noncanonical paths, symlinks, nonregular payloads, and changed bytes. Original source paths are authenticated metadata and are never used to locate current files. Unknown schema versions or fields fail closed; every admitted payload is hashed.

1.2.3 write_scorer_archive

lightning.finite_horizon.studies.archive.write_scorer_archive(
    destination,
    sources,
    *,
    source_revision,
)

Copy explicit scorer evidence sources and return the manifest SHA256.

The destination must not exist. Each logical path is canonical and relative; source files and all path ancestors must be regular/non-symlink respectively. Original absolute identities are preserved, even after relocation. Each copy checks source metadata and hashes before/after transport. A sibling staging directory is renamed only after full verification; failures remove staging and leave no published destination. This operation does not admit a study.

Back to top