Resumable Upload Rules

FATAL Constraints

• NEVER use the standard upload endpoint for files exceeding 6MB. MUST use the TUS resumable protocol.
• NEVER construct an upload path that does not start with the authenticated user's tenant_id. HALT immediately on path violation.
• NEVER ignore a 409 Conflict response. It signals a Postgres Advisory Lock collision and MUST be retried with exponential backoff.
• MUST NOT set x-upsert: true unless the user has explicitly requested file overwrite. Default is false.
• MUST NOT skip the Tus-Resumable: 1.0.0 header on any request to the resumable endpoint.
• MUST NOT upload chunks smaller than 6MB except for the final chunk of the file.

Mandatory Behaviors

• MUST validate file size before selecting upload strategy: >6MB uses TUS, <=6MB uses standard upload.
• MUST structure upload paths as <tenant_id>/<resource_type>/<filename>.
• MUST pass all upload paths through the storage-path-validation tile before any upload request.
• MUST include Upload-Metadata header with base64-encoded bucketName, objectName, and contentType.
• MUST handle network failures by sending a HEAD request to the upload URL to retrieve the confirmed offset, then resume from that offset.
• MUST retry 409 Conflict responses with exponential backoff (1s, 2s, 4s) for a maximum of 3 attempts.
• MUST verify the uploaded object exists and matches the expected size after upload completion.