# Large attachments: existing v1 contract and implementation checklist

Date: 2026-09-06. Documentation clarification only; no new wire behavior.

The frozen `qmail-object-transfer-v1.json` and its canonical vectors remain
unchanged. The command pages specify the base contract. This note distinguishes
that contract from implementation remedies and previously documented extensions.
It is not evidence of deployment on any node.

## Size and integrity scope

An exact 25 GB attachment is 25,000,000,000 logical bytes (not 25 GiB).
With 11 data stripes and one XOR parity stripe, each stored stripe is
2,272,727,273 bytes; all 12 together carry 27,272,727,276 bytes. Headers,
metadata and transport overhead are additional. Object sizes/offsets are uint64;
the negotiated range limit is independent of the logical file size.

The sender prepares immutable input, compression, stripe geometry, parity and
hashes. The server authenticates and independently verifies the bytes it stores;
it does not reconstruct or decompress attachments. Identical overlapping PUTs
are idempotent; different overlapping bytes return ERROR_RANGE_CONFLICT (224).
COMMIT verifies the actual complete stored stripe, not merely a cached hash of
an earlier sequence of writes. Durable accepted coverage must survive restart.

TELL continues to use manifest v1, 16-byte entries with CRC32 present. Object ID
is the message GUID, generation is 1 and file type comes from the manifest.
The CRC covers the same logical payload used to prepare the advertised stripes.
CRC32 is not an authenticated cryptographic digest; stripe parity/interleaving
is not encryption. Per-server SHA-256 does not create a sender-authenticated
logical SHA-256 in the existing manifest. An investor end-to-end SHA-256 check
is an independent test, not a new manifest field.

## Retry and restart interpretation

The authenticated owner and Transfer ID identify one attempt. Persist that ID
and all immutable BEGIN fields before dispatch. Retry exactly those fields
(fresh framing material and request ID are allowed), preserving the original
accepted chunk size, retention and expiry. Never extend expiry by restarting.
Payment remains keyed by owner + Object ID + locker code, not Transfer ID.
Ambiguous payment dispatch requires reconciliation, never automatic recharging.

An unanswered BEGIN/COMMIT is not proof of failure. STATUS is authoritative for
accepted ranges. Timeout/transport error is not an empty bitmap. Unknown (222),
expired (223), overlapping-byte conflict (224), and immutable-attempt conflict
(234) are different outcomes. An exact BEGIN can reconcile an unknown attempt;
it cannot lawfully revive an expired/aborted attempt or change immutable fields.
After acceptance query STATUS again before scheduling missing ranges. Preserve
original commit metadata for an exact duplicate COMMIT, and preserve aborted
tombstones through the already specified terminal-record retention interval.

Pausing locally does not send ABORT. An explicit cancellation may send ABORT.
Finite server expiry bounds offline recovery. A durable client parent job can
resume preparation, child transfers and pending TELLs after restart without
changing these commands. A parent job is a client-local implementation detail.

Only announce locations that can reconstruct every manifest file. Successful
delivery with 11 available stripes does not advertise 12-copy redundancy. Late
repair does not update an already sent location list by itself. Preserve the
existing TELL replay/edit rules; this note defines no location-update extension.

## Previously documented extensions, not newly activated here

`qmail-protocol-changes.php` describes async_ok at COMMIT offset 89/status 246,
disk-storage errors, duration fields and TCP connection reuse. Those are separate
from the frozen base vectors. Base clients keep reserved request fields zero;
246 must not be returned unless the caller opted in. A client using a documented
extension needs a compatible server or a tested base-mode fallback. TCP readers
must consume declared lengths and reconnect when a peer closes a connection;
connection reuse is not permission to retry a non-idempotent command blindly.

Historical labels such as LIVE ON CANARY and SWITCHED OFF describe a dated
review, not verified present fleet state. The inspected raidax source enables
streaming; that alone does not establish which binaries/configurations the 12
servers run. Record build hashes, switches and live capabilities at rehearsal.
Do not modify frozen vectors to hide this distinction. No new command, reserved
bit, status code or manifest version is assigned by this clarification.

## Compatible implementation classification

The Qmail audit IDs refer to `docs/findings/potential-problems-large-downloads.txt`.

| Findings | Remedy | Compatibility class |
| --- | --- | --- |
| F01 | Durable parent send/outbox and immutable preparation | Client-local format and orchestration |
| F02, F03, F14 | Reuse attempts, distinguish STATUS failures, elapsed-time pause | Existing command semantics |
| F04, F06, F13 | Durable transfer/terminal journal, ordered sync, coordinated reaper | Server-local storage/lifecycle |
| F05 | Compare stored overlaps and hash actual committed bytes | Existing integrity semantics |
| F07 | Compute CRC from the immutable prepared logical payload | Existing manifest semantics |
| F08 | Consistent server set and explicit degraded delivery state | Client scheduling/UI |
| F09, F15 | Pending is not success; display all supported servers | Client UI/local representation |
| F10 | Bit-exact faster shared codec | Implementation only |
| F11 | Shared disk budgeting, archive promotion and cleanup | Local storage/lifecycle |
| F12 | Persisted generation lookup and accurate capacity accounting | Existing admission/ownership semantics |

Journal versions, crash-test fixtures and local block hashes are not wire
extensions. A sender-authenticated logical digest, transfer renewal, richer
commit status, location refresh or streaming BEGIN would require a separate
proposal, compatibility review, schema/vectors and documentation commit before
implementation. None is a prerequisite assigned by this checklist.