Module envelope 

Envelope v2 — one validator, three uses (V8 S4).

Every bulk record stream this store produces carries an optional single-line JSON envelope header as its first line:

{"wm_envelope":{"count":5,"created_at":"2026-08-31T16:00:00+00:00","format_version":2,"generator":"wm 9.0.0","kind":"session_export"}}

Rules:

• Writers always emit the header; readers accept streams with or without one. Bare v1 payloads (plain record JSONL) stay importable forever — the header is additive, never a format break.
• The wm_envelope top-level key is the discriminator. Record types (Memory et al.) never serialize that key, so a header line can never collide with a record line.
• A header with format_version newer than ENVELOPE_FORMAT_VERSION is refused: a forward stream may carry records this build cannot parse honestly, and silently skipping records is the failure mode this module exists to prevent.
• count is advisory but checked: a mismatch is a warning, never a refusal (partial streams are still worth importing).

Uses: session.export (header line in the JSONL stream), session.import (validation), wm backup/wm restore (envelope.json beside SHA256SUMS). All three go through this module — there is no second implementation.

Structs

EnvelopeHeader

Header of an enveloped record stream.

StreamScan

Scan result for a whole stream.

Enums

HeaderRead

Result of reading a header line.

Constants

ENVELOPE_FORMAT_VERSION

The envelope format this build writes. Readers accept this version and any older header; newer headers are refused.

ENVELOPE_KEY

Top-level discriminator key on the header line.

Functions

read_header_line

Read the first non-empty line of a stream as a potential header.

scan_stream

Scan a whole stream: header, per-line JSON validity, record count.