Add separate version tracking for artifacts

README.md

@@ -22,6 +22,7 @@ Orchard is a centralized binary artifact storage system that provides content-ad
   - **Package** - Named collection within a project
   - **Artifact** - Specific content instance identified by SHA256
 - **Tags** - Alias system for referencing artifacts by human-readable names (e.g., `v1.0.0`, `latest`, `stable`)
+- **Versions** - Immutable version records set at upload time (explicit or auto-detected from filename/metadata), separate from mutable tags
 - **Package Formats & Platforms** - Packages can be tagged with format (npm, pypi, docker, deb, rpm, etc.) and platform (linux, darwin, windows, etc.)
 - **Rich Package Metadata** - Package listings include aggregated stats (tag count, artifact count, total size, latest tag)
 - **S3-Compatible Backend** - Uses MinIO (or any S3-compatible storage) for artifact storage
@@ -73,6 +74,9 @@ Orchard is a centralized binary artifact storage system that provides content-ad
 | `POST` | `/api/v1/project/:project/:package/tags` | Create a tag |
 | `GET` | `/api/v1/project/:project/:package/tags/:tag_name` | Get single tag with artifact metadata |
 | `GET` | `/api/v1/project/:project/:package/tags/:tag_name/history` | Get tag change history |
+| `GET` | `/api/v1/project/:project/:package/versions` | List all versions for a package |
+| `GET` | `/api/v1/project/:project/:package/versions/:version` | Get specific version details |
+| `DELETE` | `/api/v1/project/:project/:package/versions/:version` | Delete a version (admin only) |
 | `GET` | `/api/v1/project/:project/:package/artifacts` | List artifacts in package (with filtering) |
 | `GET` | `/api/v1/project/:project/:package/consumers` | List consumers of a package |
 | `GET` | `/api/v1/artifact/:id` | Get artifact metadata with referencing tags |
@@ -93,12 +97,14 @@ For large files, use the resumable upload API:
 
 When downloading artifacts, the `:ref` parameter supports multiple formats:
 
-- `latest` - Tag name directly
-- `v1.0.0` - Version tag
+- `latest` - Implicit lookup (checks version first, then tag, then artifact ID)
+- `v1.0.0` - Implicit lookup (version takes precedence over tag with same name)
+- `version:1.0.0` - Explicit version reference
 - `tag:stable` - Explicit tag reference
-- `version:2024.1` - Version reference
 - `artifact:a3f5d8e12b4c6789...` - Direct SHA256 hash reference
 
+**Resolution order for implicit refs:** version → tag → artifact ID
+
 ## Quick Start
 
 ### Prerequisites
@@ -230,9 +236,16 @@ curl "http://localhost:8080/api/v1/project/my-project/packages/releases?include_
 ### Upload an Artifact
 
 ```bash
+# Upload with tag only (version auto-detected from filename)
 curl -X POST http://localhost:8080/api/v1/project/my-project/releases/upload \
   -F "file=@./build/app-v1.0.0.tar.gz" \
-  -F "tag=v1.0.0"
+  -F "tag=latest"
+
+# Upload with explicit version and tag
+curl -X POST http://localhost:8080/api/v1/project/my-project/releases/upload \
+  -F "file=@./build/app-v1.0.0.tar.gz" \
+  -F "tag=latest" \
+  -F "version=1.0.0"
 ```
 
 Response:
@@ -242,7 +255,9 @@ Response:
   "size": 1048576,
   "project": "my-project",
   "package": "releases",
-  "tag": "v1.0.0",
+  "tag": "latest",
+  "version": "1.0.0",
+  "version_source": "explicit",
   "format_metadata": {
     "format": "tarball",
     "package_name": "app",
@@ -400,6 +415,38 @@ curl http://localhost:8080/api/v1/project/my-project/releases/tags/latest/histor
 
 Returns list of artifact changes for the tag (most recent first).
 
+### List Versions
+
+```bash
+# Basic listing
+curl http://localhost:8080/api/v1/project/my-project/releases/versions
+
+# With pagination and sorting
+curl "http://localhost:8080/api/v1/project/my-project/releases/versions?sort=version&order=desc"
+```
+
+Response includes tags pointing to each version's artifact:
+```json
+{
+  "items": [
+    {
+      "id": "uuid",
+      "package_id": "uuid",
+      "version": "1.0.0",
+      "version_source": "explicit",
+      "artifact_id": "a3f5d8e...",
+      "size": 1048576,
+      "content_type": "application/gzip",
+      "original_name": "app-v1.0.0.tar.gz",
+      "created_at": "2025-01-01T00:00:00Z",
+      "created_by": "user",
+      "tags": ["latest", "stable"]
+    }
+  ],
+  "pagination": {"page": 1, "limit": 20, "total": 1, "total_pages": 1}
+}
+```
+
 ### List Artifacts in Package
 
 ```bash
@@ -614,7 +661,8 @@ See `helm/orchard/values.yaml` for all configuration options.
 - **projects** - Top-level organizational containers
 - **packages** - Collections within projects
 - **artifacts** - Content-addressable artifacts (SHA256)
-- **tags** - Aliases pointing to artifacts
+- **tags** - Mutable aliases pointing to artifacts
+- **package_versions** - Immutable version records (set at upload time)
 - **tag_history** - Audit trail for tag changes
 - **uploads** - Upload event records
 - **consumers** - Dependency tracking