httk.workflow.manifests

Deterministic signed project manifests.

Attributes

MAINTENANCE_LOCK_FILE

MAINTENANCE_LOCK_MAX_AGE_SECONDS

Classes

ManifestVerification

What verifying one manifest against one tree established.

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

class httk.workflow.manifests.ManifestVerification

What verifying one manifest against one tree established.

A signature check answers two separate questions. Does this manifest describe this tree, unaltered? is answered by the digests and the signature. Was it made by somebody this project trusts? is answered only by comparing the signing key with a trust anchor that did not come from the manifest.

Parameters:

  • verdict – Classify the verification result.

  • reason – Explain the classification.

  • manifest – Identify the verified manifest.

  • manifest_format – Identify the manifest format used.

  • public_key – Record the signing key, when readable.

  • trusted_keys – Record the trust anchors consulted.

verdict: str
reason: str
manifest: pathlib.Path
manifest_format: str
public_key: str | None = None
trusted_keys: tuple[str, Ellipsis] = ()
property valid: bool

Whether the manifest describes this tree and its signature verified.

property trusted: bool

Whether the verified signature was made by a pinned key.

property exit_code: int

The command-line status this verdict reports.

as_mapping()

Return the JSON representation of this verdict.

Returns:

JSON-compatible verification members.

Return type:

dict[str, object]

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:
Returns:

The detailed verification verdict.

Raises:

ValueError – If no project or usable manifest exists.

Return type:

httk.core.project.manifests.ManifestVerification