httk.workflow.manifests

Deterministic signed project manifests.

Attributes

MAINTENANCE_LOCK_FILE
MAINTENANCE_LOCK_MAX_AGE_SECONDS

Classes

MaintenanceLock

Record the holder of one workspace maintenance lock.

Functions

payload_file_records(root)	Return the deterministic records of one job payload, minus runner scratch.
read_maintenance_lock(workspace)	Describe the workspace maintenance lock, or None when it is absent.
release_maintenance_lock(workspace, *[, force])	Remove a stale, or with force any, maintenance lock and report it.
workspace_maintenance_guard(workspace)	Fence manager launches while a project snapshot is inspected.
verify_legacy_manifest(root, path)	Verify a legacy manifest without modifying its project tree.
verify_manifest([project, manifest, trusted_keys])	Auto-detect a v2 or legacy manifest and verify it against its trust anchors.

Module Contents

httk.workflow.manifests.MAINTENANCE_LOCK_FILE = 'maintenance.lock'

httk.workflow.manifests.MAINTENANCE_LOCK_MAX_AGE_SECONDS = 86400

httk.workflow.manifests.payload_file_records(root)

Return the deterministic records of one job payload, minus runner scratch.

A payload’s runner-private entries — attempt control, logs, and job state — are excluded from every seal record exactly as they are from a payload digest, so publishing an outcome never changes a sealed payload’s records.

class httk.workflow.manifests.MaintenanceLock

Record the holder of one workspace maintenance lock.

Parameters:

• path – Locate the lock file.

• pid – Record the holder process identifier, when readable.

• hostname – Record the holder host, when readable.

• created – Record the holder creation timestamp, when readable.

• readable – Mark whether the lock contents could be read.

path: pathlib.Path

pid: int | None

hostname: str | None

created: str | None

readable: bool = True

property age_seconds: float | None

Age of the lock, or None when its timestamp is unusable.

property local: bool

Whether the recorded host is the host inspecting the lock.

property dead: bool

Whether a same-host holder process is known to be gone.

is_stale(*, max_age_seconds=MAINTENANCE_LOCK_MAX_AGE_SECONDS)

Whether the lock can be reclaimed without operator confirmation.

describe()

Describe the holder for an operator diagnostic.

httk.workflow.manifests.read_maintenance_lock(workspace)

Describe the workspace maintenance lock, or None when it is absent.

Parameters:

workspace (httk.workflow.workspace.Workspace) – Locate the workspace whose lock to inspect.

Returns:

The recorded lock, or None when no lock exists.

Return type:

MaintenanceLock | None

httk.workflow.manifests.release_maintenance_lock(workspace, *, force=False)

Remove a stale, or with force any, maintenance lock and report it.

Parameters:

• workspace (httk.workflow.workspace.Workspace) – Locate the workspace whose lock to remove.

• force (bool) – Permit removal of a lock that does not appear stale.

Returns:

A human-readable removal result.

Raises:

ValueError – If a live lock is protected by the default policy.

Return type:

str

httk.workflow.manifests.workspace_maintenance_guard(workspace)

Fence manager launches while a project snapshot is inspected.

Parameters:

workspace (httk.workflow.workspace.Workspace) – Lock and inspect this workspace around the guarded work.

Returns:

A context manager that holds the maintenance lock.

Raises:

ValueError – If the workspace is already maintained or not quiescent.

Return type:

collections.abc.Iterator[None]

httk.workflow.manifests.verify_legacy_manifest(root, path)

Verify a legacy manifest without modifying its project tree.

Parameters:

• root (pathlib.Path) – Locate the tree the manifest should describe.

• path (pathlib.Path) – Locate the legacy manifest to verify.

Returns:

Whether the legacy tree records and signature verify.

Return type:

bool

httk.workflow.manifests.verify_manifest(project=None, *, manifest=None, trusted_keys=None)

Auto-detect a v2 or legacy manifest and verify it against its trust anchors.

The trust anchor is the key pinned in project.json — never the key the manifest being verified names in its own header — plus any key passed in trusted_keys, as a recorded value or as the path of a *.pub file.

Parameters:

• project (str | os.PathLike[str] | None) – Locate the project to discover and verify.

• manifest (str | os.PathLike[str] | None) – Select a manifest path instead of the project default.

• trusted_keys (collections.abc.Sequence[str | os.PathLike[str]] | None) – Add explicit trust anchors to the project keys.

Returns:

The detailed verification verdict.

Raises:

ValueError – If no project or usable manifest exists.

Return type:

httk.core.project.manifests.ManifestVerification