Module mailbox 

Cross-process session mailbox for peer Q&A. Cross-process session mailbox: peer Q&A between concurrent CLI sessions.

Layout inside a session directory:

• mailbox/<message-id>.json — unread messages, one atomic file each, so concurrent senders never interleave.
• mailbox/read/<message-id>.json — acknowledged or expired messages, kept briefly for audit and reaped by age on every drain.

Delivery is at-least-once: the receiver drains, injects into its turn, then acknowledges. A crash between inject and ack redelivers on the next drain. Only live sessions (see retention::session_dir_is_live) accept mail; sending to an unknown or dead session fails closed instead of piling up questions nobody will read.

Structs

InboxDrain

Result of draining an inbox: live messages to inject, ids of expired messages moved aside, and a count of quarantined malformed files.

MailMessage

A persisted mailbox message as read from disk.

MailOption

One suggested choice for a structured question.

MailQuestion

One structured question inside a question message.

MailReceipt

Receipt for an accepted message.

NewMail

A validated, sendable mailbox message under construction.

Enums

MailKind

Kind of a mailbox message.

Constants

DEFAULT_TTL_SECS

Default message time-to-live in seconds.

MAILBOX_DIR

Inbox directory inside a session directory.

MAILBOX_SCHEMA_VERSION

Schema version for mailbox envelopes.

MAX_INBOX_DEPTH

Maximum unread messages per inbox; sends beyond this fail closed.

MAX_MAIL_BYTES

Maximum serialized envelope size in bytes.

MAX_OPTIONS

Maximum options per question (mirrors request_user_input).

MAX_OPTION_DESCRIPTION_CHARS

Maximum option description in characters.

MAX_OPTION_LABEL_CHARS

Maximum option label in characters.

MAX_QUESTIONS

Maximum structured questions per question message (mirrors request_user_input).

MAX_QUESTION_CHARS

Maximum question text in characters.

MAX_QUESTION_ID_CHARS

Maximum question id in characters.

MAX_TEXT_CHARS

Maximum body/answer text in characters.

MAX_TTL_SECS

Maximum message time-to-live in seconds.

MIN_TTL_SECS

Minimum message time-to-live in seconds.

READ_RETENTION_SECS

How long acknowledged/expired messages are kept for audit, in seconds.

Functions

ack_mail

Acknowledge a delivered message, moving it to the read archive. Returns false when the message was already gone (double-ack is safe).

drain_inbox

Drain an inbox: return live messages oldest-first, move expired and malformed files to the read archive, and reap aged read messages.

find_mail

Find a message by id in the live inbox or the read archive.

read_mail

Fetch one unread message by id without acknowledging it.

send_mail

Send a validated message to a live session’s inbox.