run/protocol/artifact.md

Run Artifact Contract

Artifacts move files and large payloads between platform and run without blocking current live logs or control.

Implemented Routes

• POST /api/v1/run/artifacts/open: opens a run-to-platform upload transfer and returns resume state.
• POST /api/v1/run/artifacts/chunks: uploads one bounded octet-stream chunk with byte range and checksum metadata in headers.
• POST /api/v1/run/artifacts/status: queries received chunks and the next missing chunk index.
• POST /api/v1/run/artifacts/complete: verifies all chunks and final checksum before marking the artifact available.

Browser-facing artifact downloads are implemented through platform-owned routes after a run upload completes:

• POST /api/v1/artifacts/{id}/download: returns safe download metadata and a platform content route.
• GET /api/v1/artifacts/{id}/content: returns bounded byte ranges for authorized browser or plugin-page reads.

Payloads

• ArtifactTransferOpenRequest: run ID, session token, artifact ID, upload direction, owner scope, size, chunk size, checksum, and idempotency key.
• ArtifactTransferOpenResponse: transfer ID, artifact metadata, total chunks, received chunk indexes, next missing chunk index, duplicate flag, and server time.
• ArtifactChunkUploadRequest: transfer ID, artifact ID, chunk index, byte offset, size, checksum, and an in-memory octet-stream payload buffer that is not JSON encoded.
• ArtifactChunkUploadResponse: accepted chunk index, received chunk indexes, next missing chunk index, duplicate flag, and server time.
• ArtifactTransferStatusRequest: run ID, session token, transfer ID, and artifact ID.
• ArtifactTransferStatusResponse: transfer direction, total chunks, received chunk indexes, next missing chunk index, completion flag, and server time.
• ArtifactTransferCompleteRequest: transfer ID, artifact ID, final checksum, and final size.
• ArtifactTransferCompleteResponse: completed artifact metadata and server time.

Local Queue

Run stores unacknowledged artifact chunk metadata as JSON and raw chunk bytes as sidecar files in the local artifact queue. A queued chunk may be removed only after the platform acknowledges the same transfer ID, artifact ID, and chunk index. The queue must not store or expose raw host paths.

Rules

• Transfers must be resumable.
• Transfers must be checksummed.
• Artifact concurrency must be limited.
• Artifact transfer must not block control heartbeat, job ack/result, or current live log relay.
• Artifact transfer is lower priority than control, job lifecycle metadata, and current live log relay.
• Slow or retrying artifact chunks must not delay live log relay or terminal job result submission.
• Control, job, and log routes must reject artifact chunk payloads or transport details rather than accepting them through lightweight channel payloads.

Run artifact queues use owner-only atomic JSON entries and retain chunks until an exact transfer/artifact/index acknowledgement covers them. A low-priority uploader retries pending chunks independently of control, jobs, and logs.

Deferred Channels

Platform-to-run Run self-update range reads are implemented through the signed /api/v1/run/jobs/update-input and /api/v1/run/jobs/update-chunk contract. Browser artifact upload, external object storage, presigned URLs, production mirrors/signing, and production throttling policies remain separate future work.