{
  "schema": "cloudcoin.qmail.object-transfer",
  "status": "stable",
  "version": 1,
  "frozen_at": "2026-06-11",
  "byte_order": "big-endian",
  "normative_page": "../qmail-object-transfer-v1.php",
  "transport": {
    "required": "tcp",
    "encryption_type": 1,
    "encryption": "AES-128-CTR",
    "request_header_size": 32,
    "response_header_size": 32,
    "clear_terminator_hex": "3e3e",
    "body_length_includes_terminator": true,
    "request": {
      "framing_version": 1,
      "framing_version_offset": 9,
      "body_length_offset": 10,
      "body_length_size": 4,
      "reserved_offset": 14,
      "reserved_size": 2,
      "legacy_length_sentinel_offset": 22,
      "legacy_length_sentinel_hex": "ffff"
    },
    "response": {
      "framing_version": 1,
      "framing_version_offset": 8,
      "body_length_offset": 9,
      "body_length_size": 4,
      "reserved_offset": 13,
      "reserved_size": 3,
      "legacy_execution_time_present": false,
      "error_body_length": 0,
      "post_decryption_error_challenge": "normal_challenge_hash",
      "tcp_required_error_challenge": "sixteen_zero_bytes"
    }
  },
  "request_body": {
    "qmail_preamble_size": 48,
    "command_payload_offset": 48,
    "encrypted_bytes": "qmail_preamble + command_header + optional_data",
    "terminator_encrypted": false
  },
  "response_body": {
    "command_payload_offset": 0,
    "encrypted_bytes": "command_header + optional_data",
    "terminator_encrypted": false
  },
  "common_prefix": {
    "size": 16,
    "fields": [
      {"name": "protocol_version", "offset": 0, "size": 2, "type": "uint16", "value": 1},
      {"name": "command_header_length", "offset": 2, "size": 2, "type": "uint16"},
      {"name": "flags", "offset": 4, "size": 4, "type": "uint32", "value": 0},
      {"name": "request_id", "offset": 8, "size": 8, "type": "uint64", "response": "echo"}
    ]
  },
  "hash_algorithms": {
    "1": "sha256"
  },
  "commands": {
    "76": {
      "name": "object_begin",
      "constraints": [
        "transfer_id is client-generated, nonzero, and cryptographically random",
        "transfer identity is scoped by authenticated owner plus transfer_id",
        "an exact retry excluding request_id does not reserve or initiate payment twice",
        "reuse with different command-specific fields returns ERROR_TRANSFER_CONFLICT",
        "an aborted or expired attempt requires a new transfer_id",
        "requested_retention_seconds == 0 selects the server default",
        "a nonzero requested_retention_seconds is accepted exactly or returns ERROR_RETENTION_UNAVAILABLE",
        "payment is keyed by authenticated owner, object_id, and locker_code",
        "file_type, transfer_id, and generation are not part of the Phase I payment key",
        "create requires expected_generation == 0 and target_generation > 0",
        "replace requires expected_generation == current_generation",
        "replace requires target_generation > expected_generation",
        "commit publishes exactly target_generation"
      ],
      "request": {
        "header_size": 144,
        "fields_after_common_prefix": [
          {"name": "transfer_id", "offset": 16, "size": 16, "type": "bytes", "generated_by": "client", "all_zero_allowed": false},
          {"name": "object_id", "offset": 32, "size": 16, "type": "bytes"},
          {"name": "locker_code", "offset": 48, "size": 16, "type": "bytes"},
          {"name": "file_type", "offset": 64, "size": 1, "type": "uint8"},
          {"name": "requested_retention_seconds", "offset": 65, "size": 8, "type": "uint64", "zero_means": "server_default"},
          {"name": "hash_algorithm", "offset": 73, "size": 1, "type": "uint8", "value": 1},
          {"name": "operation", "offset": 74, "size": 1, "type": "uint8", "values": {"0": "create", "1": "replace"}},
          {"name": "storage_class", "offset": 75, "size": 2, "type": "uint16", "zero_means": "server_default"},
          {"name": "reserved", "offset": 77, "size": 7, "type": "bytes", "value": "zero"},
          {"name": "preferred_chunk", "offset": 84, "size": 4, "type": "uint32", "zero_means": "server_preference"},
          {"name": "total_size", "offset": 88, "size": 8, "type": "uint64", "minimum": 1},
          {"name": "expected_generation", "offset": 96, "size": 8, "type": "uint64", "create_value": 0},
          {"name": "target_generation", "offset": 104, "size": 8, "type": "uint64", "minimum": 1},
          {"name": "object_hash", "offset": 112, "size": 32, "type": "bytes"}
        ]
      },
      "response": {
        "header_size": 80,
        "fields_after_common_prefix": [
          {"name": "transfer_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "accepted_chunk", "offset": 32, "size": 4, "type": "uint32"},
          {"name": "max_parallel", "offset": 36, "size": 2, "type": "uint16"},
          {"name": "storage_class", "offset": 38, "size": 2, "type": "uint16"},
          {"name": "hash_algorithm", "offset": 40, "size": 1, "type": "uint8"},
          {"name": "operation", "offset": 41, "size": 1, "type": "uint8"},
          {"name": "expires_at", "offset": 42, "size": 8, "type": "uint64"},
          {"name": "base_generation", "offset": 50, "size": 8, "type": "uint64"},
          {"name": "target_generation", "offset": 58, "size": 8, "type": "uint64"},
          {"name": "accepted_retention_seconds", "offset": 66, "size": 8, "type": "uint64", "zero_means": "no_scheduled_expiry"},
          {"name": "reserved", "offset": 74, "size": 6, "type": "bytes", "value": "zero"}
        ]
      }
    },
    "77": {
      "name": "object_put_range",
      "request": {
        "header_size": 80,
        "data_follows_header": true,
        "fields_after_common_prefix": [
          {"name": "transfer_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "offset", "offset": 32, "size": 8, "type": "uint64"},
          {"name": "data_length", "offset": 40, "size": 4, "type": "uint32", "equals": "data.size"},
          {"name": "hash_algorithm", "offset": 44, "size": 1, "type": "uint8", "value": 1},
          {"name": "reserved", "offset": 45, "size": 3, "type": "bytes", "value": "zero"},
          {"name": "range_hash", "offset": 48, "size": 32, "type": "bytes", "covers": "data"}
        ]
      },
      "response": {
        "header_size": 64,
        "fields_after_common_prefix": [
          {"name": "transfer_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "offset", "offset": 32, "size": 8, "type": "uint64"},
          {"name": "data_length", "offset": 40, "size": 4, "type": "uint32"},
          {"name": "range_flags", "offset": 44, "size": 4, "type": "uint32", "bits": {"0": "duplicate_retry"}},
          {"name": "received_unique", "offset": 48, "size": 8, "type": "uint64"},
          {"name": "reserved", "offset": 56, "size": 8, "type": "bytes", "value": "zero"}
        ]
      }
    },
    "78": {
      "name": "object_transfer_status",
      "request": {
        "header_size": 48,
        "fields_after_common_prefix": [
          {"name": "transfer_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "cursor", "offset": 32, "size": 8, "type": "uint64", "zero_means": "first_response"},
          {"name": "range_mode", "offset": 40, "size": 1, "type": "uint8", "values": {"0": "missing", "1": "received"}},
          {"name": "reserved_1", "offset": 41, "size": 1, "type": "uint8", "value": 0},
          {"name": "max_ranges", "offset": 42, "size": 2, "type": "uint16", "minimum": 1, "maximum": 256},
          {"name": "reserved_2", "offset": 44, "size": 4, "type": "bytes", "value": "zero"}
        ]
      },
      "response": {
        "header_size": 72,
        "entry_size": 16,
        "entry_count_field": "range_count",
        "fields_after_common_prefix": [
          {"name": "transfer_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "transfer_state", "offset": 32, "size": 1, "type": "uint8", "values": {"0": "receiving", "1": "ready", "2": "committed", "3": "aborted", "4": "expired"}},
          {"name": "range_mode", "offset": 33, "size": 1, "type": "uint8"},
          {"name": "response_flags", "offset": 34, "size": 2, "type": "uint16", "bits": {"0": "more_entries"}},
          {"name": "target_generation", "offset": 36, "size": 8, "type": "uint64"},
          {"name": "total_size", "offset": 44, "size": 8, "type": "uint64"},
          {"name": "received_unique", "offset": 52, "size": 8, "type": "uint64"},
          {"name": "next_cursor", "offset": 60, "size": 8, "type": "uint64", "zero_means": "no_more_entries"},
          {"name": "range_count", "offset": 68, "size": 2, "type": "uint16", "maximum": 256},
          {"name": "reserved", "offset": 70, "size": 2, "type": "bytes", "value": "zero"}
        ],
        "entry_fields": [
          {"name": "offset", "offset": 0, "size": 8, "type": "uint64"},
          {"name": "length", "offset": 8, "size": 8, "type": "uint64"}
        ]
      }
    },
    "79": {
      "name": "object_commit",
      "constraints": [
        "an exact retry after successful commit returns the original commit response",
        "a committed transfer retried with different total_size, hash_algorithm, or object_hash returns ERROR_TRANSFER_CONFLICT"
      ],
      "request": {
        "header_size": 80,
        "fields_after_common_prefix": [
          {"name": "transfer_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "total_size", "offset": 32, "size": 8, "type": "uint64"},
          {"name": "hash_algorithm", "offset": 40, "size": 1, "type": "uint8", "value": 1},
          {"name": "reserved", "offset": 41, "size": 7, "type": "bytes", "value": "zero"},
          {"name": "object_hash", "offset": 48, "size": 32, "type": "bytes"}
        ]
      },
      "response": {
        "header_size": 96,
        "fields_after_common_prefix": [
          {"name": "object_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "file_type", "offset": 32, "size": 1, "type": "uint8"},
          {"name": "object_state", "offset": 33, "size": 1, "type": "uint8", "value": 1},
          {"name": "storage_class", "offset": 34, "size": 2, "type": "uint16"},
          {"name": "generation", "offset": 36, "size": 8, "type": "uint64"},
          {"name": "total_size", "offset": 44, "size": 8, "type": "uint64"},
          {"name": "hash_algorithm", "offset": 52, "size": 1, "type": "uint8", "value": 1},
          {"name": "reserved", "offset": 53, "size": 3, "type": "bytes", "value": "zero"},
          {"name": "object_hash", "offset": 56, "size": 32, "type": "bytes"},
          {"name": "committed_at", "offset": 88, "size": 8, "type": "uint64"}
        ]
      }
    },
    "80": {
      "name": "object_abort",
      "request": {
        "header_size": 32,
        "fields_after_common_prefix": [
          {"name": "transfer_id", "offset": 16, "size": 16, "type": "bytes"}
        ]
      },
      "response": {
        "header_size": 48,
        "fields_after_common_prefix": [
          {"name": "transfer_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "transfer_state", "offset": 32, "size": 1, "type": "uint8", "value": 3},
          {"name": "reserved", "offset": 33, "size": 15, "type": "bytes", "value": "zero"}
        ]
      }
    },
    "81": {
      "name": "object_info",
      "request": {
        "header_size": 48,
        "fields_after_common_prefix": [
          {"name": "object_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "file_type", "offset": 32, "size": 1, "type": "uint8"},
          {"name": "reserved", "offset": 33, "size": 7, "type": "bytes", "value": "zero"},
          {"name": "generation", "offset": 40, "size": 8, "type": "uint64", "zero_means": "latest_committed"}
        ]
      },
      "response": {
        "header_size": 112,
        "fields_after_common_prefix": [
          {"name": "object_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "file_type", "offset": 32, "size": 1, "type": "uint8"},
          {"name": "object_state", "offset": 33, "size": 1, "type": "uint8", "value": 1},
          {"name": "storage_class", "offset": 34, "size": 2, "type": "uint16"},
          {"name": "hash_algorithm", "offset": 36, "size": 1, "type": "uint8", "value": 1},
          {"name": "acl_version", "offset": 37, "size": 1, "type": "uint8", "value": 1},
          {"name": "object_flags", "offset": 38, "size": 2, "type": "uint16", "bits": {"0": "volatile_storage"}},
          {"name": "generation", "offset": 40, "size": 8, "type": "uint64"},
          {"name": "total_size", "offset": 48, "size": 8, "type": "uint64"},
          {"name": "recommended_length", "offset": 56, "size": 4, "type": "uint32"},
          {"name": "reserved", "offset": 60, "size": 4, "type": "bytes", "value": "zero"},
          {"name": "committed_at", "offset": 64, "size": 8, "type": "uint64"},
          {"name": "expires_at", "offset": 72, "size": 8, "type": "uint64", "zero_means": "no_scheduled_expiry"},
          {"name": "object_hash", "offset": 80, "size": 32, "type": "bytes"}
        ]
      }
    },
    "82": {
      "name": "object_get_range",
      "request": {
        "header_size": 64,
        "fields_after_common_prefix": [
          {"name": "object_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "file_type", "offset": 32, "size": 1, "type": "uint8"},
          {"name": "request_flags", "offset": 33, "size": 1, "type": "uint8", "value": 0},
          {"name": "reserved_1", "offset": 34, "size": 6, "type": "bytes", "value": "zero"},
          {"name": "generation", "offset": 40, "size": 8, "type": "uint64", "zero_means": "latest_committed"},
          {"name": "offset", "offset": 48, "size": 8, "type": "uint64"},
          {"name": "requested_length", "offset": 56, "size": 4, "type": "uint32"},
          {"name": "reserved_2", "offset": 60, "size": 4, "type": "bytes", "value": "zero"}
        ]
      },
      "response": {
        "header_size": 104,
        "data_follows_header": true,
        "fields_after_common_prefix": [
          {"name": "object_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "file_type", "offset": 32, "size": 1, "type": "uint8"},
          {"name": "response_flags", "offset": 33, "size": 1, "type": "uint8", "bits": {"0": "final_range", "1": "volatile_storage"}},
          {"name": "hash_algorithm", "offset": 34, "size": 1, "type": "uint8", "value": 1},
          {"name": "reserved_1", "offset": 35, "size": 1, "type": "uint8", "value": 0},
          {"name": "generation", "offset": 36, "size": 8, "type": "uint64"},
          {"name": "offset", "offset": 44, "size": 8, "type": "uint64"},
          {"name": "data_length", "offset": 52, "size": 4, "type": "uint32", "equals": "data.size"},
          {"name": "recommended_length", "offset": 56, "size": 4, "type": "uint32"},
          {"name": "total_size", "offset": 60, "size": 8, "type": "uint64"},
          {"name": "object_hash", "offset": 68, "size": 32, "type": "bytes"},
          {"name": "reserved_2", "offset": 100, "size": 4, "type": "bytes", "value": "zero"}
        ]
      }
    },
    "83": {
      "name": "object_capabilities",
      "request": {
        "header_size": 16,
        "fields_after_common_prefix": []
      },
      "response": {
        "header_size": 80,
        "entry_size": 64,
        "entry_count_field": "class_count",
        "fields_after_common_prefix": [
          {"name": "capability_schema", "offset": 16, "size": 2, "type": "uint16", "value": 1},
          {"name": "protocol_min", "offset": 18, "size": 2, "type": "uint16", "value": 1},
          {"name": "protocol_max", "offset": 20, "size": 2, "type": "uint16", "value": 1},
          {"name": "transport_flags", "offset": 22, "size": 2, "type": "uint16", "bits": {"0": "tcp"}},
          {"name": "server_flags", "offset": 24, "size": 4, "type": "uint32", "bits": {"0": "enabled", "1": "replacement", "2": "deletion", "3": "legacy_locker_marker", "4": "phase_1_allow_all_reads"}},
          {"name": "preferred_chunk", "offset": 28, "size": 4, "type": "uint32"},
          {"name": "max_chunk", "offset": 32, "size": 4, "type": "uint32"},
          {"name": "max_download_range", "offset": 36, "size": 4, "type": "uint32"},
          {"name": "max_active_transfers", "offset": 40, "size": 4, "type": "uint32"},
          {"name": "max_parallel_transfer", "offset": 44, "size": 2, "type": "uint16"},
          {"name": "class_count", "offset": 46, "size": 2, "type": "uint16", "maximum": 64},
          {"name": "max_object_global", "offset": 48, "size": 8, "type": "uint64", "minimum": 1},
          {"name": "generated_at", "offset": 56, "size": 8, "type": "uint64"},
          {"name": "expires_at", "offset": 64, "size": 8, "type": "uint64", "zero_means": "no_advertised_cache_lifetime"},
          {"name": "payment_mode", "offset": 72, "size": 2, "type": "uint16", "value": 1},
          {"name": "reserved", "offset": 74, "size": 6, "type": "bytes", "value": "zero"}
        ],
        "entry_fields": [
          {"name": "class_id", "offset": 0, "size": 2, "type": "uint16"},
          {"name": "media_type", "offset": 2, "size": 1, "type": "uint8", "values": {"1": "ram", "2": "nvme", "3": "ssd", "4": "hdd", "255": "other"}},
          {"name": "class_flags", "offset": 3, "size": 1, "type": "uint8", "bits": {"0": "volatile"}},
          {"name": "max_object", "offset": 4, "size": 8, "type": "uint64", "minimum": 1},
          {"name": "capacity_bytes", "offset": 12, "size": 8, "type": "uint64", "zero_means": "not_disclosed"},
          {"name": "available_bytes", "offset": 20, "size": 8, "type": "uint64", "zero_means": "not_disclosed"},
          {"name": "max_retention_seconds", "offset": 28, "size": 8, "type": "uint64", "zero_means": "server_policy"},
          {"name": "price_schedule_id", "offset": 36, "size": 4, "type": "uint32"},
          {"name": "reserved", "offset": 40, "size": 24, "type": "bytes", "value": "zero"}
        ]
      }
    },
    "84": {
      "name": "object_delete",
      "constraints": [
        "expected_generation == current_live_generation",
        "target_generation > expected_generation",
        "the tombstone is published at exactly target_generation"
      ],
      "request": {
        "header_size": 56,
        "fields_after_common_prefix": [
          {"name": "object_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "file_type", "offset": 32, "size": 1, "type": "uint8"},
          {"name": "reserved", "offset": 33, "size": 7, "type": "bytes", "value": "zero"},
          {"name": "expected_generation", "offset": 40, "size": 8, "type": "uint64"},
          {"name": "target_generation", "offset": 48, "size": 8, "type": "uint64"}
        ]
      },
      "response": {
        "header_size": 64,
        "fields_after_common_prefix": [
          {"name": "object_id", "offset": 16, "size": 16, "type": "bytes"},
          {"name": "file_type", "offset": 32, "size": 1, "type": "uint8"},
          {"name": "object_state", "offset": 33, "size": 1, "type": "uint8", "value": 2},
          {"name": "reserved_1", "offset": 34, "size": 6, "type": "bytes", "value": "zero"},
          {"name": "tombstone_generation", "offset": 40, "size": 8, "type": "uint64"},
          {"name": "deleted_at", "offset": 48, "size": 8, "type": "uint64"},
          {"name": "reserved_2", "offset": 56, "size": 8, "type": "bytes", "value": "zero"}
        ]
      }
    }
  },
  "tell_integration": {
    "manifest": "Tells announce object-stored mail with the standard manifest v1 (16-byte entries); no Object Transfer entry exists on the wire.",
    "object_id": "email GUID from the tell routing header",
    "generation": 1,
    "file_type": "from the v1 manifest entry",
    "integrity": "v1 manifest entry crc32 (crc32_present always set) plus per-stripe SHA-256 from object-info"
  },
  "status_codes": {
    "167": "ERROR_PAYMENT_PROCESSING",
    "169": "ERROR_PAYMENT_REQUIRED",
    "202": "ERROR_FILE_NOT_EXIST",
    "218": "ERROR_TCP_REQUIRED",
    "219": "ERROR_UNSUPPORTED_PROTOCOL",
    "220": "ERROR_OBJECT_TOO_LARGE",
    "221": "ERROR_RANGE_TOO_LARGE",
    "222": "ERROR_TRANSFER_NOT_FOUND",
    "223": "ERROR_TRANSFER_EXPIRED",
    "224": "ERROR_RANGE_CONFLICT",
    "225": "ERROR_TRANSFER_INCOMPLETE",
    "226": "ERROR_HASH_MISMATCH",
    "227": "ERROR_QUOTA_EXCEEDED",
    "228": "ERROR_OBJECT_NOT_COMMITTED",
    "229": "ERROR_INVALID_RANGE",
    "230": "ERROR_STORAGE_FULL",
    "231": "ERROR_OBJECT_STATE",
    "232": "ERROR_NOT_OBJECT_OWNER",
    "233": "ERROR_GENERATION_CONFLICT",
    "234": "ERROR_TRANSFER_CONFLICT",
    "235": "ERROR_RETENTION_UNAVAILABLE",
    "250": "SUCCESS"
  },
  "payment_modes": {
    "1": "legacy_locker_marker"
  },
  "initial_recommendations": {
    "preferred_chunk_bytes": 1048576,
    "max_chunk_bytes": 8388608,
    "max_download_range_bytes": 8388608,
    "cache_max_mb": 16384
  },
  "resolved_policy": {
    "object_identity": "stable_across_generations",
    "transfer_identity": "client_generated_random_128_bit_owner_bound_idempotency_key",
    "begin_retry": "at_most_once_reservation_and_payment_for_exact_owner_transfer_id",
    "retention": "uint64_seconds_zero_server_default_nonzero_exact_or_reject",
    "phase_1_payment_scope": "once_per_server_authenticated_owner_object_id_locker_code_shared_across_file_types_and_generations",
    "payment_states": "durable_pending_paid_failed_no_automatic_redispatch_when_ambiguous",
    "generation_assignment": "client_selected_monotonic_target_server_validated_by_expected_generation_cas",
    "replacement": "owner_only_atomic_generation_swap",
    "deletion": "owner_only_tombstone_generation",
    "phase_1_read_acl": "allow_all_authenticated_qmail_requests",
    "phase_1_manage_acl": "owner_only",
    "capacity_reservation": "exact_total_size_stored_content_bytes",
    "global_fault_tolerance": "client_managed",
    "storage_class_scope": "local_server_only",
    "phase_1_payment_mode": "legacy_locker_marker",
    "legacy_commands_70_through_75": "supported_without_v1_retirement_date"
  },
  "test_vectors": "qmail-object-transfer-v1-vectors.json"
}