Persists one run result as a standalone JSON artifact.
A multi-run application passes values between ordinary runs. Scraping them from stdout is not good enough: terminal output interleaves with logs, has no atomicity, and cannot express that a value must never be published. This writer gives a run one explicit destination instead. Its read-only preflight validates deterministic destination conflicts before provider acquisition or run execution; exclusive publication remains authoritative against races.
Persistence is atomic and refuses to clobber. Content is deterministic
canonical JSON: the SHA-256 digest of the exact artifact bytes is therefore a
stable identity for the successful value. Content is written to an exclusive
file inside a mode-0700 temporary sibling directory, linked into place, and
the temporary directory is then cleaned up best-effort, so a reader never
observes a partial artifact and an existing destination fails rather than
being overwritten. Once the link succeeds, cleanup cannot turn the committed
publication into a reported failure. A relative destination is anchored once
before validation so a VM-wide working-directory change cannot redirect later
filesystem operations. A private artifact is restricted to 0600 before any
content is written, never after.
Secure publication is supported on Unix hosts with POSIX-compatible mkdir
and id executables available on PATH; persistence fails closed when those
authority/mode primitives are unavailable, a physical or lexical ancestor
has an untrusted owner, or any ancestor is group/other-writable without
sticky-directory protection. Preflight also rejects a final parent whose
effective permission class lacks create access.
The private/normal distinction is authority, not formatting. A private result may only reach a private destination; the caller decides the class and this module refuses to write a private value to a normal artifact.
Summary
Functions
Writes value to path as JSON.
Read-only validation of a result destination before run execution.
Types
@type class() :: :normal | :private
@type error() :: :result_destination_exists | :result_persistence_failed | :result_destination_unsafe | :file_sync_failed | :directory_sync_failed | :publication_collision | {:result_not_json_encodable, atom()} | :invalid_result_destination | :private_result_requires_private_destination | {:recovery_written, term()} | {:finalization_uncertain, term()}
Functions
Writes value to path as JSON.
class is the effective class of the value and destination is the class of
the artifact being written. A :private value written to a :normal
destination fails before the destination is created.
Read-only validation of a result destination before run execution.