Day 10 — One Evidence Envelope

Today Signal Room accepts four media types through one API while preserving what makes each one different.

Run the intake

cd rust/rust-ai-engineering
cargo run -q -p mosaic-evidence --example evidence_envelopes
cargo test -p mosaic-evidence envelope

Inspect the emitted JSON before reading the implementation.

Use an enum, not a bag of optional fields

pub enum EvidencePayload {
    Text(TextEvidence),
    Image(ImageEvidence),
    Audio(AudioEvidence),
    Video(VideoEvidence),
}

An image needs width, height, orientation, and regions. Audio needs sample rate, channels, and time ranges. A struct containing twenty optional fields permits nonsense such as an audio sample rate on a PNG. Enum variants make those invalid combinations harder to construct.

Wrap the payload with properties every modality shares:

pub struct EvidenceEnvelope {
    pub id: EvidenceId,
    pub source: SourceLocator,
    pub content_sha256: ContentDigest,
    pub acquired_at: Timestamp,
    pub trust: TrustLabel,
    pub payload: EvidencePayload,
}

Validate before storing

Constructors reject zero dimensions, empty identifiers, impossible ranges, unsupported formats, and a digest that does not match the bytes. Serde decoding alone cannot enforce relationships between fields.

Keep acquisition separate from interpretation. “This PNG came from dashboard export X” is provenance. “The red graph means the database was overloaded” is a hypothesis.

Break it deliberately

Mutate one fixture at a time:

• claim a different content digest;
• set image width to zero;
• provide an audio end time before its start;
• reuse an evidence ID for different bytes;
• mark untrusted user text as system-authored.

The first violated invariant should be reported at intake. Do not let malformed evidence reach a vision or language model and hope it notices.

Completion proof

For each modality, trace bytes → validated payload → envelope → manifest. Explain which values own large buffers and when Arc<[u8]> would be appropriate for parallel OCR and embedding.

Deep reference: The multimodal evidence pipeline.

Next: Day 11 — Images and Audio →.