ump_workflow.share

module ump-workflow

Share a bundle through ump-core (S6): pure helpers, no network code.

A shared bundle is filed as a Tier A model_manifest whose payload_refs pin every file of the bundle by sha256 (workflow_bundle names the bundle by its workflow.json; file:<relpath> names each file) and whose input_contract is the bundle’s. The blobs live in core’s content-addressed store. A reader downloads them, rebuilds the folder with materialize (verified through read_bundle, and against the refs), and trusts exactly the code and prep-step hashes that trusted_hashes_from_approval returns: those of a validated manifest a second person approved (G-INT-02: never the owner, the submitter or the bundle’s author). That trust is passed to open_bundle(trusted_hashes=...) for that object only and never written to the machine’s trust store.

Classes

ApprovalTrust

class

class ApprovalTrust(NamedTuple)

What an approval vouches for: hashes (code and prep-step sha256) or an empty set with a reason code (WORKFLOW_SHARE_NOT_APPROVED, WORKFLOW_SELF_APPROVED, WORKFLOW_SHARE_MISMATCH) and detail.

Fields

Name	Type	Default	Description
hashes	frozenset[str]
reason	str | None	None
detail	str	''

Source: packages/ump-workflow/src/ump_workflow/share.py, line 159

Functions

bundle_files

function

def bundle_files(bundle: BundleData | str | Path) -> dict[str, bytes]

{relpath: bytes} of every file in a verified bundle, workflow.json and SHA256SUMS included. Each file is read again and checked against the hashes the bundle was verified with (a file changed since the read is BUNDLE_TAMPERED).

Source: packages/ump-workflow/src/ump_workflow/share.py, line 39

bundle_manifest_refs

function

def bundle_manifest_refs(bundle: BundleData | str | Path) -> dict[str, str]

The payload_refs map of a shared bundle: workflow_bundle (sha256: of workflow.json, the bundle’s id) and file:<relpath> = sha256:<hex> for every file.

Source: packages/ump-workflow/src/ump_workflow/share.py, line 56

file_refs

function

def file_refs(refs: Mapping[str, str]) -> dict[str, str]

{relpath: hex} from a payload_refs map (the file: entries only).

Source: packages/ump-workflow/src/ump_workflow/share.py, line 65

step_hashes

function

def step_hashes(bundle: BundleData | str | Path) -> dict[str, str]

{step_id: sha256} of the prep recipe’s named-step code (finprint’s hash: sha256 of the UTF-8 code).

Source: packages/ump-workflow/src/ump_workflow/share.py, line 71

share_note

function

def share_note(bundle: BundleData | str | Path) -> dict[str, Any]

The manifest note that records what an approval vouches for: the code hash and the step hashes.

Source: packages/ump-workflow/src/ump_workflow/share.py, line 78

manifest_doc

function

def manifest_doc(
    bundle: BundleData | str | Path,
    *,
    client_id: str | None,
    title: str | None = None,
) -> dict[str, Any]

The draft Tier A model_manifest doc of a shared bundle: name, client, engine ump-workflow, family, estimands, summaries and dependence from summary.json, input_contract from contract.json, payload_refs from bundle_manifest_refs and the share note.

Source: packages/ump-workflow/src/ump_workflow/share.py, line 87

materialize

function

def materialize(
    files: Mapping[str, bytes],
    dest: str | Path,
    *,
    refs: Mapping[str, str] | None = None,
) -> BundleData

Rebuild a bundle folder at dest (which must not exist) from {relpath: bytes} and verify it through read_bundle; with refs (a payload_refs map) the rebuilt bundle must also match them exactly. A wrong or missing blob refuses (BUNDLE_TAMPERED) and an unsafe path (absolute, .., a backslash) is BUNDLE_INVALID; on any refusal nothing is left behind.

Source: packages/ump-workflow/src/ump_workflow/share.py, line 119

is_principal_id

function

def is_principal_id(value: Any) -> bool

True for a principal id such as user:maya.chen (the rule save_workflow enforces on author); a bare name or an email is not one.

Source: packages/ump-workflow/src/ump_workflow/share.py, line 172

trusted_hashes_from_approval

function

def trusted_hashes_from_approval(
    envelope: Mapping[str, Any],
    bundle: BundleData | str | Path,
) -> ApprovalTrust

The code and prep-step hashes a core envelope vouches for, checked against bundle. Trust is given only when the envelope is a model_manifest of engine ump-workflow in state validated (its head version is the validated one), approved_by is present and is none of the owner, the submitter and the bundle’s author, and the doc’s payload_refs and recorded code_sha256 / step_sha256 match the bundle exactly. Otherwise an empty set with a reason code.

Source: packages/ump-workflow/src/ump_workflow/share.py, line 189

Constants

Name	Type	Value	Description
ENGINE		'ump-workflow'
BUNDLE_REF		'workflow_bundle'
FILE_PREFIX		'file:'
NOTE_KIND		'workflow_bundle'