# 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 chunk with byte range and checksum metadata.
- `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 JSON byte payload.
- `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 `ArtifactChunkUploadRequest` payloads 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.