CBDF Specification: Meta Section

1. Overview

The Meta section is the first section of every CBDF document. It is the document envelope: identity, routing, previews, format options, and (in local storage only) Tell/RAIDA attestations.

Meta is never compressed. Clients can read it without decompressing Styles/Text. In QMail, private Meta may be uploaded as Tell manifest file_type=0, separate from the public Tell notification.

2. Meta Format

[Pair Count: 2 bytes LE]
[Key ID: 1][Value Length: 1][Value: N bytes]  × Pair Count

• Pair count includes every repeated key (e.g. each To recipient).
• Value length is 0–255 only. There is no extended-length sentinel. A length of 0xFF means 255 value bytes. Extended length would desynchronize deployed Phase I skippers.
• Unknown keys: skip by reading key + length + value (forward compatible).
• Keys may appear in any order. Encoders SHOULD emit key 0 then key 30 early.
• Values larger than 255 bytes belong in Text, Resources, or extension sections — not Meta (without a future key-30 format bump).

3. Key Registry

3A. Phase I keys (deployed — must match qmail_cbdf.h)

* = Required for QMail documents. Keys 6–11, 15–18, 20–24, 26–29 reserved.

3B. Phase II keys

When key 33 = 1 (meta-only), keys 31/32/37/40/42/43 are meaningless and MUST be absent.

4. Feature Flags (keys 42 and 43)

Both keys are little-endian bitfields of 1–4 bytes with trailing zero bytes omitted. Absent key means 0.

Encoders MUST set bits only for features actually used (truthful encoding).

5. Content Hash (key 45)

[alg:1][digest:N]
  alg 1 = MD5,     N = 16
  alg 2 = SHA-256, N = 32
  0, 3–255 reserved

Canonical hash input (decompressed representation, hashed verbatim):

[StylesLen:4 LE][Styles bytes] FS [TextLen:4 LE][Text bytes]
[ResourcesLen:4 LE][Resources bytes]

This matches the decompressed Styles+Text blob (including the interior FS) plus the Resources section. Exclude Meta, outer FS markers, and Logic. When uncompressed, the Styles+Text portion is identical to the on-wire bytes after the first FS through Text.

6. Mailbox Address Format

All mailbox fields (To, CC, From, Verified Sender) are exactly 7 bytes:

CloudCoin mailbox addresses MUST encode the coin-group field exactly as the deployed v0 encoder does: bytes 00 06 at offsets 0–1. This is the normative CBDF wire form for CloudCoin mailbox fields.

7. Tell Integration and Receiver Annotations

Claims vs attestations: Meta keys 0–199 are sender-written claims. The QMail Tell (Peek/Ping) carries RAIDA-confirmed GUID, sender, timestamp, locker, servers, and manifest. Integration is cross-check + annotate, never merge on the wire.

7A. Cross-check rules (receive time)

1. GUID: Tell email_id ≠ key 1 → hard reject the object.
2. Sender: Tell ≠ key 19 → display Tell identity; flag Meta as conflicting claim. ("Unverified" is for documents with no Tell.)
3. Timestamp: Tell is authoritative sent time; Meta 25/41 is sender clock; skew > 48h SHOULD be surfaced.
4. Attachments: Tell manifest wins for downloadable set; Meta supplies display names.
5. CRC: fail integrity → labeled plain-text fallback, never partial styled phishing render.
6. Badges: verified UI derives only from Tell-derived annotations 200–219.

7B. Receiver annotation keys (200–219)

Written only by the receiving client into local storage. Tell multi-byte scalars are big-endian on the wire; re-encode to LE in annotations except raw opaque entries.

8. Styled Subject

1. Key 2 — plain UTF-8 (search, notifications, extraction)
2. Key 37 — text style for inbox listing
3. SOH block inside Text — fully styled subject when opened

Plain-text extraction of the SOH block SHOULD equal key 2 (truncation aside). Clients MAY flag a mismatch as spoof risk.

9. Timestamp Policy

Key 41 = uint64 LE Unix seconds (not milliseconds). Key 25 remains required for Phase I compatibility and equals key 41's low 32 bits when both are present. Strict parsers verify truncation consistency and prefer key 41.