QMail — Pending Protocol Changes

September 2026 implementation clarification: large-attachment durability, retry and compatibility checklist. This changes no base packet layout and makes no claim about current fleet deployment.

Compatibility verdict

No wire-format change on this page breaks a correctly-written existing client. Every new request field lives in a byte that was previously required to be zero, and every new field is opt-in: a client that keeps sending zero gets byte-identical behaviour to today. Every new response field is either behind a flag the client itself set, or in a response byte range that is currently all zeros.

That is the wire. Four changes on this page can still change what an existing client experiences, and they are the ones worth the review time:

Three of the four are behind an operator switch that is off in the shipped build, so they can be reviewed and staged separately from the deploy. R-2 is not — it goes live with the binary. It is the single item on this page that most deserves a decision before anything ships.

Status legend

Summary table

1. Wire additions

1.1 object_begin (76) — retention_code_plus1 at offset 125

LIVE ON CANARY. The first byte of the seven reserved bytes at offsets 125–131 now carries a storage-duration code. The remaining six bytes (126–131) are still required to be zero.

When a code is present it wins over the seconds field; the seconds field is not consulted. A code longer than the operator's configured maximum, or a request for "forever" on a node that does not sell it, returns ERROR_RETENTION_UNAVAILABLE (235) — the code is valid, the operator just does not offer it. Clamp and retry with a shorter code rather than failing the upload.

Compatibility: safe. A client that keeps sending seven zero bytes takes the legacy path unchanged. The only behavioural difference for such a client is that byte 125 is no longer validated as zero — a request that used to be rejected with ERROR_INVALID_PARAMETER for a stray non-zero byte there is now interpreted instead. No shipped client sends a stray value.

1.2 The shared duration-code table

LIVE ON CANARY. One byte encodes a retention period. Five contiguous bands, strictly monotonic across codes 1–75, exact integer seconds, no calendar arithmetic: a month is 30 days and a year is 365 days — the same constants the server has always used for its default and maximum retention.

Monotonicity is deliberate: an operator cap can be applied with a single comparison, and the largest sellable code can be advertised as a single byte.

The same table is used in three places, with one deliberate difference:

• object_begin (76) and object_extend_retention (90) use the shifted form (code + 1).
• Upload (70) and Upload Large (75) use the raw code, because that byte predates the shift — and there 0 means "server default", never "forever".

1.3 object_commit (79) — async_ok at offset 89, and status 246

LIVE ON CANARY. Committing a very large object means hashing and flushing every byte. For a 100 GB object that is roughly 43 seconds of hashing plus around 90 seconds of fsync — longer than any reasonable socket timeout. The commit therefore moves to a background worker, and the client is told to poll.

With async_ok = 1, a commit that cannot complete inline returns STATUS_COMMIT_IN_PROGRESS (246) with no response body. The client then polls object_transfer_status (78) until the transfer reaches its committed state. Re-issuing the commit while the worker is still running returns 246 again; re-issuing it after success returns the original commit response, so a lost 246 is harmless.

Compatibility: safe, and deliberately so. 246 is never sent unsolicited; a client that sends async_ok = 0 can never see it. The trade-off is explicit: such a client keeps today's behaviour, including today's failure mode, where a commit longer than the socket timeout surfaces as a network error and is resumed later.

1.4 object_get_range (82) — verification flag and chunk hashes

LIVE ON CANARY. Today a download is protected by one SHA-256 over the whole object. At 100 GB, a single flipped bit costs a 100 GB re-download and gives no way to tell which server served the bad byte. The server can now publish a per-chunk hash sidecar and hand back the hashes covering the range it just served.

Request — request_flags at offset 81, previously required to be zero:

Response — response_flags gains one bit:

When bit 2 is set, the response body is the fixed 104-byte header, then data_length bytes of payload, then this block:

Setting the flag also makes the server check itself: it re-hashes the covering chunks before serving them and returns ERROR_OBJECT_CORRUPT (164) rather than handing over bytes it knows are wrong. A clean 164 lets the client heal that stripe from another RAIDA; silently served rot cannot be detected at all.

Hashes are only available for objects stored through the streaming path that carry a sidecar. For an older object, or one held in memory, the flag is accepted, the range is served normally, and bit 2 stays clear. A client must handle "asked for hashes, did not get them".

Compatibility: safe. A client sending request_flags = 0 gets a byte-identical response to today.

1.5 Subscribe (85) — v2 payload with 64-bit credit

LIVE ON CANARY. The v1 credit field is an unsigned 32-bit byte count, capped at about 4.29 GB. That cannot express the price of a single 100 GB upload, let alone one multiplied by a storage duration. A second payload shape carries a 64-bit value.

The two shapes are told apart by the first payload byte, immediately after the 48-byte preamble:

The marker byte is 0x56, ASCII 'V'. Read as a signed denomination that is +86, which is outside the valid range of −8 to +6, so no well-formed v1 payload can begin with it and the two shapes can never be confused. A v2 payload whose version byte is not 0x02, or whose entry array is not a whole number of 13-byte entries, returns ERROR_INVALID_PACKET_LENGTH (16).

The credit unit follows the billing mode. While duration billing is off, one unit is one byte, exactly as in v1. When it is on, one unit is one byte-period: an upload of S bytes held for P billing periods consumes S × P units. Balances saturate rather than overflow.

Compatibility: safe. A v1 payload is parsed by exactly the code path it uses today.

1.6 object_extend_retention (90) — new command

LIVE ON CANARY. Buys more storage time for an already-committed object without re-uploading it. Fully specified on its own page: object_extend_retention (cmd 90).

