envelope-audit

name	envelope-audit
description	Audit ExecutionEnvelope implementations for completeness and immutability. Use when modifying the envelope crate or reviewing fetch code that constructs envelopes.
version	0.1.0
user-invocable	true
allowed-tools	Read Grep Glob
argument-hint	[file path]

Execution Envelope Audit

The ExecutionEnvelope is the critical innovation — the missing abstraction in every crawler today. This audit verifies it is correctly implemented and used.

Checks

Completeness

Every envelope must capture:

• seed — the crawl seed that produced this fetch
• timestamp — CaptureInstant (wall + logical)
• request_headers — full request headers as sent
• dns_snapshot — resolved addresses, TTL, nameserver
• tls_fingerprint — protocol version, cipher suite, cert chain hash
• browser_config — viewport, user agent, JS enabled (None for raw HTTP mode)

Immutability

• No &mut self methods on the envelope after construction
• All fields are private with getter-only access (or the struct is pub with all fields pub but no DerefMut)
• No Default implementation (envelopes must be explicitly constructed with all fields)
• Clone is derived but never used to create modified copies

Usage

• Every fetch call site constructs an envelope BEFORE the fetch
• The envelope is passed by reference (&ExecutionEnvelope), never consumed
• The envelope is serialized into the WARC++ envelope record
• No fetch occurs without an associated envelope

Serialization

• Round-trip: serialize then deserialize produces identical envelope
• Schema version field present for forward compatibility

Output

Report completeness score (0-6 fields present), immutability violations, and usage gaps.