init

2026-08-26 09:56:43 +08:00
parent 2b4974b561
commit 8e02a316fa
93 changed files with 21749 additions and 0 deletions
@@ -0,0 +1,46 @@
+# Run Artifact Contract
+
+Artifacts move files and large payloads between platform and run without blocking 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 log upload.
+- Artifact transfer is lower priority than control, job lifecycle metadata, and durable log ingest.
+- Slow or retrying artifact chunks must not prevent log spool acknowledgement cleanup 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.