manifest

Classes

StageManifest

Durable metadata and semantic identity for one Puzzletron stage execution.

Functions

read_stage_manifest

Read a stage manifest while preserving compatibility with older schemas.

semantic_stage_config

Return configuration that can change the semantic result of one stage.

stage_manifest_from_config

Build a worker manifest with separate authored and effective config views.

validate_stage_execution_record

Validate the canonical pointer and every immutable record it references.

write_stage_execution_record

Persist immutable resolved config and artifact metadata for one execution.

write_stage_manifest

Atomically write a stage manifest from rank zero.
class StageManifest

Bases: object

Durable metadata and semantic identity for one Puzzletron stage execution.

__init__(stage, version='1', status='pending', inputs=<factory>, outputs=<factory>, config=<factory>, capability_snapshot=None, semantic_config=None, implementation_provenance=<factory>, skip_reason=None, effective_config=None, execution_record=None, stale_reason=None, started_at=<factory>, ended_at=None)
Parameters:

  • stage (str)

  • version (str)

  • status (str)

  • inputs (dict[str, Any])

  • outputs (dict[str, Any])

  • config (dict[str, Any])

  • capability_snapshot (dict[str, Any] | None)

  • semantic_config (dict[str, Any] | None)

  • implementation_provenance (dict[str, Any])

  • skip_reason (str | None)

  • effective_config (dict[str, Any] | None)

  • execution_record (dict[str, Any] | None)

  • stale_reason (str | None)

  • started_at (str)

  • ended_at (str | None)

Return type:

None

capability_snapshot: dict[str, Any] | None = None
complete(*, outputs=None, status='success', skip_reason=None)

Mark the stage complete with its validated outputs and final status.

Parameters:
Return type:

None

config: dict[str, Any]
property config_identity: str
effective_config: dict[str, Any] | None = None
ended_at: str | None = None
execution_record: dict[str, Any] | None = None
implementation_provenance: dict[str, Any]
inputs: dict[str, Any]
outputs: dict[str, Any]
semantic_config: dict[str, Any] | None = None
property semantic_config_identity: str

Return the identity of configuration relevant to this stage’s result.

property semantic_identity: str

Return the compatibility identity consumed by downstream resume checks.

skip_reason: str | None = None
stage: str
stale_reason: str | None = None
started_at: str
status: str = 'pending'
to_dict()

Return the backward-compatible serialized manifest payload.

Return type:

dict[str, Any]

version: str = '1'
read_stage_manifest(path)

Read a stage manifest while preserving compatibility with older schemas.

Parameters:

path (str | Path)

Return type:

dict[str, Any]

semantic_stage_config(config, stage_id, *, use_authored=True)

Return configuration that can change the semantic result of one stage.

Public stages declare their semantic sections alongside their other scheduler-neutral metadata. Dynamic stages that are not in the public registry retain the historical stage-ID section fallback.

Normalized worker configurations retain the independently loaded authored configuration under _runtime.authored_config. Semantic compatibility uses that authored view by default, while execution records may explicitly request the effective worker view.

Parameters:

  • config (Mapping[str, Any])

  • stage_id (str)

  • use_authored (bool)

Return type:

dict[str, Any]

stage_manifest_from_config(stage, config, *, inputs=None, effective_config=None, **manifest_fields)

Build a worker manifest with separate authored and effective config views.

Parameters:

  • stage (str)

  • config (Mapping[str, Any])

  • inputs (Mapping[str, Any] | None)

  • effective_config (Mapping[str, Any] | None)

  • manifest_fields (Any)

Return type:

StageManifest

validate_stage_execution_record(manifest_path, *, expected_stage=None)

Validate the canonical pointer and every immutable record it references.

Historical stage manifests without execution_record remain readable. Any manifest that opts into the execution-record schema is checked fail closed.

Parameters:

  • manifest_path (str | Path)

  • expected_stage (str | None)

Return type:

tuple[str, …]

write_stage_execution_record(manifest_path, manifest_payload)

Persist immutable resolved config and artifact metadata for one execution.

Parameters:

  • manifest_path (str | Path)

  • manifest_payload (dict[str, Any])

Return type:

dict[str, Any]

write_stage_manifest(path, manifest)

Atomically write a stage manifest from rank zero.

Rank zero publishes the immutable execution record and assigns its reference to manifest.execution_record before writing the manifest. Other ranks return without writing and leave manifest.execution_record unchanged.

Parameters:
Return type:

None