use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use thiserror::Error;
use crate::effects::EffectId;
use crate::record::ArtifactRef;
use crate::registry::MAX_ARTIFACT_NAME_LEN;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MediaKind {
File,
Image,
Audio,
Data,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(tag = "policy", rename_all = "snake_case")]
pub enum RetentionPolicy {
Pinned,
Days {
days: u32,
},
#[default]
ReceiptBound,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ArtifactVersion {
pub sha256: String,
pub bytes: u64,
pub committed_at: DateTime<Utc>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ArtifactLineage {
pub run_id: String,
pub effect_id: EffectId,
pub event_id: String,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RunArtifact {
pub artifact_id: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub name: Option<String>,
pub media_kind: MediaKind,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub media_type: Option<String>,
pub lineage: ArtifactLineage,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub versions: Vec<ArtifactVersion>,
pub retention: RetentionPolicy,
pub created_at: DateTime<Utc>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ArtifactCommitment {
pub artifact_id: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub name: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub version: Option<u64>,
pub media_kind: MediaKind,
pub bytes: u64,
pub effect_id: EffectId,
pub retention: RetentionPolicy,
}
#[derive(Debug, Clone)]
pub struct CommitDeclaration {
pub reference: ArtifactRef,
pub name: Option<String>,
pub media_kind: MediaKind,
pub media_type: Option<String>,
pub lineage: ArtifactLineage,
pub retention: RetentionPolicy,
pub committed_at: DateTime<Utc>,
}
pub fn commit_artifact(
declaration: CommitDeclaration,
) -> Result<(RunArtifact, ArtifactCommitment), ArtifactError> {
validate_artifact_address(&declaration.reference.sha256)?;
if let Some(name) = &declaration.name {
validate_artifact_name(name)?;
}
let version = declaration.name.as_ref().map(|_| ArtifactVersion {
sha256: declaration.reference.sha256.clone(),
bytes: declaration.reference.bytes,
committed_at: declaration.committed_at,
});
let record = RunArtifact {
artifact_id: declaration.reference.sha256.clone(),
name: declaration.name.clone(),
media_kind: declaration.media_kind,
media_type: declaration.media_type.clone(),
lineage: declaration.lineage,
versions: version.into_iter().collect(),
retention: declaration.retention,
created_at: declaration.committed_at,
};
let commitment = ArtifactCommitment {
artifact_id: declaration.reference.sha256,
name: declaration.name,
version: record
.versions
.len()
.checked_sub(1)
.map(|index| index as u64),
media_kind: declaration.media_kind,
bytes: declaration.reference.bytes,
effect_id: record.lineage.effect_id.clone(),
retention: declaration.retention,
};
Ok((record, commitment))
}
pub fn append_artifact_version(
head: &RunArtifact,
declaration: CommitDeclaration,
) -> Result<(RunArtifact, ArtifactCommitment), ArtifactError> {
validate_artifact_address(&declaration.reference.sha256)?;
let Some(head_name) = &head.name else {
return Err(ArtifactError::VersionMismatch {
reason: "the sequence head is unnamed — versions accumulate under a name; an \
address-only artifact has no sequence to join",
});
};
match &declaration.name {
Some(name) if name == head_name => validate_artifact_name(name)?,
_ => {
return Err(ArtifactError::VersionMismatch {
reason: "the declaration's name is not the sequence head's — a version \
joins the sequence its name owns",
})
}
}
let mut versions = head.versions.clone();
versions.push(ArtifactVersion {
sha256: declaration.reference.sha256.clone(),
bytes: declaration.reference.bytes,
committed_at: declaration.committed_at,
});
let record = RunArtifact {
artifact_id: declaration.reference.sha256.clone(),
name: head.name.clone(),
media_kind: declaration.media_kind,
media_type: declaration.media_type.clone(),
lineage: declaration.lineage,
versions,
retention: declaration.retention,
created_at: declaration.committed_at,
};
let commitment = ArtifactCommitment {
artifact_id: declaration.reference.sha256,
name: head.name.clone(),
version: record
.versions
.len()
.checked_sub(1)
.map(|index| index as u64),
media_kind: declaration.media_kind,
bytes: declaration.reference.bytes,
effect_id: record.lineage.effect_id.clone(),
retention: declaration.retention,
};
Ok((record, commitment))
}
fn validate_artifact_name(name: &str) -> Result<(), ArtifactError> {
let refuse = |reason: &'static str| ArtifactError::InvalidName {
name: name.to_owned(),
reason,
};
if name.is_empty() {
return Err(refuse("empty — an artifact exists to be named"));
}
if name.len() > MAX_ARTIFACT_NAME_LEN {
return Err(refuse("over 128 bytes"));
}
if name != name.trim() {
return Err(refuse(
"leading or trailing whitespace — visually identical names would be distinct \
artifacts, which is a misreview waiting to happen",
));
}
if name.chars().any(|c| c.is_control() || c == '@' || c == '/') {
return Err(refuse(
"carries a control character, `@`, or `/` — the tag separator and the tenant \
separator are structural, and control characters have no business in a key",
));
}
Ok(())
}
fn validate_artifact_address(address: &str) -> Result<(), ArtifactError> {
if address.len() == 64
&& address
.chars()
.all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase())
{
return Ok(());
}
Err(ArtifactError::InvalidAddress {
address: address.to_owned(),
reason: "not 64 lowercase hex characters — the `sha256_hex` shape; identity is \
integrity, and an address outside the rule can never re-hash to itself",
})
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PruneCause {
Expired,
Unbound,
Released,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ArtifactPrune {
pub artifact_id: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub name: Option<String>,
pub cause: PruneCause,
pub swept_at: DateTime<Utc>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ArtifactRelease {
pub artifact_id: String,
pub tenant: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub name: Option<String>,
pub released_by: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub reason: Option<String>,
pub released_at: DateTime<Utc>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum UnavailabilitySurface {
Bytes,
Preview,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ArtifactUnavailability {
pub artifact_id: String,
pub tenant: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub name: Option<String>,
pub surface: UnavailabilitySurface,
pub observed_at: DateTime<Utc>,
}
pub const PREVIEW_TEXT_MAX_BYTES: usize = 4096;
pub const PREVIEW_THUMBNAIL_MAX_EDGE: u32 = 64;
pub const PREVIEW_WAVEFORM_BUCKETS: usize = 64;
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ArtifactPreview {
Text {
text: String,
truncated: bool,
source_bytes: u64,
},
Json {
value: serde_json::Value,
source_bytes: u64,
},
Image {
format: String,
width: u32,
height: u32,
thumb_width: u32,
thumb_height: u32,
pixels_ppm_hex: String,
},
Audio {
format: String,
duration_ms: u64,
sample_rate: u32,
channels: u16,
frames: u64,
peaks: Vec<u16>,
},
Empty {
reason: String,
},
}
pub fn derive_preview(media_kind: MediaKind, bytes: &[u8]) -> ArtifactPreview {
let source_bytes = bytes.len() as u64;
match media_kind {
MediaKind::File | MediaKind::Data => derive_text_preview(bytes, source_bytes),
MediaKind::Image => derive_image_preview(bytes),
MediaKind::Audio => derive_audio_preview(bytes),
}
}
fn derive_text_preview(bytes: &[u8], source_bytes: u64) -> ArtifactPreview {
if bytes.len() <= PREVIEW_TEXT_MAX_BYTES {
if let Ok(value) = serde_json::from_slice::<serde_json::Value>(bytes) {
return ArtifactPreview::Json {
value,
source_bytes,
};
}
}
let window = &bytes[..bytes.len().min(PREVIEW_TEXT_MAX_BYTES)];
let truncated = bytes.len() > PREVIEW_TEXT_MAX_BYTES;
match std::str::from_utf8(window) {
Ok(text) => ArtifactPreview::Text {
text: text.to_owned(),
truncated,
source_bytes,
},
Err(error) if truncated && error.error_len().is_none() => {
let text = std::str::from_utf8(&window[..error.valid_up_to()])
.expect("valid_up_to is a char boundary");
ArtifactPreview::Text {
text: text.to_owned(),
truncated: true,
source_bytes,
}
}
Err(_) => ArtifactPreview::Empty {
reason: "the bytes are not valid UTF-8 — binary content yields no text \
preview, and a placeholder would pretend otherwise"
.to_owned(),
},
}
}
fn derive_image_preview(bytes: &[u8]) -> ArtifactPreview {
let decoded = decode_bmp(bytes)
.map(|(width, height, rgb)| ("bmp", width, height, rgb))
.or_else(|| decode_pnm(bytes).map(|(width, height, rgb)| ("pnm", width, height, rgb)));
let Some((format, width, height, rgb)) = decoded else {
return ArtifactPreview::Empty {
reason: "only uncompressed BMP (24/32-bit) and binary PNM (P6/P5) decode \
without a codec dependency — a compressed format is the measured-need \
seam, not something to half-parse"
.to_owned(),
};
};
let factor = (width.max(height))
.div_ceil(PREVIEW_THUMBNAIL_MAX_EDGE)
.max(1);
let thumb_width = (width / factor).max(1);
let thumb_height = (height / factor).max(1);
let mut ppm = format!("P6\n{thumb_width} {thumb_height}\n255\n").into_bytes();
for y in 0..thumb_height {
for x in 0..thumb_width {
let source = ((y * factor) * width + (x * factor)) as usize * 3;
ppm.extend_from_slice(&rgb[source..source + 3]);
}
}
ArtifactPreview::Image {
format: format.to_owned(),
width,
height,
thumb_width,
thumb_height,
pixels_ppm_hex: crate::broker::hex_encode(&ppm),
}
}
type Raster = (u32, u32, Vec<u8>);
fn read_u16_le(bytes: &[u8], at: usize) -> Option<u16> {
Some(u16::from_le_bytes(bytes.get(at..at + 2)?.try_into().ok()?))
}
fn read_u32_le(bytes: &[u8], at: usize) -> Option<u32> {
Some(u32::from_le_bytes(bytes.get(at..at + 4)?.try_into().ok()?))
}
fn decode_bmp(bytes: &[u8]) -> Option<Raster> {
if bytes.len() < 54 || &bytes[0..2] != b"BM" {
return None;
}
let data_offset = read_u32_le(bytes, 10)? as usize;
let dib_size = read_u32_le(bytes, 14)? as usize;
if dib_size < 40 {
return None;
}
let width = read_u32_le(bytes, 18)?;
let raw_height = i32::from_le_bytes(bytes.get(22..26)?.try_into().ok()?);
let top_down = raw_height < 0;
let height = raw_height.unsigned_abs();
let bpp = read_u16_le(bytes, 28)?;
let compression = read_u32_le(bytes, 30)?;
if compression != 0 || width == 0 || height == 0 || !matches!(bpp, 24 | 32) {
return None;
}
let pixel_bytes = (bpp / 8) as usize;
let stride = if bpp == 24 {
(width as usize * 3).div_ceil(4) * 4
} else {
width as usize * 4
};
let needed = data_offset.checked_add(stride.checked_mul(height as usize)?)?;
if bytes.len() < needed {
return None;
}
let mut rgb = Vec::with_capacity(width as usize * height as usize * 3);
for row in 0..height as usize {
let source_row = if top_down {
row
} else {
height as usize - 1 - row
};
let base = data_offset + source_row * stride;
for x in 0..width as usize {
let at = base + x * pixel_bytes;
rgb.push(bytes[at + 2]);
rgb.push(bytes[at + 1]);
rgb.push(bytes[at]);
}
}
Some((width, height, rgb))
}
fn decode_pnm(bytes: &[u8]) -> Option<Raster> {
let color = match bytes.first()? {
b'P' => match bytes.get(1)? {
b'6' => true,
b'5' => false,
_ => return None,
},
_ => return None,
};
let mut cursor = 2;
let mut tokens = [0u32; 3];
for token in &mut tokens {
loop {
match bytes.get(cursor)? {
b'#' => {
while bytes.get(cursor).is_some_and(|b| *b != b'\n') {
cursor += 1;
}
}
b if b.is_ascii_whitespace() => cursor += 1,
_ => break,
}
}
let start = cursor;
while bytes.get(cursor).is_some_and(|b| b.is_ascii_digit()) {
cursor += 1;
}
*token = std::str::from_utf8(bytes.get(start..cursor)?)
.ok()?
.parse()
.ok()?;
}
let [width, height, maxval] = tokens;
if width == 0 || height == 0 || maxval != 255 {
return None;
}
if !bytes.get(cursor)?.is_ascii_whitespace() {
return None;
}
cursor += 1;
let pixels = width as usize * height as usize;
let mut rgb = Vec::with_capacity(pixels * 3);
if color {
let data = bytes.get(cursor..cursor + pixels * 3)?;
rgb.extend_from_slice(data);
} else {
let data = bytes.get(cursor..cursor + pixels)?;
for gray in data {
rgb.extend_from_slice(&[*gray, *gray, *gray]);
}
}
Some((width, height, rgb))
}
fn derive_audio_preview(bytes: &[u8]) -> ArtifactPreview {
match decode_wav(bytes) {
Some((sample_rate, channels, frames, peaks)) => ArtifactPreview::Audio {
format: "wav".to_owned(),
duration_ms: frames.saturating_mul(1000) / u64::from(sample_rate.max(1)),
sample_rate,
channels,
frames,
peaks,
},
None => ArtifactPreview::Empty {
reason: "only RIFF/WAVE PCM (8/16-bit) decodes without a codec dependency — \
a compressed or foreign container yields no waveform metadata"
.to_owned(),
},
}
}
fn decode_wav(bytes: &[u8]) -> Option<(u32, u16, u64, Vec<u16>)> {
if bytes.len() < 12 || &bytes[0..4] != b"RIFF" || &bytes[8..12] != b"WAVE" {
return None;
}
let mut cursor = 12;
let mut format: Option<(u16, u32, u16, u16)> = None; let mut data: Option<&[u8]> = None;
while cursor + 8 <= bytes.len() {
let id = &bytes[cursor..cursor + 4];
let size = read_u32_le(bytes, cursor + 4)? as usize;
let body = bytes.get(cursor + 8..cursor + 8 + size)?;
match id {
b"fmt " => {
if size < 16 {
return None;
}
let audio_format = read_u16_le(body, 0)?;
let channels = read_u16_le(body, 2)?;
let sample_rate = read_u32_le(body, 4)?;
let block_align = read_u16_le(body, 12)?;
let bits = read_u16_le(body, 14)?;
if audio_format != 1 || channels == 0 || !matches!(bits, 8 | 16) {
return None;
}
format = Some((channels, sample_rate, bits, block_align));
}
b"data" => data = Some(body),
_ => {}
}
cursor += 8 + size + (size % 2);
}
let (channels, sample_rate, bits, block_align) = format?;
let data = data?;
let align = usize::from(block_align).max(usize::from(channels) * usize::from(bits / 8));
let frames = (data.len() / align) as u64;
if frames == 0 {
return None;
}
let mut peaks = vec![0u16; PREVIEW_WAVEFORM_BUCKETS];
for frame in 0..frames {
let bucket = ((frame * PREVIEW_WAVEFORM_BUCKETS as u64) / frames) as usize;
let base = frame as usize * align;
for channel in 0..usize::from(channels) {
let at = base + channel * usize::from(bits / 8);
let magnitude = match bits {
8 => u16::from(data[at].abs_diff(128)) * 256,
_ => {
let sample = i16::from_le_bytes([data[at], data[at + 1]]);
(sample as i32).unsigned_abs().min(u16::MAX as u32) as u16
}
};
peaks[bucket] = peaks[bucket].max(magnitude);
}
}
Some((sample_rate, channels, frames, peaks))
}
#[derive(Debug, Clone, PartialEq, Error)]
pub enum ArtifactError {
#[error("invalid artifact name {name:?}: {reason}")]
InvalidName {
name: String,
reason: &'static str,
},
#[error("invalid artifact address {address:?}: {reason}")]
InvalidAddress {
address: String,
reason: &'static str,
},
#[error("version append refused: {reason}")]
VersionMismatch {
reason: &'static str,
},
}
#[cfg(test)]
mod tests {
use super::*;
use crate::journal::{Clock, EventDraft, Journal};
use crate::record::{sha256_hex, Effect, RunEventKind};
use serde::Serialize;
use serde_json::json;
use std::path::PathBuf;
fn golden_path(name: &str) -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR"))
.join("tests")
.join("golden")
.join(name)
}
fn assert_golden(name: &str, value: &impl Serialize) {
let rendered = format!("{}\n", serde_json::to_string_pretty(value).unwrap());
let path = golden_path(name);
if std::env::var_os("UPDATE_GOLDEN").is_some() {
std::fs::write(&path, &rendered).unwrap();
return;
}
let expected = std::fs::read_to_string(&path)
.unwrap_or_else(|e| panic!("missing golden file `{}`: {e}", path.display()));
assert_eq!(
rendered,
expected,
"contract drift in `{}` — if intentional, re-run with UPDATE_GOLDEN=1 \
and review the diff",
path.display()
);
}
fn ts(millis: i64) -> DateTime<Utc> {
DateTime::<Utc>::from_timestamp_millis(millis).unwrap()
}
fn effect_id() -> EffectId {
crate::effects::derive_effect_id(
"run-9",
"render_report",
&sha256_hex(b"weekly"),
Some("render:9"),
)
}
fn lineage() -> ArtifactLineage {
ArtifactLineage {
run_id: "run-9".into(),
effect_id: effect_id(),
event_id: "run-9:7".into(),
}
}
fn named_commitment_pair() -> (RunArtifact, ArtifactCommitment) {
commit_artifact(CommitDeclaration {
reference: ArtifactRef {
sha256: "a".repeat(64),
bytes: 41_312,
},
name: Some("weekly-report".into()),
media_kind: MediaKind::Image,
media_type: Some("image/png".into()),
lineage: lineage(),
retention: RetentionPolicy::Days { days: 30 },
committed_at: ts(1_760_000_000_000),
})
.unwrap()
}
#[test]
fn golden_artifact_event_kinds_shape() {
assert_golden(
"artifact_event_kinds.json",
&vec![
RunEventKind::ArtifactCommitted,
RunEventKind::ArtifactPruned,
RunEventKind::ArtifactRetentionReleased,
RunEventKind::ArtifactUnavailable,
],
);
}
#[test]
fn golden_run_artifact_shape() {
let (record, _) = named_commitment_pair();
assert_golden("run_artifact.json", &record);
}
#[test]
fn golden_run_artifact_unnamed_shape() {
let (record, _) = commit_artifact(CommitDeclaration {
reference: ArtifactRef {
sha256: "b".repeat(64),
bytes: 973,
},
name: None,
media_kind: MediaKind::File,
media_type: None,
lineage: lineage(),
retention: RetentionPolicy::default(),
committed_at: ts(1_760_000_000_000),
})
.unwrap();
assert_golden("run_artifact_unnamed.json", &record);
}
#[test]
fn golden_artifact_commitment_shape() {
let (_, commitment) = named_commitment_pair();
assert_golden("artifact_commitment.json", &commitment);
}
#[test]
fn golden_retention_policy_shape() {
assert_golden(
"retention_policy.json",
&vec![
RetentionPolicy::Pinned,
RetentionPolicy::Days { days: 30 },
RetentionPolicy::ReceiptBound,
],
);
}
#[test]
fn commit_builds_record_and_payload_from_one_derivation() {
let (record, commitment) = named_commitment_pair();
assert_eq!(record.artifact_id, commitment.artifact_id);
assert_eq!(record.name, commitment.name);
assert_eq!(record.media_kind, commitment.media_kind);
assert_eq!(record.retention, commitment.retention);
assert_eq!(record.lineage.effect_id, commitment.effect_id);
assert_eq!(record.versions.len(), 1);
assert_eq!(record.versions[0].sha256, record.artifact_id);
assert_eq!(record.versions[0].bytes, commitment.bytes);
assert_eq!(commitment.version, Some(0));
}
#[test]
fn commit_refuses_the_naming_rules() {
for name in ["", " padded", "has@tag", "tenant/escape", "ctl\tchar"] {
let declaration = CommitDeclaration {
reference: ArtifactRef {
sha256: "a".repeat(64),
bytes: 1,
},
name: Some(name.into()),
media_kind: MediaKind::File,
media_type: None,
lineage: lineage(),
retention: RetentionPolicy::default(),
committed_at: ts(1_760_000_000_000),
};
assert!(
matches!(
commit_artifact(declaration),
Err(ArtifactError::InvalidName { .. })
),
"name {name:?} must be refused"
);
}
}
#[test]
fn commit_refuses_a_malformed_address() {
for address in ["", "abc", &"A".repeat(64), &"z".repeat(64)] {
let declaration = CommitDeclaration {
reference: ArtifactRef {
sha256: address.to_string(),
bytes: 1,
},
name: None,
media_kind: MediaKind::File,
media_type: None,
lineage: lineage(),
retention: RetentionPolicy::default(),
committed_at: ts(1_760_000_000_000),
};
assert!(
matches!(
commit_artifact(declaration),
Err(ArtifactError::InvalidAddress { .. })
),
"address {address:?} must be refused"
);
}
}
#[test]
fn sparse_wire_omits_absent_slots() {
let (record, _) = commit_artifact(CommitDeclaration {
reference: ArtifactRef {
sha256: "c".repeat(64),
bytes: 7,
},
name: None,
media_kind: MediaKind::Data,
media_type: None,
lineage: lineage(),
retention: RetentionPolicy::Pinned,
committed_at: ts(1_760_000_000_000),
})
.unwrap();
let wire = serde_json::to_value(&record).unwrap();
assert!(wire.get("name").is_none());
assert!(wire.get("media_type").is_none());
assert!(wire.get("versions").is_none());
let back: RunArtifact = serde_json::from_value(wire).unwrap();
assert_eq!(back, record);
}
#[test]
fn artifact_committed_journals_and_reverifies() {
let (_, commitment) = named_commitment_pair();
let journal = Journal::new("run-9", "thread-1", Clock::System);
journal.record(
EventDraft::new(RunEventKind::ArtifactCommitted, Effect::Pure)
.output(serde_json::to_value(&commitment).unwrap())
.parent("run-9:7"),
);
let snapshot = journal.snapshot();
let bytes = serde_json::to_vec(&snapshot).unwrap();
let parsed = serde_json::from_slice(&bytes).unwrap();
let rebuilt = Journal::from_snapshot(parsed, Clock::System).unwrap();
let event = &rebuilt.events()[0];
assert_eq!(event.kind, RunEventKind::ArtifactCommitted);
assert_eq!(event.parent.as_deref(), Some("run-9:7"));
let resolved: ArtifactCommitment =
serde_json::from_value(rebuilt.resolve(event.output.as_ref().unwrap()).unwrap())
.unwrap();
assert_eq!(resolved, commitment);
}
#[test]
fn artifact_committed_payload_survives_a_mixed_journal() {
let (_, commitment) = named_commitment_pair();
let journal = Journal::new("run-9", "thread-1", Clock::System);
journal.record(EventDraft::new(RunEventKind::SuperStepStart, Effect::Pure));
journal.record(
EventDraft::new(RunEventKind::NodeOutput, Effect::Pure)
.node("render")
.output(json!({"report": "weekly"})),
);
journal.record(
EventDraft::new(RunEventKind::ArtifactCommitted, Effect::Pure)
.output(serde_json::to_value(&commitment).unwrap()),
);
let snapshot = journal.snapshot();
let rebuilt = Journal::from_snapshot(
serde_json::from_str(&serde_json::to_string(&snapshot).unwrap()).unwrap(),
Clock::System,
)
.unwrap();
assert_eq!(rebuilt.len(), 3);
assert_eq!(rebuilt.events()[2].kind, RunEventKind::ArtifactCommitted);
}
fn versioned_head() -> (RunArtifact, ArtifactCommitment) {
let (base, _) = named_commitment_pair();
let (v2, _) = append_artifact_version(
&base,
CommitDeclaration {
reference: ArtifactRef {
sha256: "d".repeat(64),
bytes: 41_990,
},
name: Some("weekly-report".into()),
media_kind: MediaKind::Image,
media_type: Some("image/png".into()),
lineage: lineage(),
retention: RetentionPolicy::Days { days: 30 },
committed_at: ts(1_760_100_000_000),
},
)
.unwrap();
append_artifact_version(
&v2,
CommitDeclaration {
reference: ArtifactRef {
sha256: "e".repeat(64),
bytes: 42_104,
},
name: Some("weekly-report".into()),
media_kind: MediaKind::Image,
media_type: Some("image/png".into()),
lineage: lineage(),
retention: RetentionPolicy::Days { days: 30 },
committed_at: ts(1_760_200_000_000),
},
)
.unwrap()
}
#[test]
fn golden_run_artifact_versioned_shape() {
let (head, _) = versioned_head();
assert_golden("run_artifact_versioned.json", &head);
}
#[test]
fn golden_artifact_prune_shape() {
assert_golden(
"artifact_prune.json",
&vec![
ArtifactPrune {
artifact_id: "a".repeat(64),
name: Some("weekly-report".into()),
cause: PruneCause::Expired,
swept_at: ts(1_760_300_000_000),
},
ArtifactPrune {
artifact_id: "b".repeat(64),
name: None,
cause: PruneCause::Unbound,
swept_at: ts(1_760_300_000_000),
},
ArtifactPrune {
artifact_id: "c".repeat(64),
name: None,
cause: PruneCause::Released,
swept_at: ts(1_760_300_000_000),
},
],
);
}
#[test]
fn golden_artifact_release_shape() {
assert_golden(
"artifact_release.json",
&ArtifactRelease {
artifact_id: "a".repeat(64),
tenant: "acme".into(),
name: Some("weekly-report".into()),
released_by: "human:amjad".into(),
reason: Some("evidence window closed by counsel".into()),
released_at: ts(1_760_300_000_000),
},
);
}
#[test]
fn golden_artifact_unavailability_shape() {
assert_golden(
"artifact_unavailability.json",
&vec![
ArtifactUnavailability {
artifact_id: "a".repeat(64),
tenant: "acme".into(),
name: Some("weekly-report".into()),
surface: UnavailabilitySurface::Bytes,
observed_at: ts(1_760_300_000_000),
},
ArtifactUnavailability {
artifact_id: "a".repeat(64),
tenant: "acme".into(),
name: Some("weekly-report".into()),
surface: UnavailabilitySurface::Preview,
observed_at: ts(1_760_300_100_000),
},
],
);
}
#[test]
fn version_append_accumulates_and_indexes_the_new_head() {
let (head, commitment) = versioned_head();
assert_eq!(head.versions.len(), 3);
assert_eq!(head.versions[0].sha256, "a".repeat(64));
assert_eq!(head.versions[1].sha256, "d".repeat(64));
assert_eq!(head.versions[2].sha256, "e".repeat(64));
assert_eq!(head.artifact_id, head.versions[2].sha256);
assert_eq!(commitment.version, Some(2));
assert_eq!(commitment.name.as_deref(), Some("weekly-report"));
assert_eq!(head.name.as_deref(), Some("weekly-report"));
}
#[test]
fn version_append_refuses_a_foreign_or_unnamed_sequence() {
let (base, _) = named_commitment_pair();
let declaration = |name: Option<&str>| CommitDeclaration {
reference: ArtifactRef {
sha256: "d".repeat(64),
bytes: 1,
},
name: name.map(str::to_owned),
media_kind: MediaKind::File,
media_type: None,
lineage: lineage(),
retention: RetentionPolicy::default(),
committed_at: ts(1_760_100_000_000),
};
assert!(matches!(
append_artifact_version(&base, declaration(Some("monthly-report"))),
Err(ArtifactError::VersionMismatch { .. })
));
assert!(matches!(
append_artifact_version(&base, declaration(None)),
Err(ArtifactError::VersionMismatch { .. })
));
let (unnamed, _) = commit_artifact(CommitDeclaration {
reference: ArtifactRef {
sha256: "b".repeat(64),
bytes: 1,
},
name: None,
media_kind: MediaKind::File,
media_type: None,
lineage: lineage(),
retention: RetentionPolicy::default(),
committed_at: ts(1_760_000_000_000),
})
.unwrap();
assert!(matches!(
append_artifact_version(&unnamed, declaration(Some("weekly-report"))),
Err(ArtifactError::VersionMismatch { .. })
));
assert!(matches!(
append_artifact_version(&base, declaration(Some("tenant/escape"))),
Err(ArtifactError::VersionMismatch { .. })
));
}
#[test]
fn retention_acts_omit_absent_slots() {
let release = ArtifactRelease {
artifact_id: "f".repeat(64),
tenant: "default".into(),
name: None,
released_by: "human:amjad".into(),
reason: None,
released_at: ts(1_760_300_000_000),
};
let wire = serde_json::to_value(&release).unwrap();
assert!(wire.get("name").is_none());
assert!(wire.get("reason").is_none());
let back: ArtifactRelease = serde_json::from_value(wire).unwrap();
assert_eq!(back, release);
}
fn tiny_bmp() -> Vec<u8> {
let stride = 12; let mut bmp = Vec::new();
bmp.extend_from_slice(b"BM");
bmp.extend_from_slice(&(54u32 + 2 * stride as u32).to_le_bytes()); bmp.extend_from_slice(&0u32.to_le_bytes()); bmp.extend_from_slice(&54u32.to_le_bytes()); bmp.extend_from_slice(&40u32.to_le_bytes()); bmp.extend_from_slice(&4u32.to_le_bytes()); bmp.extend_from_slice(&2i32.to_le_bytes()); bmp.extend_from_slice(&1u16.to_le_bytes()); bmp.extend_from_slice(&24u16.to_le_bytes()); bmp.extend_from_slice(&0u32.to_le_bytes()); bmp.extend_from_slice(&(2 * stride as u32).to_le_bytes()); bmp.extend_from_slice(&0u32.to_le_bytes()); bmp.extend_from_slice(&0u32.to_le_bytes()); bmp.extend_from_slice(&0u32.to_le_bytes()); bmp.extend_from_slice(&0u32.to_le_bytes()); for _ in 0..4 {
bmp.extend_from_slice(&[255, 0, 0]);
}
bmp.extend_from_slice(&[0; 0]); for _ in 0..4 {
bmp.extend_from_slice(&[0, 0, 255]);
}
bmp
}
fn tiny_wav() -> Vec<u8> {
let samples: Vec<u8> = (0..16).map(|i| i * 16).collect();
let mut wav = Vec::new();
wav.extend_from_slice(b"RIFF");
wav.extend_from_slice(&(36u32 + samples.len() as u32).to_le_bytes());
wav.extend_from_slice(b"WAVE");
wav.extend_from_slice(b"fmt ");
wav.extend_from_slice(&16u32.to_le_bytes());
wav.extend_from_slice(&1u16.to_le_bytes()); wav.extend_from_slice(&1u16.to_le_bytes()); wav.extend_from_slice(&8000u32.to_le_bytes()); wav.extend_from_slice(&8000u32.to_le_bytes()); wav.extend_from_slice(&1u16.to_le_bytes()); wav.extend_from_slice(&8u16.to_le_bytes()); wav.extend_from_slice(b"data");
wav.extend_from_slice(&(samples.len() as u32).to_le_bytes());
wav.extend_from_slice(&samples);
wav
}
#[test]
fn golden_artifact_preview_shapes() {
let text = derive_preview(MediaKind::File, b"plain export, no structure");
let json_preview = derive_preview(MediaKind::Data, br#"{"rows":[1,2,3]}"#);
let image = derive_preview(MediaKind::Image, &tiny_bmp());
let audio = derive_preview(MediaKind::Audio, &tiny_wav());
let empty = derive_preview(MediaKind::File, &[0xff, 0x00, 0xfe, 0x01]);
assert_golden(
"artifact_preview.json",
&vec![text, json_preview, image, audio, empty],
);
}
#[test]
fn text_preview_bounds_the_window_and_json_stays_whole() {
let preview = derive_preview(MediaKind::Data, br#"{"ok":true}"#);
assert!(matches!(preview, ArtifactPreview::Json { .. }));
let big = format!("{{\"data\":\"{}\"}}", "x".repeat(PREVIEW_TEXT_MAX_BYTES));
let preview = derive_preview(MediaKind::Data, big.as_bytes());
match preview {
ArtifactPreview::Text {
truncated,
text,
source_bytes,
} => {
assert!(truncated);
assert!(text.len() <= PREVIEW_TEXT_MAX_BYTES);
assert_eq!(source_bytes, big.len() as u64);
}
other => panic!("expected truncated text, got {other:?}"),
}
let mut bytes = vec![b'a'; PREVIEW_TEXT_MAX_BYTES - 1];
bytes.extend_from_slice("é".as_bytes()); let preview = derive_preview(MediaKind::File, &bytes);
match preview {
ArtifactPreview::Text {
truncated, text, ..
} => {
assert!(truncated);
assert_eq!(text.len(), PREVIEW_TEXT_MAX_BYTES - 1);
}
other => panic!("expected boundary-clipped text, got {other:?}"),
}
assert!(matches!(
derive_preview(MediaKind::File, &[b'a', 0xff, b'b']),
ArtifactPreview::Empty { .. }
));
}
#[test]
fn image_preview_decodes_downscales_and_refuses_the_undecodable() {
let preview = derive_preview(MediaKind::Image, &tiny_bmp());
match preview {
ArtifactPreview::Image {
format,
width,
height,
thumb_width,
thumb_height,
pixels_ppm_hex,
} => {
assert_eq!(format, "bmp");
assert_eq!((width, height), (4, 2));
assert_eq!((thumb_width, thumb_height), (4, 2)); let ppm = crate::broker::hex_decode(&pixels_ppm_hex).unwrap();
assert_eq!(&ppm[0..2], b"P6");
let header_len = "P6\n4 2\n255\n".len();
assert_eq!(&ppm[header_len..header_len + 3], &[255, 0, 0]);
assert_eq!(&ppm[ppm.len() - 3..], &[0, 0, 255]);
}
other => panic!("expected a derived thumbnail, got {other:?}"),
}
let mut pnm = b"P5\n2 1\n255\n".to_vec();
pnm.extend_from_slice(&[17, 240]);
match derive_preview(MediaKind::Image, &pnm) {
ArtifactPreview::Image {
format,
pixels_ppm_hex,
..
} => {
assert_eq!(format, "pnm");
let ppm = crate::broker::hex_decode(&pixels_ppm_hex).unwrap();
assert!(ppm.windows(3).any(|w| w == [17, 17, 17]));
}
other => panic!("expected a derived pnm thumbnail, got {other:?}"),
}
let png = [0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0];
assert!(matches!(
derive_preview(MediaKind::Image, &png),
ArtifactPreview::Empty { .. }
));
}
#[test]
fn audio_preview_derives_waveform_metadata_for_pcm_only() {
let preview = derive_preview(MediaKind::Audio, &tiny_wav());
match preview {
ArtifactPreview::Audio {
format,
duration_ms,
sample_rate,
channels,
frames,
peaks,
} => {
assert_eq!(format, "wav");
assert_eq!(duration_ms, 2); assert_eq!(sample_rate, 8000);
assert_eq!(channels, 1);
assert_eq!(frames, 16);
assert_eq!(peaks.len(), PREVIEW_WAVEFORM_BUCKETS);
assert_eq!(peaks[0], 128 * 256);
assert_eq!(peaks.iter().max().unwrap(), &(128 * 256));
assert_eq!(peaks[32], 0);
}
other => panic!("expected waveform metadata, got {other:?}"),
}
assert!(matches!(
derive_preview(MediaKind::Audio, b"RIFF"),
ArtifactPreview::Empty { .. }
));
assert!(matches!(
derive_preview(MediaKind::Audio, b"OggS........"),
ArtifactPreview::Empty { .. }
));
}
}