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.

Body Format (key 46)

The sender MUST set key 46 from the intended compose format, not infer it from message contents. The private Meta object (Tell manifest file_type=0) carries this field; Tell packet layouts, tell_type and manifest file_type remain unchanged. Absent means native CBDF, preserving existing styled documents.

Values 1–3 use the existing Text section framing, with the source text carried literally inside STX/ETX. CBDF transport escaping/framing is decoded before interpreting the source. CBDF styles, list inference and automatic URL conversion MUST NOT alter this source. Normalize CRLF and bare CR to LF. The field describes the entire body, not attachments or the subject.

Receivers MUST preserve the original source for drafts, editing and forwarding. Rendering is a temporary view. Markdown uses CommonMark; optional extensions may vary by client. HTML clients MAY support a documented static subset. Scripts, active content and automatic external resource requests MUST be disabled.

Unknown or unsupported values MUST fall back to visibly labeled source text. Older clients MAY ignore key 46 and display all source as plain text; faithful formatted rendering is not required for compatibility. Duplicate key 46 or lengths other than 1 are malformed; receivers MUST NOT select an active renderer from a malformed field. Meta-only objects MUST omit key 46.

2E 01 02   ; key 46, value length 1, Markdown source

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.