Artifact

An Artifact is immutable file or tree content with explicit identity and metadata. It owns validation, composition, transport and verified storage. A storage path is not its identity.

Source and concrete API: artifact.go.

Properties

Artifact: a derivation Key, semantic SHA256, content tree and named outputs.
Tree and Entry: relative paths, bytes, modes, owners, links and supported filesystem metadata.
Output: a name referring to a declared file or subtree.
Store and Objects: caller-located storage for validated trees or opaque binary payloads and their receipts.

Behavior

Tree.Validate rejects invalid paths and metadata. Compose merges compatible trees without implicit overlay precedence. Equal entries may be deduplicated; different contents, ownership, modes, link targets or entry kinds at one path are conflicts. Traversal outside the logical root and writes through symlink entries fail.

Tree.File, Tree.Sub and Snapshot select or capture explicit content. Tree.Tar, Tree.WriteTar, ReadTar and WalkTar transport or inspect trees; TAR is a representation utility, not a separate domain concept. WriteTar streams the same deterministic bytes as Tar into a caller-owned writer without allocating a complete archive buffer. Failure may leave partial output, which must not be published.

Store.Open, Store.Put and ValidateOutputs verify content and publish complete results. Payload files precede their receipts. Missing, incomplete or corrupt payloads invalidate reuse. Receipts contain identities and metadata, never base64-encoded file bodies.

Objects.Open, OpenImmutable and Put handle binary objects. Immutable-object size/mtime stamp reuse is an explicit trust policy; it does not detect deliberate edits that restore timestamps. Ordinary tree results verify their payload bytes.

Artifact.MaterializeFile writes a named regular-file output to a new read-only host file. It rejects existing destinations, missing names and non-file outputs, and removes incomplete writes. The caller owns the parent directory and the copy’s lifetime. This is byte export for consumption, not installation or a promise to reproduce Linux owners, modes or special entries. Stored payloads remain separate from the copy.

Identity and lifetime

File identity covers bytes and relevant executable metadata. Tree identity covers canonical paths, types, contents, modes, owners, links and supported metadata independently of host path spelling or enumeration order. A derivation key describes how content was obtained; its inputs are supplied by the caller. Equal content does not prove equal derivations.

Publication must not expose incomplete content. Mutable scratch is never proof of a successful result. Unsupported metadata causes an explicit failure rather than silent loss. Persistent storage belongs to the caller; a tree value grants no right to modify its source files.