Artifacts

Purpose and authority boundary

ArtifactDescriptor describes an artifact; it does not store or retrieve it. Scientific byte identity is the SHA-256 of the exact content, not a filename, path, URL, database row, or runtime object. The module keeps that distinction usable without introducing a filesystem or cloud dependency.

Descriptor contract

• Id is a typed entity id; ArtifactRef is the stable workflow/bundle reference.
• LogicalPath is a portable relative path, not a machine location.
• ArtifactKind, MediaType, SchemaId, and SchemaVersion describe how the bytes are interpreted.
• SizeBytes and RawByteDigest bind the exact content.
• Optional SourceRecordDigest, workflow node, provenance event id/digest, and RequiredFor preserve lineage and intended use.

The complete implementation is Artifacts.cs. The broader portable-artifact contract is in ADR 0009.

Identity and path rules

content bytes ──SHA-256──→ raw-byte digest
local input path ────────→ acquisition/reference metadata
portable logical path ───→ bundle/workflow addressing

These three values are not interchangeable.

ComputeRawByteDigest hashes bytes without newline, encoding, filename, or container normalization. NormalizeLogicalPath accepts slash-separated relative logical paths and rejects backslashes, absolute paths, URI schemes, drive letters, leading/trailing slash, empty segments, and ./... Equality remains ordinal and case-sensitive at the bundle boundary.

Typical developer flow

1. Read or produce bytes in an adapter that owns I/O.
2. Compute ContentDigest.Sha256(bytes) before any storage or transport transformation.
3. Create a descriptor with a portable logical path, media type, schema, and stable source/producer references.
4. Persist bytes and descriptor atomically in the owning workspace or bundle adapter.
5. On read, recompute size and digest; never trust descriptor text alone.

Failure behavior

Creation rejects blank identity fields, unsafe logical paths, negative size, and invalid/default digests. A descriptor is not a verified-byte wrapper: callers must still compare the recorded size and digest against observed bytes. Changing bytes at the same local path produces a new identity; identical bytes from different locations retain the same raw-byte identity but may have distinct acquisition provenance.

Tests, extension points, and nonclaims

Artifact behavior is exercised with Bundle and Full Text tests, including path traversal, raw digest mismatch, changed bytes, duplicate content, and source-record binding: see BundleTests and FullTextTests.

New artifact kinds extend schema/media vocabularies in their owning domains. This package does not provide storage, retention, access control, malware scanning, MIME sniffing, signatures, encryption, legal/redistribution assessment, archive identity, or safe import commit by itself.