Compatibility: safe. A new command code; a server that does not have it answers ERROR_INVALID_COMMAND (6), which is what clients already see for any unimplemented code.

1.7 Device links (86–89) — four new commands

LIVE ON CANARY. These let one user run QMail on several devices, each holding its own identity coin, so rotating one device's password does not lock out the others. Devices link under an "authority" mailbox — the public address — and a subordinate's coin is a device credential, never a visible identity.

Each device authenticates with its own coin through the ordinary QMail preamble. A maximum of eight devices share one authority, including the authority itself. New status codes: ERROR_LINK_NOT_FOUND (173), ERROR_NOT_LINK_ADMIN (174), ERROR_BAD_PAIRING_CODE (175), ERROR_DEVICE_LIMIT (176).

These four commands are intentionally live while the behaviour that uses them is switched off, so devices can pair before the mailbox rewrite is turned on.

Compatibility: safe. New command codes, and no existing command changes while the rewrite stays off.

1.8 Upload (70) and Upload Large (75) — the duration byte, a size cap, and expiry

LIVE ON CANARY. This is the item with real client exposure. Three changes to the two legacy upload commands, none of which alters a single byte of the wire format:

The duration byte is now decoded

Byte 81 of cmd 70, and byte 65 of cmd 75, has always been documented as "Storage retention code" and has always been ignored — the current page even says so: "the byte is logged but the server does not yet enforce retention". It is now interpreted, using the shared duration-code table in its raw form:

A one-gigabyte accumulation cap on cmd 75

Pages uploaded under a single GUID now accumulate against a 1 GiB ceiling. Exceeding it returns ERROR_QUOTA_EXCEEDED (227). The reasoning is that large files ride the object-transfer path (76–84), so a modest ceiling on the legacy paged path constrains only abuse — but any existing caller that assembles more than 1 GiB through cmd 75 stops working at the boundary.

Legacy uploads are registered for expiry

Uploads through cmd 70 and 75 are now recorded in the object lifecycle index with their retention, so the reaper can remove them on schedule. Until now nothing recorded when such a file should leave, and they stayed on disk forever.

2. Behaviour changes behind operator switches

None of these alter a request or response layout. They are listed because they change what a client observes, and because each is a separate flip.

2.1 Streaming storage — statuses 162 and 165

SWITCHED OFF. object_put_range writes into a preallocated staging file instead of holding the object in memory, which is what allows an object larger than RAM. Two new failures become reachable at object_begin:

• ERROR_STORAGE_EXHAUSTED (162) — the server physically cannot reserve the space. Not retryable here; pick another server, and pick it before sending payload. Distinct from ERROR_STORAGE_FULL (230), which is a policy refusal: 162 is "cannot", 230 is "will not".
• ERROR_RESUME_MISMATCH (165) — a re-begin reused a transfer ID but declared a different size, hash, or file type. A client bug or a stale ID, not a transient. Do not retry it in a loop; start a new transfer.

2.2 The reaper deletes expired objects

SWITCHED OFF. The expiry index is always maintained; this switch gates the unlink. Covers expired objects and abandoned staging files. See R-1 for the exposure.

2.3 Duration billing

SWITCHED OFF. Storage is priced by size × duration rather than size alone. The number of billing periods is ceil(retention_seconds / fee_period_seconds), with "forever" billed at the 30-year figure rather than free. As shipped, the billing period is zero, which means one period — the exact pre-existing one-time fee.

Rate and period are per-node operator settings, so the nine QMail servers may legitimately price the same object differently. A client must sum the per-server charges rather than multiplying one server's answer.

2.4 Zero-locker funding — statuses 170 and 171

SWITCHED OFF. An upload with an all-zero locker code draws on prepaid credit instead of a funded locker, in a fixed precedence: a free floor for small stripes, then subscription credit, then a rolling welfare allowance, then refusal. Already documented in full on the object_begin page, including the response bytes at 74–79 and the parser change described in R-4. New statuses: ERROR_NO_STORAGE_CREDIT (170), ERROR_WELFARE_EXHAUSTED (171).

2.5 Linked-device mailbox rewrite

SWITCHED OFF. When on, a subordinate device's Ping and Peek serve the authority's inbox, its Tell is stamped as coming from the authority, and — the significant one — Ping stops deleting. Each tell carries a per-device delivery bitmap and is removed once every active device has collected it, or after a 30-day backstop.

That is a real change in Ping's contract, from "fetch and drain" to "fetch and mark". While the switch is off, Ping remains destructive exactly as documented today. The four link commands stay live either way.

3. Transport — TCP connection reuse

SWITCHED OFF. Today the server closes the TCP connection after writing each response. With this on, it keeps the connection open and serves further requests on it.

The benefit is on the client side and only materialises once the client also stops opening a socket per request. A 100 GB object moved in 8 MB requests is 12,800 handshakes and 12,800 cold starts otherwise.

4. New status codes

There is no central status-code table on this site — each command page lists the codes it can return. These are the codes the changes above introduce, and where each can actually appear.

5. Declared but not implemented

6. Rollout order

The published spec should describe production. The order that keeps that true:

1. Approve this page. Nothing below happens first.
2. Settle R-2 — confirm what every uploader actually writes into the duration byte, since that change is not behind a switch.
3. Settle R-1 — choose the default retention for legacy uploads, knowing it applies to files already on disk.
4. Ship the binary with every switch off. At that point the fleet behaves as documented today, apart from items 1.8 and any new command codes, which are additive.
5. Fold each approved change into its own command page as its switch is flipped — not before. A page describing behaviour that is not yet live is worse than a stale page.
6. Write the four missing device-link pages before that feature is announced.