first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,65 @@
+## ADDED Requirements
+
+### Requirement: Artifact transfer channel is separate from other run channels
+
+The platform SHALL expose artifact transfer behavior through dedicated run artifact routes and SHALL NOT require control, job, or log routes to carry artifact chunk payloads.
+
+#### Scenario: Dedicated artifact routes handle chunks
+- **WHEN** a registered run endpoint uploads an artifact chunk
+- **THEN** the request is handled by a run artifact transfer route and no control, job, or log route accepts the chunk payload
+
+### Requirement: Run opens upload transfer sessions
+
+The platform SHALL allow an active run session to open an upload transfer for a job-owned or server-instance-owned artifact assigned to that run endpoint.
+
+#### Scenario: Valid upload session opens
+- **WHEN** a run endpoint opens an upload transfer with a valid session token, artifact metadata, owner, total size, chunk size, checksum, and idempotency key
+- **THEN** the platform returns an accepted transfer ID, records the artifact in uploading state, and reports no received chunks
+
+#### Scenario: Invalid owner is rejected
+- **WHEN** a run endpoint opens an upload transfer for an artifact owner that is not assigned to that run endpoint
+- **THEN** the platform rejects the request without marking the artifact available
+
+### Requirement: Platform validates chunk upload integrity
+
+The platform SHALL validate artifact transfer ID, run session, chunk index, byte range, payload size, and chunk checksum before acknowledging an uploaded chunk.
+
+#### Scenario: Valid chunk is acknowledged
+- **WHEN** a run endpoint uploads a chunk whose byte range, payload size, and checksum match the opened transfer
+- **THEN** the platform records the chunk and returns an acknowledgement with the accepted chunk index and received chunk list
+
+#### Scenario: Conflicting duplicate chunk is rejected
+- **WHEN** a run endpoint uploads a chunk index that was already acknowledged with different payload bytes or checksum
+- **THEN** the platform rejects the request as a validation error
+
+### Requirement: Artifact transfer resume state is queryable
+
+The platform SHALL report the current transfer state, received chunk indexes, next missing chunk index, total chunk count, and completion status for an active artifact transfer.
+
+#### Scenario: Resume status reports missing chunk
+- **WHEN** a run endpoint queries transfer status after only part of an artifact has uploaded
+- **THEN** the platform returns the acknowledged chunk indexes and the next missing chunk index
+
+### Requirement: Artifact completion verifies full checksum
+
+The platform SHALL mark an artifact available only after all chunks are present and the final artifact checksum matches the opened transfer metadata.
+
+#### Scenario: Complete verified artifact
+- **WHEN** every chunk has been uploaded and the run endpoint completes the transfer with the correct final checksum
+- **THEN** the platform marks the artifact available and returns the updated artifact metadata
+
+#### Scenario: Missing chunk prevents completion
+- **WHEN** the run endpoint completes a transfer before every chunk is present
+- **THEN** the platform rejects completion and leaves the artifact non-available
+
+### Requirement: Run retains unacknowledged artifact chunks
+
+The run executor SHALL persist pending artifact chunk upload requests locally and SHALL remove a chunk from the pending queue only after platform acknowledgement for that artifact transfer and chunk index.
+
+#### Scenario: Acknowledged chunk is removed from retry queue
+- **WHEN** a pending artifact chunk receives a platform acknowledgement for the same transfer ID and chunk index
+- **THEN** the run artifact queue removes that chunk from pending retry state
+
+#### Scenario: Unacknowledged chunk remains pending
+- **WHEN** an artifact chunk has not received a matching platform acknowledgement
+- **THEN** the run artifact queue keeps the chunk available for retry