Artifact publication API¶

Use an immutable writer for typed content-addressed evidence. The legacy atomic JSON/CSV helpers replace mutable single-writer exports. Their contracts differ in concurrency, identity, validation and interruption behavior.

Read architecture and versioned results for the relationships to native result sinks and checkpoints. Callers own trusted local paths and parent directories.

coleman.artifacts ¶

Deterministic artifact writing helpers for hooks and extensions.

ArtifactWriter ¶

Build artifact paths and publish local files for extensions.

Parameters:

Name	Type	Description	Default
`run_root`	`str or Path`	Caller-owned local artifact root. Construction stores the path without creating directories or validating a security boundary.	required

Notes

The caller owns path selection and trusted parent directories. This helper is not a hostile-filesystem sandbox. Immutable publication supports cooperative concurrent writers; mutable JSON/CSV helpers have a narrower single-writer contract. Directory durability across power loss is outside the process-interruption guarantee.

init ¶

__init__(run_root)

Store the caller-owned artifact root without filesystem writes.

Parameters:

Name	Type	Description	Default
`run_root`	`str or Path`	Local base directory used by `path_for`. Relative paths retain the caller's working-directory interpretation.	required

path_for ¶

path_for(
    *,
    run_id,
    dataset_id,
    sched_time_ratio=None,
    budget_mode=None,
    budget_value=None,
    execution_id,
    artifact_type,
    ext,
    stem="artifact",
)

Build a deterministic legacy artifact path without creating files.

Parameters:

Name	Type	Description	Default
`run_id`	`str`	Trusted run namespace, normally the configuration-derived run ID.	required
`dataset_id`	`str or None`	Dataset label; `None` uses a placeholder. Unsafe label characters are replaced for this segment.	required
`sched_time_ratio`	`float or None`	Legacy dimensionless ratio, used when `budget_value` is absent.	`None`
`budget_mode`	`str or None`	Budget label. `None` selects `ratio`.	`None`
`budget_value`	`float or None`	Ratio, seconds or test count according to the selected mode.	`None`
`execution_id`	`str or None`	Execution label; `None` uses a placeholder.	required
`artifact_type`	`str`	Artifact family label, sanitized as a path segment.	required
`ext`	`str`	Trusted filename extension, with a leading dot removed.	required
`stem`	`str`	Filename stem, sanitized as a path segment.	`'artifact'`

Returns:

Type	Description
`Path`	Path beneath the composed run/artifact/budget/dataset/execution labels.

Notes

Ratio labels round to integer percentages for compatibility and are not collision-free identities for arbitrary fractional budgets. run_id and ext are caller-trusted rather than containment-validated. Use typed contract fingerprints and immutable family namespaces when exact identity is required; this path builder does not validate budget semantics.

write_csv_atomic ¶

write_csv_atomic(path, rows)

Replace a local CSV file after writing and fsyncing its contents.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Caller-selected destination; missing parents are created.	required
`rows`	`list[dict[str, Any]]`	Materialized rows. The sorted union of keys determines the header; omitted row fields are emitted as empty fields.	required

Raises:

Type	Description
`OSError`	If writing, flushing or replacing the destination fails.

Notes

Overwrites the destination through a fixed .tmp sibling. This is a single-writer legacy export, not concurrent immutable publication or a versioned unit/missingness contract. An interrupted write may leave its uncommitted temporary file.

write_immutable ¶

write_immutable(path, content)

Publish complete UTF-8 bytes once with atomic create-if-absent.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Caller-selected local destination; missing parents are created.	required
`content`	`str`	Exact text bytes after UTF-8 encoding. Existing identical bytes are accepted as an idempotent replay.	required

Raises:

Type	Description
`ValueError`	If an existing destination has different contents.
`OSError`	If the filesystem cannot perform the required local I/O or hard-link publication and directory fsync.

Notes

A unique fsynced temporary file is linked to the final name. Cooperative concurrent writers cannot overwrite a winner or expose partial contents. Temporary files are not completed artifacts; a crash after publication is recovered by identical replay. No lock file or in-memory duplicate index needs recovery. Trusted parents and a suitable local filesystem are required. Parent-directory durability across power loss is outside this contract.

write_immutable_stream ¶

write_immutable_stream(path, chunks, *, maximum_bytes)

Publish a bounded stream with immutable local-file semantics.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Caller-selected destination; missing parents are created.	required
`chunks`	`Iterable[bytes]`	Caller-owned byte iterator. It is exhausted before publication so final checksum validation may fail without exposing a completed artifact.	required
`maximum_bytes`	`int`	Nonnegative integral upper bound on encoded bytes; booleans are rejected.	required

Raises:

Type	Description
`ValueError`	If the bound is invalid, contents exceed it, or existing bytes conflict.
`TypeError`	If a yielded chunk is not bytes.
`OSError`	If local writing, hard-link publication or directory fsync fails.

Notes

Iterator errors propagate; ordinary unwinding removes the unique temporary file. Abrupt termination can leave an uncommitted temporary file. Callers must close their input resources. Identical concurrent replay succeeds; comparison does not load a full source/artifact into memory. The trusted local-filesystem and power-loss limits of write_immutable apply.

write_json_atomic ¶

write_json_atomic(path, payload, indent=2)

Replace a local JSON file after writing and fsyncing its contents.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Caller-selected destination. Missing parent directories are created.	required
`payload`	`object`	JSON-serializable Python value. This legacy helper does not enforce versioned record semantics or finite-number validation.	required
`indent`	`int`	JSON indentation width; keys are sorted and UTF-8 is preserved.	`2`

Raises:

Type	Description
`TypeError`	If the payload cannot be encoded by the standard JSON encoder.
`OSError`	If writing, flushing or replacing the file fails.

Notes

Overwrites the destination. Its fixed .tmp sibling is for a single cooperative writer, not concurrent publication or a complete-last multi-file receipt. Use write_immutable for immutable contract artifacts.

Artifact publication API¶

coleman.artifacts ¶

ArtifactWriter ¶

__init__ ¶

path_for ¶

write_csv_atomic ¶

write_immutable ¶

write_immutable_stream ¶

write_json_atomic ¶

init ¶