docs: add detailed implementation plan for PyPI proxy performance

Comprehensive design for:
- HTTP connection pooling with lifecycle management
- Redis caching layer (TTL for discovery, permanent for immutable)
- Abstract PackageProxyBase for multi-protocol support (npm, Maven)
- Database query optimization with batch operations
- Dependency resolution caching for ensure files
- Observability via health endpoints

Maintains hermetic build guarantees: artifact content and extracted
metadata are immutable, only discovery data uses TTL-based caching.

.gitlab-ci.yml

@@ -11,13 +11,6 @@ variables:
   # Environment URLs (used by deploy and test jobs)
   STAGE_URL: https://orchard-stage.common.global.bsf.tools
   PROD_URL: https://orchard.common.global.bsf.tools
-  # Stage environment AWS resources (used by reset job)
-  STAGE_RDS_HOST: orchard-stage.cluster-cvw3jzjkozoc.us-gov-west-1.rds.amazonaws.com
-  STAGE_RDS_DBNAME: postgres
-  STAGE_SECRET_ARN: "arn:aws-us-gov:secretsmanager:us-gov-west-1:052673043337:secret:rds!cluster-a573672b-1a38-4665-a654-1b7df37b5297-IaeFQL"
-  STAGE_AUTH_SECRET_ARN: "arn:aws-us-gov:secretsmanager:us-gov-west-1:052673043337:secret:orchard-stage-creds-SMqvQx"
-  STAGE_S3_BUCKET: orchard-artifacts-stage
-  AWS_REGION: us-gov-west-1
   # Shared pip cache directory
   PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache"
 
@@ -95,10 +88,18 @@ cve_sbom_analysis:
       when: never
     - when: on_success
 
-# Override release job to wait for stage integration tests before creating tag
+# Disable prosper_setup for tag pipelines since no build/analysis jobs run
+# (image is already built when commit was on main, and deploy uses helm directly)
+prosper_setup:
+  rules:
+    - if: '$CI_COMMIT_TAG'
+      when: never
+    - when: on_success
+
+# Override release job to wait for stage deployment and smoke tests before creating tag
 # This ensures the tag (which triggers prod deploy) is only created after stage passes
 release:
-  needs: [integration_test_stage, changelog]
+  needs: [smoke_test_stage, changelog]
 
 # Full integration test suite template (for feature/stage deployments)
 # Runs the complete pytest integration test suite against the deployed environment
@@ -200,108 +201,6 @@ release:
           sys.exit(0)
       PYTEST_SCRIPT
 
-# Reset stage template - runs from CI runner, uses CI variable for auth
-# Calls the /api/v1/admin/factory-reset endpoint which handles DB and S3 cleanup
-.reset_stage_template: &reset_stage_template
-  stage: deploy
-  image: deps.global.bsf.tools/docker/python:3.12-slim
-  timeout: 5m
-  retry: 1
-  before_script:
-    - pip install --index-url "$PIP_INDEX_URL" httpx
-  script:
-    - |
-      python - <<'RESET_SCRIPT'
-      import httpx
-      import sys
-      import os
-      import time
-
-      BASE_URL = os.environ.get("STAGE_URL", "")
-      ADMIN_USER = "admin"
-      ADMIN_PASS = os.environ.get("STAGE_ADMIN_PASSWORD", "")
-      MAX_RETRIES = 3
-      RETRY_DELAY = 5
-
-      if not BASE_URL:
-          print("ERROR: STAGE_URL not set")
-          sys.exit(1)
-
-      if not ADMIN_PASS:
-          print("ERROR: STAGE_ADMIN_PASSWORD not set")
-          sys.exit(1)
-
-      print(f"=== Resetting stage environment at {BASE_URL} ===")
-
-      def do_reset():
-          with httpx.Client(base_url=BASE_URL, timeout=120.0) as client:
-              print("Logging in as admin...")
-              login_response = client.post(
-                  "/api/v1/auth/login",
-                  json={"username": ADMIN_USER, "password": ADMIN_PASS},
-              )
-              if login_response.status_code != 200:
-                  raise Exception(f"Login failed: {login_response.status_code} - {login_response.text}")
-              print("Login successful")
-
-              print("Calling factory reset endpoint...")
-              reset_response = client.post(
-                  "/api/v1/admin/factory-reset",
-                  headers={"X-Confirm-Reset": "yes-delete-all-data"},
-              )
-
-              if reset_response.status_code == 200:
-                  result = reset_response.json()
-                  print("Factory reset successful!")
-                  print(f"  Database tables dropped: {result['results']['database_tables_dropped']}")
-                  print(f"  S3 objects deleted: {result['results']['s3_objects_deleted']}")
-                  print(f"  Database reinitialized: {result['results']['database_reinitialized']}")
-                  print(f"  Seeded: {result['results']['seeded']}")
-                  return True
-              else:
-                  raise Exception(f"Factory reset failed: {reset_response.status_code} - {reset_response.text}")
-
-      for attempt in range(1, MAX_RETRIES + 1):
-          try:
-              print(f"Attempt {attempt}/{MAX_RETRIES}")
-              if do_reset():
-                  sys.exit(0)
-          except Exception as e:
-              print(f"Attempt {attempt} failed: {e}")
-              if attempt < MAX_RETRIES:
-                  print(f"Retrying in {RETRY_DELAY} seconds...")
-                  time.sleep(RETRY_DELAY)
-              else:
-                  print("All retry attempts failed")
-                  sys.exit(1)
-      RESET_SCRIPT
-  rules:
-    - if: '$CI_COMMIT_BRANCH == "main"'
-      when: on_success
-
-# Reset stage BEFORE integration tests (ensure known state)
-reset_stage_pre:
-  <<: *reset_stage_template
-  needs: [deploy_stage]
-
-# Integration tests for stage deployment
-# Uses CI variable STAGE_ADMIN_PASSWORD (set in GitLab CI/CD settings)
-integration_test_stage:
-  <<: *integration_test_template
-  needs: [reset_stage_pre]
-  variables:
-    ORCHARD_TEST_URL: $STAGE_URL
-    ORCHARD_TEST_PASSWORD: $STAGE_ADMIN_PASSWORD
-  rules:
-    - if: '$CI_COMMIT_BRANCH == "main"'
-      when: on_success
-
-# Reset stage AFTER integration tests (clean slate for next run)
-reset_stage:
-  <<: *reset_stage_template
-  needs: [integration_test_stage]
-  allow_failure: true  # Don't fail pipeline if reset has issues
-
 # Integration tests for feature deployment (full suite)
 # Uses DEV_ADMIN_PASSWORD CI variable (same as deploy_feature)
 integration_test_feature:
@@ -314,6 +213,74 @@ integration_test_feature:
     - if: '$CI_COMMIT_BRANCH && $CI_COMMIT_BRANCH != "main"'
       when: on_success
 
+# Reset feature environment after integration tests
+# Calls factory-reset to clean up test data created during integration tests
+reset_feature:
+  stage: deploy
+  needs: [integration_test_feature]
+  image: deps.global.bsf.tools/docker/python:3.12-slim
+  timeout: 5m
+  before_script:
+    - pip install --index-url "$PIP_INDEX_URL" httpx
+  script:
+    # Debug: Check if variable is set at shell level
+    - echo "RESET_ADMIN_PASSWORD length at shell level:${#RESET_ADMIN_PASSWORD}"
+    - |
+      python - <<'RESET_SCRIPT'
+      import httpx
+      import os
+      import sys
+
+      BASE_URL = f"https://orchard-{os.environ['CI_COMMIT_REF_SLUG']}.common.global.bsf.tools"
+      PASSWORD_RAW = os.environ.get("RESET_ADMIN_PASSWORD")
+
+      if not PASSWORD_RAW:
+          print("ERROR: RESET_ADMIN_PASSWORD not set")
+          sys.exit(1)
+
+      # Debug: check for hidden characters
+      print(f"Raw password repr (first 3 chars): {repr(PASSWORD_RAW[:3])}")
+      print(f"Raw password repr (last 3 chars): {repr(PASSWORD_RAW[-3:])}")
+      print(f"Raw length: {len(PASSWORD_RAW)}")
+
+      # Strip any whitespace
+      PASSWORD = PASSWORD_RAW.strip()
+      print(f"Stripped length: {len(PASSWORD)}")
+
+      print(f"Resetting environment at {BASE_URL}")
+      client = httpx.Client(base_url=BASE_URL, timeout=60.0)
+
+      # Login as admin
+      login_resp = client.post("/api/v1/auth/login", json={
+          "username": "admin",
+          "password": PASSWORD
+      })
+      if login_resp.status_code != 200:
+          print(f"ERROR: Login failed: {login_resp.status_code}")
+          print(f"Response: {login_resp.text}")
+          sys.exit(1)
+
+      # Call factory reset
+      reset_resp = client.post(
+          "/api/v1/admin/factory-reset",
+          headers={"X-Confirm-Reset": "yes-delete-all-data"}
+      )
+      if reset_resp.status_code == 200:
+          print("SUCCESS: Factory reset completed")
+          print(reset_resp.json())
+      else:
+          print(f"ERROR: Factory reset failed: {reset_resp.status_code}")
+          print(reset_resp.text)
+          sys.exit(1)
+      RESET_SCRIPT
+  variables:
+    # Use same pattern as integration_test_feature - create new variable from CI variable
+    RESET_ADMIN_PASSWORD: $DEV_ADMIN_PASSWORD
+  rules:
+    - if: '$CI_COMMIT_BRANCH && $CI_COMMIT_BRANCH != "main"'
+      when: on_success
+  allow_failure: true  # Don't fail the pipeline if reset fails
+
 # Run Python backend unit tests
 python_unit_tests:
   stage: test
@@ -412,9 +379,88 @@ frontend_tests:
   echo "Health check failed after 30 attempts"
   exit 1
 
-# Deploy to stage (main branch)
-deploy_stage:
+# Ephemeral test deployment in stage namespace (main branch only)
+# Runs integration tests before promoting to long-running stage
+deploy_test:
   <<: *deploy_template
+  variables:
+    NAMESPACE: orch-stage-namespace
+    VALUES_FILE: helm/orchard/values-dev.yaml
+    BASE_URL: https://orchard-test.common.global.bsf.tools
+  before_script:
+    - kubectl config use-context esv/bsf/bsf-integration/orchard/orchard-mvp:orchard-stage
+    - *helm_setup
+  script:
+    - echo "Deploying ephemeral test environment"
+    - cd $CI_PROJECT_DIR
+    - |
+      helm upgrade --install orchard-test ./helm/orchard \
+        --namespace $NAMESPACE \
+        -f $VALUES_FILE \
+        --set image.tag=git.linux-amd64-$CI_COMMIT_SHA \
+        --set orchard.auth.adminPassword=$STAGE_ADMIN_PASSWORD \
+        --set ingress.hosts[0].host=orchard-test.common.global.bsf.tools \
+        --set ingress.tls[0].hosts[0]=orchard-test.common.global.bsf.tools \
+        --set ingress.tls[0].secretName=orchard-test-tls \
+        --set minioIngress.host=minio-test.common.global.bsf.tools \
+        --set minioIngress.tls.secretName=minio-test-tls \
+        --wait \
+        --atomic \
+        --timeout 10m
+    - kubectl rollout status deployment/orchard-test-server -n $NAMESPACE --timeout=10m
+    - *verify_deployment
+  environment:
+    name: test
+    url: https://orchard-test.common.global.bsf.tools
+    on_stop: cleanup_test
+    kubernetes:
+      agent: esv/bsf/bsf-integration/orchard/orchard-mvp:orchard-stage
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: on_success
+
+# Integration tests for ephemeral test deployment (main branch)
+# Runs against orchard-test before promoting to long-running stage
+integration_test_main:
+  <<: *integration_test_template
+  needs: [deploy_test]
+  variables:
+    ORCHARD_TEST_URL: https://orchard-test.common.global.bsf.tools
+    ORCHARD_TEST_PASSWORD: $STAGE_ADMIN_PASSWORD
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: on_success
+
+# Cleanup ephemeral test deployment after integration tests
+cleanup_test:
+  stage: deploy
+  needs: [integration_test_main]
+  image: deps.global.bsf.tools/registry-1.docker.io/alpine/k8s:1.29.12
+  timeout: 5m
+  variables:
+    NAMESPACE: orch-stage-namespace
+    GIT_STRATEGY: none
+  before_script:
+    - kubectl config use-context esv/bsf/bsf-integration/orchard/orchard-mvp:orchard-stage
+  script:
+    - echo "Cleaning up ephemeral test deployment orchard-test"
+    - helm uninstall orchard-test --namespace $NAMESPACE || true
+  environment:
+    name: test
+    action: stop
+    kubernetes:
+      agent: esv/bsf/bsf-integration/orchard/orchard-mvp:orchard-stage
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: on_success
+  allow_failure: true
+
+# Deploy to long-running stage (main branch, after ephemeral tests pass)
+deploy_stage:
+  stage: deploy
+  # Wait for ephemeral test to pass before promoting to long-running stage
+  needs: [cleanup_test]
+  image: deps.global.bsf.tools/registry-1.docker.io/alpine/k8s:1.29.12
   variables:
     NAMESPACE: orch-stage-namespace
     VALUES_FILE: helm/orchard/values-stage.yaml
@@ -423,7 +469,7 @@ deploy_stage:
     - kubectl config use-context esv/bsf/bsf-integration/orchard/orchard-mvp:orchard-stage
     - *helm_setup
   script:
-    - echo "Deploying to stage environment"
+    - echo "Deploying to long-running stage environment"
     - cd $CI_PROJECT_DIR
     - |
       helm upgrade --install orchard-stage ./helm/orchard \
@@ -445,6 +491,16 @@ deploy_stage:
     - if: '$CI_COMMIT_BRANCH == "main"'
       when: on_success
 
+# Smoke test for long-running stage (after promotion)
+smoke_test_stage:
+  <<: *smoke_test_template
+  needs: [deploy_stage]
+  variables:
+    ORCHARD_TEST_URL: $STAGE_URL
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: on_success
+
 # Deploy feature branch to dev namespace
 deploy_feature:
   <<: *deploy_template

CHANGELOG.md

@@ -7,6 +7,113 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
+- Added transparent PyPI proxy implementing PEP 503 Simple API (#108)
+  - `GET /pypi/simple/` - package index (proxied from upstream)
+  - `GET /pypi/simple/{package}/` - version list with rewritten download links
+  - `GET /pypi/simple/{package}/{filename}` - download with automatic caching
+  - Allows `pip install --index-url https://orchard.../pypi/simple/ <package>`
+  - Artifacts cached on first access through configured upstream sources
+- Added `POST /api/v1/cache/resolve` endpoint to cache packages by coordinates instead of URL (#108)
+
+### Changed
+- Upstream sources table text is now centered under column headers (#108)
+- ENV badge now appears inline with source name instead of separate column (#108)
+- Test and Edit buttons now have more prominent button styling (#108)
+- Reduced footer padding for cleaner layout (#108)
+
+### Fixed
+- Fixed purge_seed_data crash when deleting access permissions - was comparing UUID to VARCHAR column (#107)
+
+### Changed
+- Upstream source connectivity test no longer follows redirects, fixing "Exceeded maximum allowed redirects" error with Artifactory proxies (#107)
+- Test runs automatically after saving a new or updated upstream source (#107)
+- Test status now shows as colored dots (green=success, red=error) instead of text badges (#107)
+- Clicking red dot shows error details in a modal (#107)
+- Source name column no longer wraps text for better table layout (#107)
+- Renamed "Cache Management" page to "Upstream Sources" (#107)
+- Moved Delete button from table row to edit modal for cleaner table layout (#107)
+
+### Removed
+- Removed `is_public` field from upstream sources - all sources are now treated as internal/private (#107)
+- Removed `allow_public_internet` (air-gap mode) setting from cache settings - not needed for enterprise proxy use case (#107)
+- Removed seeding of public registry URLs (npm-public, pypi-public, maven-central, docker-hub) (#107)
+- Removed "Public" badge and checkbox from upstream sources UI (#107)
+- Removed "Allow Public Internet" toggle from cache settings UI (#107)
+- Removed "Global Settings" section from cache management UI - auto-create system projects is always enabled (#107)
+- Removed unused CacheSettings frontend types and API functions (#107)
+
+### Added
+- Added `ORCHARD_PURGE_SEED_DATA` environment variable support to stage helm values to remove seed data from long-running deployments (#107)
+- Added frontend system projects visual distinction (#105)
+  - "Cache" badge for system projects in project list
+  - "System Cache" badge on project detail page
+  - Added `is_system` field to Project type
+- Added frontend admin page for upstream sources and cache settings (#75)
+  - New `/admin/cache` page accessible from user menu (admin only)
+  - Upstream sources table with create/edit/delete/test connectivity
+  - Cache settings section with air-gap mode and auto-create system projects toggles
+  - Visual indicators for env-defined sources (locked, cannot be modified)
+  - Environment variable override badges when settings are overridden
+  - API client functions for all cache admin operations
+- Added environment variable overrides for cache configuration (#74)
+  - `ORCHARD_CACHE_ALLOW_PUBLIC_INTERNET` - Override allow_public_internet (air-gap mode)
+  - `ORCHARD_CACHE_AUTO_CREATE_SYSTEM_PROJECTS` - Override auto_create_system_projects
+  - `ORCHARD_UPSTREAM__{NAME}__*` - Define upstream sources via env vars
+  - Env-defined sources appear in API with `source: "env"` marker
+  - Env-defined sources cannot be modified/deleted via API (400 error)
+  - Cache settings response includes `*_env_override` fields when overridden
+  - 7 unit tests for env var parsing and configuration
+- Added Global Cache Settings Admin API (#73)
+  - `GET /api/v1/admin/cache-settings` - Retrieve current cache settings
+  - `PUT /api/v1/admin/cache-settings` - Update cache settings (partial updates)
+  - Admin-only access with audit logging
+  - Controls `allow_public_internet` (air-gap mode) and `auto_create_system_projects`
+  - 7 integration tests for settings management
+- Added Upstream Sources Admin API for managing cache sources (#72)
+  - `GET /api/v1/admin/upstream-sources` - List sources with filtering
+  - `POST /api/v1/admin/upstream-sources` - Create source with auth configuration
+  - `GET /api/v1/admin/upstream-sources/{id}` - Get source details
+  - `PUT /api/v1/admin/upstream-sources/{id}` - Update source (partial updates)
+  - `DELETE /api/v1/admin/upstream-sources/{id}` - Delete source
+  - `POST /api/v1/admin/upstream-sources/{id}/test` - Test connectivity
+  - Admin-only access with audit logging
+  - Credentials never exposed (only has_password/has_headers flags)
+  - 13 integration tests for all CRUD operations
+- Added system project restrictions and management (#71)
+  - System projects (`_npm`, `_pypi`, etc.) cannot be deleted (returns 403)
+  - System projects cannot be made private (must remain public)
+  - `GET /api/v1/system-projects` endpoint to list all system cache projects
+  - 5 integration tests for system project restrictions
+- Added Cache API endpoint for fetching and storing artifacts from upstream URLs (#70)
+  - `POST /api/v1/cache` endpoint to cache artifacts from upstream registries
+  - URL parsing helpers to extract package name/version from npm, PyPI, Maven URLs
+  - Automatic system project creation (`_npm`, `_pypi`, `_maven`, etc.)
+  - URL-to-artifact provenance tracking via `cached_urls` table
+  - Optional user project cross-referencing for custom organization
+  - Cache hit returns existing artifact without re-fetching
+  - Air-gap mode enforcement (blocks public URLs when disabled)
+  - Hash verification for downloaded artifacts
+  - 21 unit tests for URL parsing and cache endpoint
+- Added HTTP client for fetching artifacts from upstream sources (#69)
+  - `UpstreamClient` class in `backend/app/upstream.py` with streaming downloads
+  - SHA256 hash computation while streaming (doesn't load large files into memory)
+  - Auth support: none, basic auth, bearer token, API key (custom headers)
+  - URL-to-source matching by URL prefix with priority ordering
+  - Configuration options: timeouts, retries with exponential backoff, redirect limits, max file size
+  - Air-gap mode enforcement via `allow_public_internet` setting
+  - Response header capture for provenance tracking
+  - Proper error handling with custom exception types
+  - Connection test method for upstream source validation
+  - 33 unit tests for client functionality
+- Added upstream artifact caching schema for hermetic builds (#68)
+  - `upstream_sources` table for configuring upstream registries (npm, PyPI, Maven, etc.)
+  - `cache_settings` table for global settings including air-gap mode
+  - `cached_urls` table for URL-to-artifact provenance tracking
+  - `is_system` column on projects for system cache projects (_npm, _pypi, etc.)
+  - Support for multiple auth types: none, basic auth, bearer token, API key
+  - Fernet encryption for credentials using `ORCHARD_CACHE_ENCRYPTION_KEY`
+  - Default upstream sources seeded (npm-public, pypi-public, maven-central, docker-hub) - disabled by default
+  - Migration `010_upstream_caching.sql`
 - Added team-based multi-tenancy for organizing projects and collaboration (#88-#104)
   - Teams serve as organizational containers for projects
   - Users can belong to multiple teams with different roles (owner, admin, member)

backend/app/auth.py

@@ -11,7 +11,7 @@ from typing import Optional
 from passlib.context import CryptContext
 from sqlalchemy.orm import Session
 
-from .models import User, Session as UserSession, APIKey, Team, TeamMembership
+from .models import User, Session as UserSession, APIKey
 from .config import get_settings
 
 logger = logging.getLogger(__name__)
@@ -363,8 +363,6 @@ def create_default_admin(db: Session) -> Optional[User]:
 
     The admin password can be set via ORCHARD_ADMIN_PASSWORD environment variable.
     If not set, defaults to 'changeme123' and requires password change on first login.
-
-    Also creates the "Global Admins" team and adds the admin user to it.
     """
     # Check if any users exist
     user_count = db.query(User).count()
@@ -387,27 +385,6 @@ def create_default_admin(db: Session) -> Optional[User]:
         must_change_password=must_change,
     )
 
-    # Create Global Admins team and add admin to it
-    global_admins_team = Team(
-        name="Global Admins",
-        slug="global-admins",
-        description="System administrators with full access",
-        created_by="admin",
-    )
-    db.add(global_admins_team)
-    db.flush()
-
-    membership = TeamMembership(
-        team_id=global_admins_team.id,
-        user_id=admin.id,
-        role="owner",
-        invited_by="admin",
-    )
-    db.add(membership)
-    db.commit()
-
-    logger.info("Created Global Admins team and added admin as owner")
-
     if settings.admin_password:
         logger.info("Created default admin user with configured password")
     else:

backend/app/cache.py

@@ -0,0 +1,316 @@
+"""
+Cache service for upstream artifact caching.
+
+Provides URL parsing, system project management, and caching logic
+for the upstream caching feature.
+"""
+
+import logging
+import re
+from dataclasses import dataclass
+from typing import Optional
+from urllib.parse import urlparse, unquote
+
+logger = logging.getLogger(__name__)
+
+
+# System project names for each source type
+SYSTEM_PROJECT_NAMES = {
+    "npm": "_npm",
+    "pypi": "_pypi",
+    "maven": "_maven",
+    "docker": "_docker",
+    "helm": "_helm",
+    "nuget": "_nuget",
+    "deb": "_deb",
+    "rpm": "_rpm",
+    "generic": "_generic",
+}
+
+# System project descriptions
+SYSTEM_PROJECT_DESCRIPTIONS = {
+    "npm": "System cache for npm packages",
+    "pypi": "System cache for PyPI packages",
+    "maven": "System cache for Maven packages",
+    "docker": "System cache for Docker images",
+    "helm": "System cache for Helm charts",
+    "nuget": "System cache for NuGet packages",
+    "deb": "System cache for Debian packages",
+    "rpm": "System cache for RPM packages",
+    "generic": "System cache for generic artifacts",
+}
+
+
+@dataclass
+class ParsedUrl:
+    """Parsed URL information for caching."""
+
+    package_name: str
+    version: Optional[str] = None
+    filename: Optional[str] = None
+
+
+def parse_npm_url(url: str) -> Optional[ParsedUrl]:
+    """
+    Parse npm registry URL to extract package name and version.
+
+    Formats:
+    - https://registry.npmjs.org/{package}/-/{package}-{version}.tgz
+    - https://registry.npmjs.org/@{scope}/{package}/-/{package}-{version}.tgz
+
+    Examples:
+    - https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz
+    - https://registry.npmjs.org/@types/node/-/node-18.0.0.tgz
+    """
+    parsed = urlparse(url)
+    path = unquote(parsed.path)
+
+    # Pattern for scoped packages: /@scope/package/-/package-version.tgz
+    scoped_pattern = r"^/@([^/]+)/([^/]+)/-/\2-(.+)\.tgz$"
+    match = re.match(scoped_pattern, path)
+    if match:
+        scope, name, version = match.groups()
+        return ParsedUrl(
+            package_name=f"@{scope}/{name}",
+            version=version,
+            filename=f"{name}-{version}.tgz",
+        )
+
+    # Pattern for unscoped packages: /package/-/package-version.tgz
+    unscoped_pattern = r"^/([^/@]+)/-/\1-(.+)\.tgz$"
+    match = re.match(unscoped_pattern, path)
+    if match:
+        name, version = match.groups()
+        return ParsedUrl(
+            package_name=name,
+            version=version,
+            filename=f"{name}-{version}.tgz",
+        )
+
+    return None
+
+
+def parse_pypi_url(url: str) -> Optional[ParsedUrl]:
+    """
+    Parse PyPI URL to extract package name and version.
+
+    Formats:
+    - https://files.pythonhosted.org/packages/.../package-version.tar.gz
+    - https://files.pythonhosted.org/packages/.../package-version-py3-none-any.whl
+    - https://pypi.org/packages/.../package-version.tar.gz
+
+    Examples:
+    - https://files.pythonhosted.org/packages/ab/cd/requests-2.28.0.tar.gz
+    - https://files.pythonhosted.org/packages/ab/cd/requests-2.28.0-py3-none-any.whl
+    """
+    parsed = urlparse(url)
+    path = unquote(parsed.path)
+
+    # Get the filename from the path
+    filename = path.split("/")[-1]
+    if not filename:
+        return None
+
+    # Handle wheel files: package-version-py3-none-any.whl
+    wheel_pattern = r"^([a-zA-Z0-9_-]+)-(\d+[^-]*)-.*\.whl$"
+    match = re.match(wheel_pattern, filename)
+    if match:
+        name, version = match.groups()
+        # Normalize package name (PyPI uses underscores internally)
+        name = name.replace("_", "-").lower()
+        return ParsedUrl(
+            package_name=name,
+            version=version,
+            filename=filename,
+        )
+
+    # Handle source distributions: package-version.tar.gz or package-version.zip
+    sdist_pattern = r"^([a-zA-Z0-9_-]+)-(\d+(?:\.\d+)*(?:[a-zA-Z0-9_.+-]*)?)(?:\.tar\.gz|\.zip|\.tar\.bz2)$"
+    match = re.match(sdist_pattern, filename)
+    if match:
+        name, version = match.groups()
+        name = name.replace("_", "-").lower()
+        return ParsedUrl(
+            package_name=name,
+            version=version,
+            filename=filename,
+        )
+
+    return None
+
+
+def parse_maven_url(url: str) -> Optional[ParsedUrl]:
+    """
+    Parse Maven repository URL to extract artifact info.
+
+    Format:
+    - https://repo1.maven.org/maven2/{group}/{artifact}/{version}/{artifact}-{version}.jar
+
+    Examples:
+    - https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.12.0/commons-lang3-3.12.0.jar
+    - https://repo1.maven.org/maven2/com/google/guava/guava/31.1-jre/guava-31.1-jre.jar
+    """
+    parsed = urlparse(url)
+    path = unquote(parsed.path)
+
+    # Find /maven2/ or similar repository path
+    maven2_idx = path.find("/maven2/")
+    if maven2_idx >= 0:
+        path = path[maven2_idx + 8:]  # Remove /maven2/
+    elif path.startswith("/"):
+        path = path[1:]
+
+    parts = path.split("/")
+    if len(parts) < 4:
+        return None
+
+    # Last part is filename, before that is version, before that is artifact
+    filename = parts[-1]
+    version = parts[-2]
+    artifact = parts[-3]
+    group = ".".join(parts[:-3])
+
+    # Verify filename matches expected pattern
+    if not filename.startswith(f"{artifact}-{version}"):
+        return None
+
+    return ParsedUrl(
+        package_name=f"{group}:{artifact}",
+        version=version,
+        filename=filename,
+    )
+
+
+def parse_docker_url(url: str) -> Optional[ParsedUrl]:
+    """
+    Parse Docker registry URL to extract image info.
+
+    Note: Docker registries are more complex (manifests, blobs, etc.)
+    This handles basic blob/manifest URLs.
+
+    Examples:
+    - https://registry-1.docker.io/v2/library/nginx/blobs/sha256:abc123
+    - https://registry-1.docker.io/v2/myuser/myimage/manifests/latest
+    """
+    parsed = urlparse(url)
+    path = unquote(parsed.path)
+
+    # Pattern: /v2/{namespace}/{image}/blobs/{digest} or /manifests/{tag}
+    pattern = r"^/v2/([^/]+(?:/[^/]+)?)/([^/]+)/(blobs|manifests)/(.+)$"
+    match = re.match(pattern, path)
+    if match:
+        namespace, image, artifact_type, reference = match.groups()
+        if namespace == "library":
+            package_name = image
+        else:
+            package_name = f"{namespace}/{image}"
+
+        # For manifests, the reference is the tag
+        version = reference if artifact_type == "manifests" else None
+
+        return ParsedUrl(
+            package_name=package_name,
+            version=version,
+            filename=f"{image}-{reference}" if version else reference,
+        )
+
+    return None
+
+
+def parse_generic_url(url: str) -> ParsedUrl:
+    """
+    Parse a generic URL to extract filename.
+
+    Attempts to extract meaningful package name and version from filename.
+
+    Examples:
+    - https://example.com/downloads/myapp-1.2.3.tar.gz
+    - https://github.com/user/repo/releases/download/v1.0/release.zip
+    """
+    parsed = urlparse(url)
+    path = unquote(parsed.path)
+    filename = path.split("/")[-1] or "artifact"
+
+    # List of known compound and simple extensions
+    known_extensions = [
+        ".tar.gz", ".tar.bz2", ".tar.xz",
+        ".zip", ".tgz", ".gz", ".jar", ".war", ".deb", ".rpm"
+    ]
+
+    # Strip extension from filename first
+    base_name = filename
+    matched_ext = None
+    for ext in known_extensions:
+        if filename.endswith(ext):
+            base_name = filename[:-len(ext)]
+            matched_ext = ext
+            break
+
+    if matched_ext is None:
+        # Unknown extension, return filename as package name
+        return ParsedUrl(
+            package_name=filename,
+            version=None,
+            filename=filename,
+        )
+
+    # Try to extract version from base_name
+    # Pattern: name-version or name_version
+    # Version starts with digit(s) and can include dots, dashes, and alphanumeric suffixes
+    version_pattern = r"^(.+?)[-_](v?\d+(?:\.\d+)*(?:[-_][a-zA-Z0-9]+)?)$"
+    match = re.match(version_pattern, base_name)
+    if match:
+        name, version = match.groups()
+        return ParsedUrl(
+            package_name=name,
+            version=version,
+            filename=filename,
+        )
+
+    # No version found, use base_name as package name
+    return ParsedUrl(
+        package_name=base_name,
+        version=None,
+        filename=filename,
+    )
+
+
+def parse_url(url: str, source_type: str) -> ParsedUrl:
+    """
+    Parse URL to extract package name and version based on source type.
+
+    Args:
+        url: The URL to parse.
+        source_type: The source type (npm, pypi, maven, docker, etc.)
+
+    Returns:
+        ParsedUrl with extracted information.
+    """
+    parsed = None
+
+    if source_type == "npm":
+        parsed = parse_npm_url(url)
+    elif source_type == "pypi":
+        parsed = parse_pypi_url(url)
+    elif source_type == "maven":
+        parsed = parse_maven_url(url)
+    elif source_type == "docker":
+        parsed = parse_docker_url(url)
+
+    # Fall back to generic parsing if type-specific parsing fails
+    if parsed is None:
+        parsed = parse_generic_url(url)
+
+    return parsed
+
+
+def get_system_project_name(source_type: str) -> str:
+    """Get the system project name for a source type."""
+    return SYSTEM_PROJECT_NAMES.get(source_type, "_generic")
+
+
+def get_system_project_description(source_type: str) -> str:
+    """Get the system project description for a source type."""
+    return SYSTEM_PROJECT_DESCRIPTIONS.get(
+        source_type, "System cache for artifacts"
+    )

backend/app/config.py

@@ -1,5 +1,8 @@
 from pydantic_settings import BaseSettings
 from functools import lru_cache
+from typing import Optional
+import os
+import re
 
 
 class Settings(BaseSettings):
@@ -48,6 +51,7 @@ class Settings(BaseSettings):
     presigned_url_expiry: int = (
         3600  # Presigned URL expiry in seconds (default: 1 hour)
     )
+    pypi_download_mode: str = "redirect"  # "redirect" (to S3) or "proxy" (stream through Orchard)
 
     # Logging settings
     log_level: str = "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL
@@ -56,6 +60,16 @@ class Settings(BaseSettings):
     # Initial admin user settings
     admin_password: str = ""  # Initial admin password (if empty, uses 'changeme123')
 
+    # Cache settings
+    cache_encryption_key: str = ""  # Fernet key for encrypting upstream credentials (auto-generated if empty)
+    # Global cache settings override (None = use DB value, True/False = override DB)
+    cache_auto_create_system_projects: Optional[bool] = None  # Override auto_create_system_projects
+
+    # PyPI Cache Worker settings
+    pypi_cache_workers: int = 5  # Number of concurrent cache workers
+    pypi_cache_max_depth: int = 10  # Maximum recursion depth for dependency caching
+    pypi_cache_max_attempts: int = 3  # Maximum retry attempts for failed cache tasks
+
     # JWT Authentication settings (optional, for external identity providers)
     jwt_enabled: bool = False  # Enable JWT token validation
     jwt_secret: str = ""  # Secret key for HS256, or leave empty for RS256 with JWKS
@@ -80,6 +94,24 @@ class Settings(BaseSettings):
     def is_production(self) -> bool:
         return self.env.lower() == "production"
 
+    @property
+    def PORT(self) -> int:
+        """Alias for server_port for compatibility."""
+        return self.server_port
+
+    # Uppercase aliases for PyPI cache settings (for backward compatibility)
+    @property
+    def PYPI_CACHE_WORKERS(self) -> int:
+        return self.pypi_cache_workers
+
+    @property
+    def PYPI_CACHE_MAX_DEPTH(self) -> int:
+        return self.pypi_cache_max_depth
+
+    @property
+    def PYPI_CACHE_MAX_ATTEMPTS(self) -> int:
+        return self.pypi_cache_max_attempts
+
     class Config:
         env_prefix = "ORCHARD_"
         case_sensitive = False
@@ -88,3 +120,110 @@ class Settings(BaseSettings):
 @lru_cache()
 def get_settings() -> Settings:
     return Settings()
+
+
+class EnvUpstreamSource:
+    """Represents an upstream source defined via environment variables."""
+
+    def __init__(
+        self,
+        name: str,
+        url: str,
+        source_type: str = "generic",
+        enabled: bool = True,
+        auth_type: str = "none",
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        priority: int = 100,
+    ):
+        self.name = name
+        self.url = url
+        self.source_type = source_type
+        self.enabled = enabled
+        self.auth_type = auth_type
+        self.username = username
+        self.password = password
+        self.priority = priority
+        self.source = "env"  # Mark as env-defined
+
+
+def parse_upstream_sources_from_env() -> list[EnvUpstreamSource]:
+    """
+    Parse upstream sources from environment variables.
+
+    Uses double underscore (__) as separator to allow source names with single underscores.
+    Pattern: ORCHARD_UPSTREAM__{NAME}__FIELD
+
+    Example:
+        ORCHARD_UPSTREAM__NPM_PRIVATE__URL=https://npm.corp.com
+        ORCHARD_UPSTREAM__NPM_PRIVATE__TYPE=npm
+        ORCHARD_UPSTREAM__NPM_PRIVATE__ENABLED=true
+        ORCHARD_UPSTREAM__NPM_PRIVATE__AUTH_TYPE=basic
+        ORCHARD_UPSTREAM__NPM_PRIVATE__USERNAME=reader
+        ORCHARD_UPSTREAM__NPM_PRIVATE__PASSWORD=secret
+
+    Returns:
+        List of EnvUpstreamSource objects parsed from environment variables.
+    """
+    # Pattern: ORCHARD_UPSTREAM__{NAME}__{FIELD}
+    pattern = re.compile(r"^ORCHARD_UPSTREAM__([A-Z0-9_]+)__([A-Z_]+)$", re.IGNORECASE)
+
+    # Collect all env vars matching the pattern, grouped by source name
+    sources_data: dict[str, dict[str, str]] = {}
+
+    for key, value in os.environ.items():
+        match = pattern.match(key)
+        if match:
+            source_name = match.group(1).lower()  # Normalize to lowercase
+            field = match.group(2).upper()
+            if source_name not in sources_data:
+                sources_data[source_name] = {}
+            sources_data[source_name][field] = value
+
+    # Build source objects from collected data
+    sources: list[EnvUpstreamSource] = []
+
+    for name, data in sources_data.items():
+        # URL is required
+        url = data.get("URL")
+        if not url:
+            continue  # Skip sources without URL
+
+        # Parse boolean fields
+        def parse_bool(val: Optional[str], default: bool) -> bool:
+            if val is None:
+                return default
+            return val.lower() in ("true", "1", "yes", "on")
+
+        # Parse integer fields
+        def parse_int(val: Optional[str], default: int) -> int:
+            if val is None:
+                return default
+            try:
+                return int(val)
+            except ValueError:
+                return default
+
+        source = EnvUpstreamSource(
+            name=name.replace("_", "-"),  # Convert underscores to hyphens for readability
+            url=url,
+            source_type=data.get("TYPE", "generic").lower(),
+            enabled=parse_bool(data.get("ENABLED"), True),
+            auth_type=data.get("AUTH_TYPE", "none").lower(),
+            username=data.get("USERNAME"),
+            password=data.get("PASSWORD"),
+            priority=parse_int(data.get("PRIORITY"), 100),
+        )
+        sources.append(source)
+
+    return sources
+
+
+@lru_cache()
+def get_env_upstream_sources() -> tuple[EnvUpstreamSource, ...]:
+    """
+    Get cached list of upstream sources from environment variables.
+
+    Returns a tuple for hashability (required by lru_cache).
+    """
+    return tuple(parse_upstream_sources_from_env())

backend/app/database.py

@@ -1,17 +1,34 @@
 from sqlalchemy import create_engine, text, event
 from sqlalchemy.orm import sessionmaker, Session
 from sqlalchemy.pool import QueuePool
-from typing import Generator
+from typing import Generator, NamedTuple
 from contextlib import contextmanager
 import logging
 import time
+import hashlib
 
 from .config import get_settings
 from .models import Base
+from .purge_seed_data import should_purge_seed_data, purge_seed_data
 
 settings = get_settings()
 logger = logging.getLogger(__name__)
 
+
+class Migration(NamedTuple):
+    """A database migration with a unique name and SQL to execute."""
+    name: str
+    sql: str
+
+
+# PostgreSQL error codes that indicate "already exists" - safe to skip
+SAFE_PG_ERROR_CODES = {
+    "42P07",  # duplicate_table
+    "42701",  # duplicate_column
+    "42710",  # duplicate_object (index, constraint, etc.)
+    "42P16",  # invalid_table_definition (e.g., column already exists)
+}
+
 # Build connect_args with query timeout if configured
 connect_args = {}
 if settings.database_query_timeout > 0:
@@ -64,12 +81,74 @@ def init_db():
     # Run migrations for schema updates
     _run_migrations()
 
+    # Purge seed data if requested (for transitioning to production-like environment)
+    if should_purge_seed_data():
+        db = SessionLocal()
+        try:
+            purge_seed_data(db)
+        finally:
+            db.close()
+
+
+def _ensure_migrations_table(conn) -> None:
+    """Create the migrations tracking table if it doesn't exist."""
+    conn.execute(text("""
+        CREATE TABLE IF NOT EXISTS _schema_migrations (
+            name VARCHAR(255) PRIMARY KEY,
+            checksum VARCHAR(64) NOT NULL,
+            applied_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+        );
+    """))
+    conn.commit()
+
+
+def _get_applied_migrations(conn) -> dict[str, str]:
+    """Get all applied migrations and their checksums."""
+    result = conn.execute(text(
+        "SELECT name, checksum FROM _schema_migrations"
+    ))
+    return {row[0]: row[1] for row in result}
+
+
+def _compute_checksum(sql: str) -> str:
+    """Compute a checksum for migration SQL to detect changes."""
+    return hashlib.sha256(sql.strip().encode()).hexdigest()[:16]
+
+
+def _is_safe_error(exception: Exception) -> bool:
+    """Check if the error indicates the migration was already applied."""
+    # Check for psycopg2 errors with pgcode attribute
+    original = getattr(exception, "orig", None)
+    if original is not None:
+        pgcode = getattr(original, "pgcode", None)
+        if pgcode in SAFE_PG_ERROR_CODES:
+            return True
+
+    # Fallback: check error message for common "already exists" patterns
+    error_str = str(exception).lower()
+    safe_patterns = [
+        "already exists",
+        "duplicate key",
+        "relation .* already exists",
+        "column .* already exists",
+    ]
+    return any(pattern in error_str for pattern in safe_patterns)
+
+
+def _record_migration(conn, name: str, checksum: str) -> None:
+    """Record a migration as applied."""
+    conn.execute(text(
+        "INSERT INTO _schema_migrations (name, checksum) VALUES (:name, :checksum)"
+    ), {"name": name, "checksum": checksum})
+    conn.commit()
+
 
 def _run_migrations():
-    """Run manual migrations for schema updates"""
+    """Run manual migrations for schema updates with tracking and error detection."""
     migrations = [
-        # Add format_metadata column to artifacts table
-        """
+        Migration(
+            name="001_add_format_metadata",
+            sql="""
             DO $$
             BEGIN
                 IF NOT EXISTS (
@@ -80,8 +159,10 @@ def _run_migrations():
                 END IF;
             END $$;
             """,
-        # Add format column to packages table
-        """
+        ),
+        Migration(
+            name="002_add_package_format",
+            sql="""
             DO $$
             BEGIN
                 IF NOT EXISTS (
@@ -93,8 +174,10 @@ def _run_migrations():
                 END IF;
             END $$;
             """,
-        # Add platform column to packages table
-        """
+        ),
+        Migration(
+            name="003_add_package_platform",
+            sql="""
             DO $$
             BEGIN
                 IF NOT EXISTS (
@@ -106,18 +189,18 @@ def _run_migrations():
                 END IF;
             END $$;
             """,
-        # Add ref_count index and constraints for artifacts
-        """
+        ),
+        Migration(
+            name="004_add_ref_count_index_constraint",
+            sql="""
             DO $$
             BEGIN
-            -- Add ref_count index
                 IF NOT EXISTS (
                     SELECT 1 FROM pg_indexes WHERE indexname = 'idx_artifacts_ref_count'
                 ) THEN
                     CREATE INDEX idx_artifacts_ref_count ON artifacts(ref_count);
                 END IF;
 
-            -- Add ref_count >= 0 constraint
                 IF NOT EXISTS (
                     SELECT 1 FROM pg_constraint WHERE conname = 'check_ref_count_non_negative'
                 ) THEN
@@ -125,39 +208,28 @@ def _run_migrations():
                 END IF;
             END $$;
             """,
-        # Add composite indexes for packages and tags
-        """
+        ),
+        Migration(
+            name="005_add_composite_indexes",
+            sql="""
             DO $$
             BEGIN
-            -- Composite index for package lookup by project and name
                 IF NOT EXISTS (
                     SELECT 1 FROM pg_indexes WHERE indexname = 'idx_packages_project_name'
                 ) THEN
                     CREATE UNIQUE INDEX idx_packages_project_name ON packages(project_id, name);
                 END IF;
 
-            -- Composite index for tag lookup by package and name
-            IF NOT EXISTS (
-                SELECT 1 FROM pg_indexes WHERE indexname = 'idx_tags_package_name'
-            ) THEN
-                CREATE UNIQUE INDEX idx_tags_package_name ON tags(package_id, name);
-            END IF;
-
-            -- Composite index for recent tags queries
-            IF NOT EXISTS (
-                SELECT 1 FROM pg_indexes WHERE indexname = 'idx_tags_package_created_at'
-            ) THEN
-                CREATE INDEX idx_tags_package_created_at ON tags(package_id, created_at);
-            END IF;
+                -- Tag indexes removed: tags table no longer exists (removed in tag system removal)
             END $$;
             """,
-        # Add package_versions indexes and triggers (007_package_versions.sql)
-        """
+        ),
+        Migration(
+            name="006_add_package_versions_indexes",
+            sql="""
             DO $$
             BEGIN
-            -- Create indexes for package_versions if table exists
                 IF EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name = 'package_versions') THEN
-                -- Indexes for common queries
                     IF NOT EXISTS (SELECT 1 FROM pg_indexes WHERE indexname = 'idx_package_versions_package_id') THEN
                         CREATE INDEX idx_package_versions_package_id ON package_versions(package_id);
                     END IF;
@@ -170,8 +242,10 @@ def _run_migrations():
                 END IF;
             END $$;
             """,
-        # Create ref_count trigger functions for tags (ensures triggers exist even if initial migration wasn't run)
-        """
+        ),
+        Migration(
+            name="007_create_ref_count_trigger_functions",
+            sql="""
             CREATE OR REPLACE FUNCTION increment_artifact_ref_count()
             RETURNS TRIGGER AS $$
             BEGIN
@@ -179,8 +253,7 @@ def _run_migrations():
                 RETURN NEW;
             END;
             $$ LANGUAGE plpgsql;
-        """,
-        """
+
             CREATE OR REPLACE FUNCTION decrement_artifact_ref_count()
             RETURNS TRIGGER AS $$
             BEGIN
@@ -188,8 +261,7 @@ def _run_migrations():
                 RETURN OLD;
             END;
             $$ LANGUAGE plpgsql;
-        """,
-        """
+
             CREATE OR REPLACE FUNCTION update_artifact_ref_count()
             RETURNS TRIGGER AS $$
             BEGIN
@@ -201,33 +273,17 @@ def _run_migrations():
             END;
             $$ LANGUAGE plpgsql;
             """,
-        # Create triggers for tags ref_count management
-        """
-        DO $$
-        BEGIN
-            -- Drop and recreate triggers to ensure they're current
-            DROP TRIGGER IF EXISTS tags_ref_count_insert_trigger ON tags;
-            CREATE TRIGGER tags_ref_count_insert_trigger
-                AFTER INSERT ON tags
-                FOR EACH ROW
-                EXECUTE FUNCTION increment_artifact_ref_count();
-
-            DROP TRIGGER IF EXISTS tags_ref_count_delete_trigger ON tags;
-            CREATE TRIGGER tags_ref_count_delete_trigger
-                AFTER DELETE ON tags
-                FOR EACH ROW
-                EXECUTE FUNCTION decrement_artifact_ref_count();
-
-            DROP TRIGGER IF EXISTS tags_ref_count_update_trigger ON tags;
-            CREATE TRIGGER tags_ref_count_update_trigger
-                AFTER UPDATE ON tags
-                FOR EACH ROW
-                WHEN (OLD.artifact_id IS DISTINCT FROM NEW.artifact_id)
-                EXECUTE FUNCTION update_artifact_ref_count();
-        END $$;
+        ),
+        Migration(
+            name="008_create_tags_ref_count_triggers",
+            sql="""
+            -- Tags table removed: triggers no longer needed (tag system removed)
+            DO $$ BEGIN NULL; END $$;
             """,
-        # Create ref_count trigger functions for package_versions
-        """
+        ),
+        Migration(
+            name="009_create_version_ref_count_functions",
+            sql="""
             CREATE OR REPLACE FUNCTION increment_version_ref_count()
             RETURNS TRIGGER AS $$
             BEGIN
@@ -235,8 +291,7 @@ def _run_migrations():
                 RETURN NEW;
             END;
             $$ LANGUAGE plpgsql;
-        """,
-        """
+
             CREATE OR REPLACE FUNCTION decrement_version_ref_count()
             RETURNS TRIGGER AS $$
             BEGIN
@@ -245,12 +300,13 @@ def _run_migrations():
             END;
             $$ LANGUAGE plpgsql;
             """,
-        # Create triggers for package_versions ref_count
-        """
+        ),
+        Migration(
+            name="010_create_package_versions_triggers",
+            sql="""
             DO $$
             BEGIN
                 IF EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name = 'package_versions') THEN
-                -- Drop and recreate triggers to ensure they're current
                     DROP TRIGGER IF EXISTS package_versions_ref_count_insert ON package_versions;
                     CREATE TRIGGER package_versions_ref_count_insert
                         AFTER INSERT ON package_versions
@@ -265,14 +321,18 @@ def _run_migrations():
                 END IF;
             END $$;
             """,
-        # Migrate existing semver tags to package_versions
-        r"""
+        ),
+        Migration(
+            name="011_migrate_semver_tags_to_versions",
+            sql=r"""
+            -- Migrate semver tags to versions (only if both tables exist - for existing databases)
             DO $$
             BEGIN
-            IF EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name = 'package_versions') THEN
-                -- Migrate tags that look like versions (v1.0.0, 1.2.3, 2.0.0-beta, etc.)
-                INSERT INTO package_versions (package_id, artifact_id, version, version_source, created_by, created_at)
+                IF EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name = 'package_versions')
+                   AND EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name = 'tags') THEN
+                    INSERT INTO package_versions (id, package_id, artifact_id, version, version_source, created_by, created_at)
                     SELECT
+                        gen_random_uuid(),
                         t.package_id,
                         t.artifact_id,
                         CASE WHEN t.name LIKE 'v%' THEN substring(t.name from 2) ELSE t.name END,
@@ -285,36 +345,40 @@ def _run_migrations():
                 END IF;
             END $$;
             """,
-        # Teams and multi-tenancy migration (009_teams.sql)
-        """
-        -- Create teams table
+        ),
+        Migration(
+            name="012_create_teams_table",
+            sql="""
             CREATE TABLE IF NOT EXISTS teams (
                 id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
                 name VARCHAR(255) NOT NULL,
                 slug VARCHAR(255) NOT NULL UNIQUE,
                 description TEXT,
-            created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
-            updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+                updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
                 created_by VARCHAR(255) NOT NULL,
-            settings JSONB DEFAULT '{}'::jsonb,
-            CONSTRAINT check_team_slug_format CHECK (slug ~ '^[a-z0-9][a-z0-9-]*[a-z0-9]$' OR slug ~ '^[a-z0-9]$')
+                settings JSONB DEFAULT '{}'
             );
             """,
-        """
-        -- Create team_memberships table
+        ),
+        Migration(
+            name="013_create_team_memberships_table",
+            sql="""
             CREATE TABLE IF NOT EXISTS team_memberships (
                 id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
                 team_id UUID NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
                 user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-            role VARCHAR(20) NOT NULL DEFAULT 'member',
-            created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+                role VARCHAR(50) NOT NULL DEFAULT 'member',
+                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
                 invited_by VARCHAR(255),
-            CONSTRAINT unique_team_membership UNIQUE (team_id, user_id),
-            CONSTRAINT check_team_role CHECK (role IN ('owner', 'admin', 'member'))
+                CONSTRAINT team_memberships_unique UNIQUE (team_id, user_id),
+                CONSTRAINT team_memberships_role_check CHECK (role IN ('owner', 'admin', 'member'))
             );
             """,
-        # Add team_id column to projects table
-        """
+        ),
+        Migration(
+            name="014_add_team_id_to_projects",
+            sql="""
             DO $$
             BEGIN
                 IF NOT EXISTS (
@@ -322,11 +386,14 @@ def _run_migrations():
                     WHERE table_name = 'projects' AND column_name = 'team_id'
                 ) THEN
                     ALTER TABLE projects ADD COLUMN team_id UUID REFERENCES teams(id) ON DELETE SET NULL;
+                    CREATE INDEX IF NOT EXISTS idx_projects_team_id ON projects(team_id);
                 END IF;
             END $$;
             """,
-        # Create indexes for teams
-        """
+        ),
+        Migration(
+            name="015_add_teams_indexes",
+            sql="""
             DO $$
             BEGIN
                 IF NOT EXISTS (SELECT 1 FROM pg_indexes WHERE indexname = 'idx_teams_slug') THEN
@@ -335,32 +402,241 @@ def _run_migrations():
                 IF NOT EXISTS (SELECT 1 FROM pg_indexes WHERE indexname = 'idx_teams_created_by') THEN
                     CREATE INDEX idx_teams_created_by ON teams(created_by);
                 END IF;
-            IF NOT EXISTS (SELECT 1 FROM pg_indexes WHERE indexname = 'idx_teams_created_at') THEN
-                CREATE INDEX idx_teams_created_at ON teams(created_at);
-            END IF;
                 IF NOT EXISTS (SELECT 1 FROM pg_indexes WHERE indexname = 'idx_team_memberships_team_id') THEN
                     CREATE INDEX idx_team_memberships_team_id ON team_memberships(team_id);
                 END IF;
                 IF NOT EXISTS (SELECT 1 FROM pg_indexes WHERE indexname = 'idx_team_memberships_user_id') THEN
                     CREATE INDEX idx_team_memberships_user_id ON team_memberships(user_id);
                 END IF;
-            IF NOT EXISTS (SELECT 1 FROM pg_indexes WHERE indexname = 'idx_team_memberships_role') THEN
-                CREATE INDEX idx_team_memberships_role ON team_memberships(role);
-            END IF;
-            IF NOT EXISTS (SELECT 1 FROM pg_indexes WHERE indexname = 'idx_projects_team_id') THEN
-                CREATE INDEX idx_projects_team_id ON projects(team_id);
+            END $$;
+            """,
+        ),
+        Migration(
+            name="016_add_is_system_to_projects",
+            sql="""
+            DO $$
+            BEGIN
+                IF NOT EXISTS (
+                    SELECT 1 FROM information_schema.columns
+                    WHERE table_name = 'projects' AND column_name = 'is_system'
+                ) THEN
+                    ALTER TABLE projects ADD COLUMN is_system BOOLEAN NOT NULL DEFAULT FALSE;
+                    CREATE INDEX IF NOT EXISTS idx_projects_is_system ON projects(is_system);
                 END IF;
             END $$;
             """,
+        ),
+        Migration(
+            name="017_create_upstream_sources",
+            sql="""
+            CREATE TABLE IF NOT EXISTS upstream_sources (
+                id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+                name VARCHAR(255) NOT NULL UNIQUE,
+                source_type VARCHAR(50) NOT NULL DEFAULT 'generic',
+                url VARCHAR(2048) NOT NULL,
+                enabled BOOLEAN NOT NULL DEFAULT FALSE,
+                auth_type VARCHAR(20) NOT NULL DEFAULT 'none',
+                username VARCHAR(255),
+                password_encrypted BYTEA,
+                headers_encrypted BYTEA,
+                priority INTEGER NOT NULL DEFAULT 100,
+                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+                updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+                CONSTRAINT check_source_type CHECK (
+                    source_type IN ('npm', 'pypi', 'maven', 'docker', 'helm', 'nuget', 'deb', 'rpm', 'generic')
+                ),
+                CONSTRAINT check_auth_type CHECK (
+                    auth_type IN ('none', 'basic', 'bearer', 'api_key')
+                ),
+                CONSTRAINT check_priority_positive CHECK (priority > 0)
+            );
+            CREATE INDEX IF NOT EXISTS idx_upstream_sources_enabled ON upstream_sources(enabled);
+            CREATE INDEX IF NOT EXISTS idx_upstream_sources_source_type ON upstream_sources(source_type);
+            CREATE INDEX IF NOT EXISTS idx_upstream_sources_priority ON upstream_sources(priority);
+            """,
+        ),
+        Migration(
+            name="018_create_cache_settings",
+            sql="""
+            CREATE TABLE IF NOT EXISTS cache_settings (
+                id INTEGER PRIMARY KEY DEFAULT 1,
+                auto_create_system_projects BOOLEAN NOT NULL DEFAULT TRUE,
+                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+                updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+                CONSTRAINT check_cache_settings_singleton CHECK (id = 1)
+            );
+            INSERT INTO cache_settings (id, auto_create_system_projects)
+            VALUES (1, TRUE)
+            ON CONFLICT (id) DO NOTHING;
+            """,
+        ),
+        Migration(
+            name="019_create_cached_urls",
+            sql="""
+            CREATE TABLE IF NOT EXISTS cached_urls (
+                id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+                url VARCHAR(4096) NOT NULL,
+                url_hash VARCHAR(64) NOT NULL UNIQUE,
+                artifact_id VARCHAR(64) NOT NULL REFERENCES artifacts(id),
+                source_id UUID REFERENCES upstream_sources(id) ON DELETE SET NULL,
+                fetched_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+                response_headers JSONB DEFAULT '{}',
+                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+            );
+            CREATE INDEX IF NOT EXISTS idx_cached_urls_url_hash ON cached_urls(url_hash);
+            CREATE INDEX IF NOT EXISTS idx_cached_urls_artifact_id ON cached_urls(artifact_id);
+            CREATE INDEX IF NOT EXISTS idx_cached_urls_source_id ON cached_urls(source_id);
+            CREATE INDEX IF NOT EXISTS idx_cached_urls_fetched_at ON cached_urls(fetched_at);
+            """,
+        ),
+        Migration(
+            name="020_seed_default_upstream_sources",
+            sql="""
+            -- Originally seeded public sources, but these are no longer used.
+            -- Migration 023 deletes any previously seeded sources.
+            -- This migration is now a no-op for fresh installs.
+            SELECT 1;
+            """,
+        ),
+        Migration(
+            name="021_remove_is_public_from_upstream_sources",
+            sql="""
+            DO $$
+            BEGIN
+                -- Drop the index if it exists
+                DROP INDEX IF EXISTS idx_upstream_sources_is_public;
+
+                -- Drop the column if it exists
+                IF EXISTS (
+                    SELECT 1 FROM information_schema.columns
+                    WHERE table_name = 'upstream_sources' AND column_name = 'is_public'
+                ) THEN
+                    ALTER TABLE upstream_sources DROP COLUMN is_public;
+                END IF;
+            END $$;
+            """,
+        ),
+        Migration(
+            name="022_remove_allow_public_internet_from_cache_settings",
+            sql="""
+            DO $$
+            BEGIN
+                IF EXISTS (
+                    SELECT 1 FROM information_schema.columns
+                    WHERE table_name = 'cache_settings' AND column_name = 'allow_public_internet'
+                ) THEN
+                    ALTER TABLE cache_settings DROP COLUMN allow_public_internet;
+                END IF;
+            END $$;
+            """,
+        ),
+        Migration(
+            name="023_delete_seeded_public_sources",
+            sql="""
+            -- Delete the seeded public sources that were added by migration 020
+            DELETE FROM upstream_sources
+            WHERE name IN ('npm-public', 'pypi-public', 'maven-central', 'docker-hub');
+            """,
+        ),
+        Migration(
+            name="024_remove_tags",
+            sql="""
+            -- Remove tag system, keeping only versions for artifact references
+            DO $$
+            BEGIN
+                -- Drop triggers on tags table (if they exist)
+                DROP TRIGGER IF EXISTS tags_ref_count_insert_trigger ON tags;
+                DROP TRIGGER IF EXISTS tags_ref_count_delete_trigger ON tags;
+                DROP TRIGGER IF EXISTS tags_ref_count_update_trigger ON tags;
+                DROP TRIGGER IF EXISTS tags_updated_at_trigger ON tags;
+                DROP TRIGGER IF EXISTS tag_changes_trigger ON tags;
+
+                -- Drop the tag change tracking function
+                DROP FUNCTION IF EXISTS track_tag_changes();
+
+                -- Remove tag_constraint from artifact_dependencies
+                IF EXISTS (
+                    SELECT 1 FROM information_schema.table_constraints
+                    WHERE constraint_name = 'check_constraint_type'
+                    AND table_name = 'artifact_dependencies'
+                ) THEN
+                    ALTER TABLE artifact_dependencies DROP CONSTRAINT check_constraint_type;
+                END IF;
+
+                -- Remove the tag_constraint column if it exists
+                IF EXISTS (
+                    SELECT 1 FROM information_schema.columns
+                    WHERE table_name = 'artifact_dependencies' AND column_name = 'tag_constraint'
+                ) THEN
+                    ALTER TABLE artifact_dependencies DROP COLUMN tag_constraint;
+                END IF;
+
+                -- Make version_constraint NOT NULL
+                UPDATE artifact_dependencies SET version_constraint = '*' WHERE version_constraint IS NULL;
+                ALTER TABLE artifact_dependencies ALTER COLUMN version_constraint SET NOT NULL;
+
+                -- Drop tag_history table first (depends on tags)
+                DROP TABLE IF EXISTS tag_history;
+
+                -- Drop tags table
+                DROP TABLE IF EXISTS tags;
+
+                -- Rename uploads.tag_name to version if it exists and version doesn't
+                IF EXISTS (
+                    SELECT 1 FROM information_schema.columns
+                    WHERE table_name = 'uploads' AND column_name = 'tag_name'
+                ) AND NOT EXISTS (
+                    SELECT 1 FROM information_schema.columns
+                    WHERE table_name = 'uploads' AND column_name = 'version'
+                ) THEN
+                    ALTER TABLE uploads RENAME COLUMN tag_name TO version;
+                END IF;
+            END $$;
+            """,
+        ),
     ]
 
     with engine.connect() as conn:
+        # Ensure migrations tracking table exists
+        _ensure_migrations_table(conn)
+
+        # Get already-applied migrations
+        applied = _get_applied_migrations(conn)
+
         for migration in migrations:
+            checksum = _compute_checksum(migration.sql)
+
+            # Check if migration was already applied
+            if migration.name in applied:
+                stored_checksum = applied[migration.name]
+                if stored_checksum != checksum:
+                    logger.warning(
+                        f"Migration '{migration.name}' has changed since it was applied! "
+                        f"Stored checksum: {stored_checksum}, current: {checksum}"
+                    )
+                continue
+
+            # Run the migration
             try:
-                conn.execute(text(migration))
+                logger.info(f"Running migration: {migration.name}")
+                conn.execute(text(migration.sql))
                 conn.commit()
+                _record_migration(conn, migration.name, checksum)
+                logger.info(f"Migration '{migration.name}' applied successfully")
             except Exception as e:
-                logger.warning(f"Migration failed (may already be applied): {e}")
+                conn.rollback()
+                if _is_safe_error(e):
+                    # Migration was already applied (schema already exists)
+                    logger.info(
+                        f"Migration '{migration.name}' already applied (schema exists), recording as complete"
+                    )
+                    _record_migration(conn, migration.name, checksum)
+                else:
+                    # Real error - fail hard
+                    logger.error(f"Migration '{migration.name}' failed: {e}")
+                    raise RuntimeError(
+                        f"Migration '{migration.name}' failed with error: {e}"
+                    ) from e
 
 
 def get_db() -> Generator[Session, None, None]:

backend/app/dependencies.py

@@ -10,16 +10,24 @@ Handles:
 - Conflict detection
 """
 
+import re
 import yaml
 from typing import List, Dict, Any, Optional, Set, Tuple
 from sqlalchemy.orm import Session
 from sqlalchemy import and_
 
+# Import packaging for PEP 440 version matching
+try:
+    from packaging.specifiers import SpecifierSet, InvalidSpecifier
+    from packaging.version import Version, InvalidVersion
+    HAS_PACKAGING = True
+except ImportError:
+    HAS_PACKAGING = False
+
 from .models import (
     Project,
     Package,
     Artifact,
-    Tag,
     ArtifactDependency,
     PackageVersion,
 )
@@ -33,10 +41,27 @@ from .schemas import (
     ResolvedArtifact,
     DependencyResolutionResponse,
     DependencyConflict,
+    MissingDependency,
     PaginationMeta,
 )
 
 
+def _normalize_pypi_package_name(name: str) -> str:
+    """
+    Normalize a PyPI package name for comparison.
+
+    - Strips extras brackets (e.g., "package[extra]" -> "package")
+    - Replaces sequences of hyphens, underscores, and dots with a single hyphen
+    - Lowercases the result
+
+    This follows PEP 503 normalization rules.
+    """
+    # Strip extras brackets like [test], [dev], etc.
+    base_name = re.sub(r'\[.*\]', '', name)
+    # Normalize separators and lowercase
+    return re.sub(r'[-_.]+', '-', base_name).lower()
+
+
 class DependencyError(Exception):
     """Base exception for dependency errors."""
     pass
@@ -127,26 +152,20 @@ def parse_ensure_file(content: bytes) -> EnsureFileContent:
         project = dep.get('project')
         package = dep.get('package')
         version = dep.get('version')
-        tag = dep.get('tag')
 
         if not project:
             raise InvalidEnsureFileError(f"Dependency {i} missing 'project'")
         if not package:
             raise InvalidEnsureFileError(f"Dependency {i} missing 'package'")
-        if not version and not tag:
+        if not version:
             raise InvalidEnsureFileError(
-                f"Dependency {i} must have either 'version' or 'tag'"
-            )
-        if version and tag:
-            raise InvalidEnsureFileError(
-                f"Dependency {i} cannot have both 'version' and 'tag'"
+                f"Dependency {i} must have 'version'"
             )
 
         dependencies.append(EnsureFileDependency(
             project=project,
             package=package,
             version=version,
-            tag=tag,
         ))
 
     return EnsureFileContent(dependencies=dependencies)
@@ -200,7 +219,6 @@ def store_dependencies(
             dependency_project=dep.project,
             dependency_package=dep.package,
             version_constraint=dep.version,
-            tag_constraint=dep.tag,
         )
         db.add(artifact_dep)
         created.append(artifact_dep)
@@ -266,26 +284,21 @@ def get_reverse_dependencies(
         if not artifact:
             continue
 
-        # Find which package this artifact belongs to via tags or versions
-        tag = db.query(Tag).filter(Tag.artifact_id == dep.artifact_id).first()
-        if tag:
-            pkg = db.query(Package).filter(Package.id == tag.package_id).first()
+        # Find which package this artifact belongs to via versions
+        version_record = db.query(PackageVersion).filter(
+            PackageVersion.artifact_id == dep.artifact_id,
+        ).first()
+        if version_record:
+            pkg = db.query(Package).filter(Package.id == version_record.package_id).first()
             if pkg:
                 proj = db.query(Project).filter(Project.id == pkg.project_id).first()
                 if proj:
-                    # Get version if available
-                    version_record = db.query(PackageVersion).filter(
-                        PackageVersion.artifact_id == dep.artifact_id,
-                        PackageVersion.package_id == pkg.id,
-                    ).first()
-
                     dependents.append(DependentInfo(
                         artifact_id=dep.artifact_id,
                         project=proj.name,
                         package=pkg.name,
-                        version=version_record.version if version_record else None,
-                        constraint_type="version" if dep.version_constraint else "tag",
-                        constraint_value=dep.version_constraint or dep.tag_constraint,
+                        version=version_record.version,
+                        constraint_value=dep.version_constraint,
                     ))
 
     total_pages = (total + limit - 1) // limit
@@ -304,25 +317,117 @@ def get_reverse_dependencies(
     )
 
 
+def _is_version_constraint(version_str: str) -> bool:
+    """Check if a version string contains constraint operators."""
+    if not version_str:
+        return False
+    # Check for common constraint operators
+    return any(op in version_str for op in ['>=', '<=', '!=', '~=', '>', '<', '==', '*'])
+
+
+def _resolve_version_constraint(
+    db: Session,
+    package: Package,
+    constraint: str,
+) -> Optional[Tuple[str, str, int]]:
+    """
+    Resolve a version constraint (e.g., '>=1.9') to a specific version.
+
+    Uses PEP 440 version matching to find the best matching version.
+
+    Args:
+        db: Database session
+        package: Package to search versions in
+        constraint: Version constraint string (e.g., '>=1.9', '<2.0,>=1.5')
+
+    Returns:
+        Tuple of (artifact_id, resolved_version, size) or None if not found
+    """
+    if not HAS_PACKAGING:
+        # Fallback: if packaging not available, can't do constraint matching
+        return None
+
+    # Handle wildcard - return latest version
+    if constraint == '*':
+        # Get the latest version by created_at
+        latest = db.query(PackageVersion).filter(
+            PackageVersion.package_id == package.id,
+        ).order_by(PackageVersion.created_at.desc()).first()
+        if latest:
+            artifact = db.query(Artifact).filter(Artifact.id == latest.artifact_id).first()
+            if artifact:
+                return (artifact.id, latest.version, artifact.size)
+        return None
+
+    try:
+        specifier = SpecifierSet(constraint)
+    except InvalidSpecifier:
+        # Invalid constraint (e.g., ">=" without version) - treat as wildcard
+        # This can happen with malformed metadata from PyPI packages
+        latest = db.query(PackageVersion).filter(
+            PackageVersion.package_id == package.id,
+        ).order_by(PackageVersion.created_at.desc()).first()
+        if latest:
+            artifact = db.query(Artifact).filter(Artifact.id == latest.artifact_id).first()
+            if artifact:
+                return (artifact.id, latest.version, artifact.size)
+        return None
+
+    # Get all versions for this package
+    all_versions = db.query(PackageVersion).filter(
+        PackageVersion.package_id == package.id,
+    ).all()
+
+    if not all_versions:
+        return None
+
+    # Find matching versions
+    matching = []
+    for pv in all_versions:
+        try:
+            v = Version(pv.version)
+            if v in specifier:
+                matching.append((pv, v))
+        except InvalidVersion:
+            # Skip invalid versions
+            continue
+
+    if not matching:
+        return None
+
+    # Sort by version (descending) and return the latest matching
+    matching.sort(key=lambda x: x[1], reverse=True)
+    best_match = matching[0][0]
+
+    artifact = db.query(Artifact).filter(Artifact.id == best_match.artifact_id).first()
+    if artifact:
+        return (artifact.id, best_match.version, artifact.size)
+
+    return None
+
+
 def _resolve_dependency_to_artifact(
     db: Session,
     project_name: str,
     package_name: str,
-    version: Optional[str],
-    tag: Optional[str],
+    version: str,
 ) -> Optional[Tuple[str, str, int]]:
     """
     Resolve a dependency constraint to an artifact ID.
 
+    Supports:
+    - Exact version matching (e.g., '1.2.3')
+    - Version constraints (e.g., '>=1.9', '<2.0,>=1.5')
+    - Wildcard ('*' for any version)
+
     Args:
         db: Database session
         project_name: Project name
         package_name: Package name
-        version: Version constraint (exact)
-        tag: Tag constraint
+        version: Version or version constraint
 
     Returns:
-        Tuple of (artifact_id, resolved_version_or_tag, size) or None if not found
+        Tuple of (artifact_id, resolved_version, size) or None if not found
     """
     # Get project and package
     project = db.query(Project).filter(Project.name == project_name).first()
@@ -336,8 +441,13 @@ def _resolve_dependency_to_artifact(
     if not package:
         return None
 
-    if version:
-        # Look up by version
+    # Check if this is a version constraint (>=, <, etc.) or exact version
+    if _is_version_constraint(version):
+        result = _resolve_version_constraint(db, package, version)
+        if result:
+            return result
+    else:
+        # Look up by exact version
         pkg_version = db.query(PackageVersion).filter(
             PackageVersion.package_id == package.id,
             PackageVersion.version == version,
@@ -349,31 +459,6 @@ def _resolve_dependency_to_artifact(
             if artifact:
                 return (artifact.id, version, artifact.size)
 
-        # Also check if there's a tag with this exact name
-        tag_record = db.query(Tag).filter(
-            Tag.package_id == package.id,
-            Tag.name == version,
-        ).first()
-        if tag_record:
-            artifact = db.query(Artifact).filter(
-                Artifact.id == tag_record.artifact_id
-            ).first()
-            if artifact:
-                return (artifact.id, version, artifact.size)
-
-    if tag:
-        # Look up by tag
-        tag_record = db.query(Tag).filter(
-            Tag.package_id == package.id,
-            Tag.name == tag,
-        ).first()
-        if tag_record:
-            artifact = db.query(Artifact).filter(
-                Artifact.id == tag_record.artifact_id
-            ).first()
-            if artifact:
-                return (artifact.id, tag, artifact.size)
-
     return None
 
 
@@ -403,10 +488,16 @@ def _detect_package_cycle(
     Returns:
         Cycle path if detected, None otherwise
     """
-    pkg_key = f"{project_name}/{package_name}"
+    # Normalize names for comparison (handles extras like [test] and separators)
+    pkg_normalized = _normalize_pypi_package_name(package_name)
+    target_pkg_normalized = _normalize_pypi_package_name(target_package)
+
+    # Use normalized key for tracking
+    pkg_key = f"{project_name.lower()}/{pkg_normalized}"
 
     # Check if we've reached the target package (cycle detected)
-    if project_name == target_project and package_name == target_package:
+    # Use normalized comparison to handle extras and naming variations
+    if project_name.lower() == target_project.lower() and pkg_normalized == target_pkg_normalized:
         return path + [pkg_key]
 
     if pkg_key in visiting:
@@ -427,9 +518,9 @@ def _detect_package_cycle(
             Package.name == package_name,
         ).first()
         if package:
-            # Find all artifacts in this package via tags
-            tags = db.query(Tag).filter(Tag.package_id == package.id).all()
-            artifact_ids = {t.artifact_id for t in tags}
+            # Find all artifacts in this package via versions
+            versions = db.query(PackageVersion).filter(PackageVersion.package_id == package.id).all()
+            artifact_ids = {v.artifact_id for v in versions}
 
             # Get dependencies from all artifacts in this package
             for artifact_id in artifact_ids:
@@ -472,8 +563,8 @@ def check_circular_dependencies(
         db: Database session
         artifact_id: The artifact that will have these dependencies
         new_dependencies: Dependencies to be added
-        project_name: Project name (optional, will try to look up from tag if not provided)
-        package_name: Package name (optional, will try to look up from tag if not provided)
+        project_name: Project name (optional, will try to look up from version if not provided)
+        package_name: Package name (optional, will try to look up from version if not provided)
 
     Returns:
         Cycle path if detected, None otherwise
@@ -482,17 +573,19 @@ def check_circular_dependencies(
     if project_name and package_name:
         current_path = f"{project_name}/{package_name}"
     else:
-        # Try to look up from tag
+        # Try to look up from version
         artifact = db.query(Artifact).filter(Artifact.id == artifact_id).first()
         if not artifact:
             return None
 
-        # Find package for this artifact
-        tag = db.query(Tag).filter(Tag.artifact_id == artifact_id).first()
-        if not tag:
+        # Find package for this artifact via version
+        version_record = db.query(PackageVersion).filter(
+            PackageVersion.artifact_id == artifact_id
+        ).first()
+        if not version_record:
             return None
 
-        package = db.query(Package).filter(Package.id == tag.package_id).first()
+        package = db.query(Package).filter(Package.id == version_record.package_id).first()
         if not package:
             return None
 
@@ -508,12 +601,15 @@ def check_circular_dependencies(
     else:
         return None
 
+    # Normalize the initial path for consistency with _detect_package_cycle
+    normalized_path = f"{target_project.lower()}/{_normalize_pypi_package_name(target_package)}"
+
     # For each new dependency, check if it would create a cycle back to our package
     for dep in new_dependencies:
         # Check if this dependency (transitively) depends on us at the package level
         visiting: Set[str] = set()
         visited: Set[str] = set()
-        path: List[str] = [current_path]
+        path: List[str] = [normalized_path]
 
         # Check from the dependency's package
         cycle = _detect_package_cycle(
@@ -546,7 +642,7 @@ def resolve_dependencies(
         db: Database session
         project_name: Project name
         package_name: Package name
-        ref: Tag or version reference
+        ref: Version reference (or artifact:hash)
         base_url: Base URL for download URLs
 
     Returns:
@@ -569,22 +665,35 @@ def resolve_dependencies(
     if not package:
         raise DependencyNotFoundError(project_name, package_name, ref)
 
-    # Try to find artifact by tag or version
+    # Handle artifact: prefix for direct artifact ID references
+    if ref.startswith("artifact:"):
+        artifact_id = ref[9:]
+        artifact = db.query(Artifact).filter(Artifact.id == artifact_id).first()
+        if not artifact:
+            raise DependencyNotFoundError(project_name, package_name, ref)
+        root_artifact_id = artifact.id
+        root_version = artifact_id[:12]  # Use short hash as version display
+        root_size = artifact.size
+    else:
+        # Try to find artifact by version
         resolved = _resolve_dependency_to_artifact(
-        db, project_name, package_name, ref, ref
+            db, project_name, package_name, ref
         )
         if not resolved:
             raise DependencyNotFoundError(project_name, package_name, ref)
-
         root_artifact_id, root_version, root_size = resolved
 
     # Track resolved artifacts and their versions
     resolved_artifacts: Dict[str, ResolvedArtifact] = {}
+    # Track missing dependencies (not cached on server)
+    missing_dependencies: List[MissingDependency] = []
     # Track version requirements for conflict detection
     version_requirements: Dict[str, List[Dict[str, Any]]] = {}  # pkg_key -> [(version, required_by)]
     # Track visiting/visited for cycle detection
     visiting: Set[str] = set()
     visited: Set[str] = set()
+    # Track the current path for cycle reporting (artifact_id -> pkg_key)
+    current_path: Dict[str, str] = {}
     # Resolution order (topological)
     resolution_order: List[str] = []
 
@@ -606,8 +715,10 @@ def resolve_dependencies(
 
         # Cycle detection (at artifact level)
         if artifact_id in visiting:
-            # Build cycle path
-            raise CircularDependencyError([pkg_key, pkg_key])
+            # Build cycle path from current_path
+            cycle_start = current_path.get(artifact_id, pkg_key)
+            cycle = [cycle_start, pkg_key]
+            raise CircularDependencyError(cycle)
 
         # Conflict detection - check if we've seen this package before with a different version
         if pkg_key in version_requirements:
@@ -638,6 +749,7 @@ def resolve_dependencies(
             return
 
         visiting.add(artifact_id)
+        current_path[artifact_id] = pkg_key
 
         # Track version requirement
         if pkg_key not in version_requirements:
@@ -654,23 +766,39 @@ def resolve_dependencies(
 
         # Resolve each dependency first (depth-first)
         for dep in deps:
+            # Skip self-dependencies (can happen with PyPI extras like pytest[testing])
+            # Use normalized comparison for PyPI naming conventions (handles extras, separators)
+            dep_proj_normalized = dep.dependency_project.lower()
+            dep_pkg_normalized = _normalize_pypi_package_name(dep.dependency_package)
+            curr_proj_normalized = proj_name.lower()
+            curr_pkg_normalized = _normalize_pypi_package_name(pkg_name)
+            if dep_proj_normalized == curr_proj_normalized and dep_pkg_normalized == curr_pkg_normalized:
+                continue
+
             resolved_dep = _resolve_dependency_to_artifact(
                 db,
                 dep.dependency_project,
                 dep.dependency_package,
                 dep.version_constraint,
-                dep.tag_constraint,
             )
 
             if not resolved_dep:
-                constraint = dep.version_constraint or dep.tag_constraint
-                raise DependencyNotFoundError(
-                    dep.dependency_project,
-                    dep.dependency_package,
-                    constraint,
-                )
+                # Dependency not cached on server - track as missing but continue
+                constraint = dep.version_constraint
+                missing_dependencies.append(MissingDependency(
+                    project=dep.dependency_project,
+                    package=dep.dependency_package,
+                    constraint=constraint,
+                    required_by=pkg_key,
+                ))
+                continue
 
             dep_artifact_id, dep_version, dep_size = resolved_dep
+
+            # Skip if resolved to same artifact (self-dependency at artifact level)
+            if dep_artifact_id == artifact_id:
+                continue
+
             _resolve_recursive(
                 dep_artifact_id,
                 dep.dependency_project,
@@ -682,6 +810,7 @@ def resolve_dependencies(
             )
 
         visiting.remove(artifact_id)
+        del current_path[artifact_id]
         visited.add(artifact_id)
 
         # Add to resolution order (dependencies before dependents)
@@ -718,6 +847,7 @@ def resolve_dependencies(
             "ref": ref,
         },
         resolved=resolved_list,
+        missing=missing_dependencies,
         total_size=total_size,
         artifact_count=len(resolved_list),
     )

backend/app/encryption.py

@@ -0,0 +1,160 @@
+"""
+Encryption utilities for sensitive data storage.
+
+Uses Fernet symmetric encryption for credentials like upstream passwords.
+The encryption key is sourced from ORCHARD_CACHE_ENCRYPTION_KEY environment variable.
+If not set, a random key is generated on startup (with a warning).
+"""
+
+import base64
+import logging
+import os
+import secrets
+from functools import lru_cache
+from typing import Optional
+
+from cryptography.fernet import Fernet, InvalidToken
+
+logger = logging.getLogger(__name__)
+
+# Module-level storage for auto-generated key (only used if env var not set)
+_generated_key: Optional[bytes] = None
+
+
+def _get_key_from_env() -> Optional[bytes]:
+    """Get encryption key from environment variable."""
+    key_str = os.environ.get("ORCHARD_CACHE_ENCRYPTION_KEY", "")
+    if not key_str:
+        return None
+
+    # Support both raw base64 and url-safe base64 formats
+    try:
+        # Try to decode as-is (Fernet keys are url-safe base64)
+        key_bytes = key_str.encode("utf-8")
+        # Validate it's a valid Fernet key by trying to create a Fernet instance
+        Fernet(key_bytes)
+        return key_bytes
+    except Exception:
+        pass
+
+    # Try base64 decoding if it's a raw 32-byte key encoded as base64
+    try:
+        decoded = base64.urlsafe_b64decode(key_str)
+        if len(decoded) == 32:
+            # Re-encode as url-safe base64 for Fernet
+            key_bytes = base64.urlsafe_b64encode(decoded)
+            Fernet(key_bytes)
+            return key_bytes
+    except Exception:
+        pass
+
+    logger.error(
+        "ORCHARD_CACHE_ENCRYPTION_KEY is set but invalid. "
+        "Must be a valid Fernet key (32 bytes, url-safe base64 encoded). "
+        "Generate one with: python -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\""
+    )
+    return None
+
+
+def get_encryption_key() -> bytes:
+    """
+    Get the Fernet encryption key.
+
+    Returns the key from ORCHARD_CACHE_ENCRYPTION_KEY if set and valid,
+    otherwise generates a random key (with a warning logged).
+
+    The generated key is cached for the lifetime of the process.
+    """
+    global _generated_key
+
+    # Try to get from environment
+    env_key = _get_key_from_env()
+    if env_key:
+        return env_key
+
+    # Generate a new key if needed
+    if _generated_key is None:
+        _generated_key = Fernet.generate_key()
+        logger.warning(
+            "ORCHARD_CACHE_ENCRYPTION_KEY not set - using auto-generated key. "
+            "Encrypted credentials will be lost on restart! "
+            "Set ORCHARD_CACHE_ENCRYPTION_KEY for persistent encryption. "
+            "Generate a key with: python -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\""
+        )
+
+    return _generated_key
+
+
+@lru_cache(maxsize=1)
+def _get_fernet() -> Fernet:
+    """Get a cached Fernet instance."""
+    return Fernet(get_encryption_key())
+
+
+def encrypt_value(plaintext: str) -> bytes:
+    """
+    Encrypt a string value using Fernet.
+
+    Args:
+        plaintext: The string to encrypt
+
+    Returns:
+        Encrypted bytes (includes Fernet token with timestamp)
+    """
+    if not plaintext:
+        raise ValueError("Cannot encrypt empty value")
+
+    fernet = _get_fernet()
+    return fernet.encrypt(plaintext.encode("utf-8"))
+
+
+def decrypt_value(ciphertext: bytes) -> str:
+    """
+    Decrypt a Fernet-encrypted value.
+
+    Args:
+        ciphertext: The encrypted bytes
+
+    Returns:
+        Decrypted string
+
+    Raises:
+        InvalidToken: If decryption fails (wrong key or corrupted data)
+    """
+    if not ciphertext:
+        raise ValueError("Cannot decrypt empty value")
+
+    fernet = _get_fernet()
+    return fernet.decrypt(ciphertext).decode("utf-8")
+
+
+def can_decrypt(ciphertext: bytes) -> bool:
+    """
+    Check if a value can be decrypted with the current key.
+
+    Useful for checking if credentials are still valid after key rotation.
+
+    Args:
+        ciphertext: The encrypted bytes
+
+    Returns:
+        True if decryption succeeds, False otherwise
+    """
+    if not ciphertext:
+        return False
+
+    try:
+        decrypt_value(ciphertext)
+        return True
+    except (InvalidToken, ValueError):
+        return False
+
+
+def generate_key() -> str:
+    """
+    Generate a new Fernet encryption key.
+
+    Returns:
+        A valid Fernet key as a string (url-safe base64 encoded)
+    """
+    return Fernet.generate_key().decode("utf-8")

backend/app/main.py

@@ -11,6 +11,7 @@ from slowapi.errors import RateLimitExceeded
 from .config import get_settings
 from .database import init_db, SessionLocal
 from .routes import router
+from .pypi_proxy import router as pypi_router
 from .seed import seed_database
 from .auth import create_default_admin
 from .rate_limit import limiter
@@ -49,7 +50,6 @@ async def lifespan(app: FastAPI):
         logger.info(f"Running in {settings.env} mode - skipping seed data")
 
     yield
-    # Shutdown: cleanup if needed
 
 
 app = FastAPI(
@@ -65,6 +65,7 @@ app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
 
 # Include API routes
 app.include_router(router)
+app.include_router(pypi_router)
 
 # Serve static files (React build) if the directory exists
 static_dir = os.path.join(os.path.dirname(__file__), "..", "..", "frontend", "dist")

backend/app/models.py

@@ -12,6 +12,7 @@ from sqlalchemy import (
     Index,
     JSON,
     ARRAY,
+    LargeBinary,
 )
 from sqlalchemy.dialects.postgresql import UUID
 from sqlalchemy.orm import relationship, declarative_base
@@ -27,6 +28,7 @@ class Project(Base):
     name = Column(String(255), unique=True, nullable=False)
     description = Column(Text)
     is_public = Column(Boolean, default=True)
+    is_system = Column(Boolean, default=False, nullable=False)
     created_at = Column(DateTime(timezone=True), default=datetime.utcnow)
     updated_at = Column(
         DateTime(timezone=True), default=datetime.utcnow, onupdate=datetime.utcnow
@@ -46,6 +48,7 @@ class Project(Base):
         Index("idx_projects_name", "name"),
         Index("idx_projects_created_by", "created_by"),
         Index("idx_projects_team_id", "team_id"),
+        Index("idx_projects_is_system", "is_system"),
     )
 
 
@@ -68,7 +71,6 @@ class Package(Base):
     )
 
     project = relationship("Project", back_populates="packages")
-    tags = relationship("Tag", back_populates="package", cascade="all, delete-orphan")
     uploads = relationship(
         "Upload", back_populates="package", cascade="all, delete-orphan"
     )
@@ -117,7 +119,6 @@ class Artifact(Base):
     ref_count = Column(Integer, default=1)
     s3_key = Column(String(1024), nullable=False)
 
-    tags = relationship("Tag", back_populates="artifact")
     uploads = relationship("Upload", back_populates="artifact")
     versions = relationship("PackageVersion", back_populates="artifact")
     dependencies = relationship(
@@ -148,65 +149,6 @@ class Artifact(Base):
     )
 
 
-class Tag(Base):
-    __tablename__ = "tags"
-
-    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
-    package_id = Column(
-        UUID(as_uuid=True),
-        ForeignKey("packages.id", ondelete="CASCADE"),
-        nullable=False,
-    )
-    name = Column(String(255), nullable=False)
-    artifact_id = Column(String(64), ForeignKey("artifacts.id"), nullable=False)
-    created_at = Column(DateTime(timezone=True), default=datetime.utcnow)
-    updated_at = Column(
-        DateTime(timezone=True), default=datetime.utcnow, onupdate=datetime.utcnow
-    )
-    created_by = Column(String(255), nullable=False)
-
-    package = relationship("Package", back_populates="tags")
-    artifact = relationship("Artifact", back_populates="tags")
-    history = relationship(
-        "TagHistory", back_populates="tag", cascade="all, delete-orphan"
-    )
-
-    __table_args__ = (
-        Index("idx_tags_package_id", "package_id"),
-        Index("idx_tags_artifact_id", "artifact_id"),
-        Index(
-            "idx_tags_package_name", "package_id", "name", unique=True
-        ),  # Composite unique index
-        Index(
-            "idx_tags_package_created_at", "package_id", "created_at"
-        ),  # For recent tags queries
-    )
-
-
-class TagHistory(Base):
-    __tablename__ = "tag_history"
-
-    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
-    tag_id = Column(
-        UUID(as_uuid=True), ForeignKey("tags.id", ondelete="CASCADE"), nullable=False
-    )
-    old_artifact_id = Column(String(64), ForeignKey("artifacts.id"))
-    new_artifact_id = Column(String(64), ForeignKey("artifacts.id"), nullable=False)
-    change_type = Column(String(20), nullable=False, default="update")
-    changed_at = Column(DateTime(timezone=True), default=datetime.utcnow)
-    changed_by = Column(String(255), nullable=False)
-
-    tag = relationship("Tag", back_populates="history")
-
-    __table_args__ = (
-        Index("idx_tag_history_tag_id", "tag_id"),
-        Index("idx_tag_history_changed_at", "changed_at"),
-        CheckConstraint(
-            "change_type IN ('create', 'update', 'delete')", name="check_change_type"
-        ),
-    )
-
-
 class PackageVersion(Base):
     """Immutable version record for a package-artifact relationship.
 
@@ -246,7 +188,7 @@ class Upload(Base):
     artifact_id = Column(String(64), ForeignKey("artifacts.id"), nullable=False)
     package_id = Column(UUID(as_uuid=True), ForeignKey("packages.id"), nullable=False)
     original_name = Column(String(1024))
-    tag_name = Column(String(255))  # Tag assigned during upload
+    version = Column(String(255))  # Version assigned during upload
     user_agent = Column(String(512))  # Client identification
     duration_ms = Column(Integer)  # Upload timing in milliseconds
     deduplicated = Column(Boolean, default=False)  # Whether artifact was deduplicated
@@ -521,8 +463,8 @@ class PackageHistory(Base):
 class ArtifactDependency(Base):
     """Dependency declared by an artifact on another package.
 
-    Each artifact can declare dependencies on other packages, specifying either
-    an exact version or a tag. This enables recursive dependency resolution.
+    Each artifact can declare dependencies on other packages, specifying a version.
+    This enables recursive dependency resolution.
     """
 
     __tablename__ = "artifact_dependencies"
@@ -535,20 +477,13 @@ class ArtifactDependency(Base):
     )
     dependency_project = Column(String(255), nullable=False)
     dependency_package = Column(String(255), nullable=False)
-    version_constraint = Column(String(255), nullable=True)
-    tag_constraint = Column(String(255), nullable=True)
+    version_constraint = Column(String(255), nullable=False)
     created_at = Column(DateTime(timezone=True), default=datetime.utcnow)
 
     # Relationship to the artifact that declares this dependency
     artifact = relationship("Artifact", back_populates="dependencies")
 
     __table_args__ = (
-        # Exactly one of version_constraint or tag_constraint must be set
-        CheckConstraint(
-            "(version_constraint IS NOT NULL AND tag_constraint IS NULL) OR "
-            "(version_constraint IS NULL AND tag_constraint IS NOT NULL)",
-            name="check_constraint_type",
-        ),
         # Each artifact can only depend on a specific project/package once
         Index(
             "idx_artifact_dependencies_artifact_id",
@@ -637,3 +572,166 @@ class TeamMembership(Base):
             name="check_team_role",
         ),
     )
+
+
+# =============================================================================
+# Upstream Caching Models
+# =============================================================================
+
+# Valid source types for upstream registries
+SOURCE_TYPES = ["npm", "pypi", "maven", "docker", "helm", "nuget", "deb", "rpm", "generic"]
+
+# Valid authentication types
+AUTH_TYPES = ["none", "basic", "bearer", "api_key"]
+
+
+class UpstreamSource(Base):
+    """Configuration for an upstream artifact registry.
+
+    Stores connection details and authentication for upstream registries
+    like npm, PyPI, Maven Central, or private Artifactory instances.
+    """
+
+    __tablename__ = "upstream_sources"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    name = Column(String(255), unique=True, nullable=False)
+    source_type = Column(String(50), default="generic", nullable=False)
+    url = Column(String(2048), nullable=False)
+    enabled = Column(Boolean, default=False, nullable=False)
+    auth_type = Column(String(20), default="none", nullable=False)
+    username = Column(String(255))
+    password_encrypted = Column(LargeBinary)
+    headers_encrypted = Column(LargeBinary)
+    priority = Column(Integer, default=100, nullable=False)
+    created_at = Column(DateTime(timezone=True), default=datetime.utcnow)
+    updated_at = Column(
+        DateTime(timezone=True), default=datetime.utcnow, onupdate=datetime.utcnow
+    )
+
+    # Relationships
+    cached_urls = relationship("CachedUrl", back_populates="source")
+
+    __table_args__ = (
+        Index("idx_upstream_sources_enabled", "enabled"),
+        Index("idx_upstream_sources_source_type", "source_type"),
+        Index("idx_upstream_sources_priority", "priority"),
+        CheckConstraint(
+            "source_type IN ('npm', 'pypi', 'maven', 'docker', 'helm', 'nuget', 'deb', 'rpm', 'generic')",
+            name="check_source_type",
+        ),
+        CheckConstraint(
+            "auth_type IN ('none', 'basic', 'bearer', 'api_key')",
+            name="check_auth_type",
+        ),
+        CheckConstraint("priority > 0", name="check_priority_positive"),
+    )
+
+    def set_password(self, password: str) -> None:
+        """Encrypt and store a password/token."""
+        from .encryption import encrypt_value
+
+        if password:
+            self.password_encrypted = encrypt_value(password)
+        else:
+            self.password_encrypted = None
+
+    def get_password(self) -> str | None:
+        """Decrypt and return the stored password/token."""
+        from .encryption import decrypt_value
+
+        if self.password_encrypted:
+            try:
+                return decrypt_value(self.password_encrypted)
+            except Exception:
+                return None
+        return None
+
+    def has_password(self) -> bool:
+        """Check if a password/token is stored."""
+        return self.password_encrypted is not None
+
+    def set_headers(self, headers: dict) -> None:
+        """Encrypt and store custom headers as JSON."""
+        from .encryption import encrypt_value
+        import json
+
+        if headers:
+            self.headers_encrypted = encrypt_value(json.dumps(headers))
+        else:
+            self.headers_encrypted = None
+
+    def get_headers(self) -> dict | None:
+        """Decrypt and return custom headers."""
+        from .encryption import decrypt_value
+        import json
+
+        if self.headers_encrypted:
+            try:
+                return json.loads(decrypt_value(self.headers_encrypted))
+            except Exception:
+                return None
+        return None
+
+
+class CacheSettings(Base):
+    """Global cache settings (singleton table).
+
+    Controls behavior of the upstream caching system.
+    """
+
+    __tablename__ = "cache_settings"
+
+    id = Column(Integer, primary_key=True, default=1)
+    auto_create_system_projects = Column(Boolean, default=True, nullable=False)
+    created_at = Column(DateTime(timezone=True), default=datetime.utcnow)
+    updated_at = Column(
+        DateTime(timezone=True), default=datetime.utcnow, onupdate=datetime.utcnow
+    )
+
+    __table_args__ = (
+        CheckConstraint("id = 1", name="check_cache_settings_singleton"),
+    )
+
+
+class CachedUrl(Base):
+    """Tracks URL to artifact mappings for provenance.
+
+    Records which URLs have been cached and maps them to their stored artifacts.
+    Enables "is this URL already cached?" lookups and audit trails.
+    """
+
+    __tablename__ = "cached_urls"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    url = Column(String(4096), nullable=False)
+    url_hash = Column(String(64), unique=True, nullable=False)
+    artifact_id = Column(
+        String(64), ForeignKey("artifacts.id"), nullable=False
+    )
+    source_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("upstream_sources.id", ondelete="SET NULL"),
+    )
+    fetched_at = Column(DateTime(timezone=True), default=datetime.utcnow, nullable=False)
+    response_headers = Column(JSON, default=dict)
+    created_at = Column(DateTime(timezone=True), default=datetime.utcnow)
+
+    # Relationships
+    artifact = relationship("Artifact")
+    source = relationship("UpstreamSource", back_populates="cached_urls")
+
+    __table_args__ = (
+        Index("idx_cached_urls_url_hash", "url_hash"),
+        Index("idx_cached_urls_artifact_id", "artifact_id"),
+        Index("idx_cached_urls_source_id", "source_id"),
+        Index("idx_cached_urls_fetched_at", "fetched_at"),
+    )
+
+    @staticmethod
+    def compute_url_hash(url: str) -> str:
+        """Compute SHA256 hash of a URL for fast lookups."""
+        import hashlib
+        return hashlib.sha256(url.encode("utf-8")).hexdigest()
+
+

backend/app/purge_seed_data.py

@@ -0,0 +1,202 @@
+"""
+Purge seed/demo data from the database.
+
+This is used when transitioning an environment from dev/test to production-like.
+Triggered by setting ORCHARD_PURGE_SEED_DATA=true environment variable.
+"""
+import logging
+import os
+from sqlalchemy.orm import Session
+
+from .models import (
+    Project,
+    Package,
+    Artifact,
+    Upload,
+    PackageVersion,
+    ArtifactDependency,
+    Team,
+    TeamMembership,
+    User,
+    AccessPermission,
+)
+from .storage import get_storage
+
+logger = logging.getLogger(__name__)
+
+# Seed data identifiers (from seed.py)
+SEED_PROJECT_NAMES = [
+    "frontend-libs",
+    "backend-services",
+    "mobile-apps",
+    "internal-tools",
+]
+
+SEED_TEAM_SLUG = "demo-team"
+
+SEED_USERNAMES = [
+    "alice",
+    "bob",
+    "charlie",
+    "diana",
+    "eve",
+    "frank",
+]
+
+
+def should_purge_seed_data() -> bool:
+    """Check if seed data should be purged based on environment variable."""
+    return os.environ.get("ORCHARD_PURGE_SEED_DATA", "").lower() == "true"
+
+
+def purge_seed_data(db: Session) -> dict:
+    """
+    Purge all seed/demo data from the database.
+
+    Returns a dict with counts of deleted items.
+    """
+    logger.warning("PURGING SEED DATA - This will delete demo projects, users, and teams")
+
+    results = {
+        "dependencies_deleted": 0,
+        "versions_deleted": 0,
+        "uploads_deleted": 0,
+        "artifacts_deleted": 0,
+        "packages_deleted": 0,
+        "projects_deleted": 0,
+        "permissions_deleted": 0,
+        "team_memberships_deleted": 0,
+        "users_deleted": 0,
+        "teams_deleted": 0,
+        "s3_objects_deleted": 0,
+    }
+
+    storage = get_storage()
+
+    # Find seed projects
+    seed_projects = db.query(Project).filter(Project.name.in_(SEED_PROJECT_NAMES)).all()
+    seed_project_ids = [p.id for p in seed_projects]
+
+    if not seed_projects:
+        logger.info("No seed projects found, nothing to purge")
+        return results
+
+    logger.info(f"Found {len(seed_projects)} seed projects to purge")
+
+    # Find packages in seed projects
+    seed_packages = db.query(Package).filter(Package.project_id.in_(seed_project_ids)).all()
+    seed_package_ids = [p.id for p in seed_packages]
+
+    # Find artifacts in seed packages (via uploads)
+    seed_uploads = db.query(Upload).filter(Upload.package_id.in_(seed_package_ids)).all()
+    seed_artifact_ids = list(set(u.artifact_id for u in seed_uploads))
+
+    # Delete in order (respecting foreign keys)
+
+    # 1. Delete artifact dependencies
+    if seed_artifact_ids:
+        count = db.query(ArtifactDependency).filter(
+            ArtifactDependency.artifact_id.in_(seed_artifact_ids)
+        ).delete(synchronize_session=False)
+        results["dependencies_deleted"] = count
+        logger.info(f"Deleted {count} artifact dependencies")
+
+    # 2. Delete package versions
+    if seed_package_ids:
+        count = db.query(PackageVersion).filter(
+            PackageVersion.package_id.in_(seed_package_ids)
+        ).delete(synchronize_session=False)
+        results["versions_deleted"] = count
+        logger.info(f"Deleted {count} package versions")
+
+    # 3. Delete uploads
+    if seed_package_ids:
+        count = db.query(Upload).filter(Upload.package_id.in_(seed_package_ids)).delete(
+            synchronize_session=False
+        )
+        results["uploads_deleted"] = count
+        logger.info(f"Deleted {count} uploads")
+
+    # 4. Delete S3 objects for seed artifacts
+    if seed_artifact_ids:
+        seed_artifacts = db.query(Artifact).filter(Artifact.id.in_(seed_artifact_ids)).all()
+        for artifact in seed_artifacts:
+            if artifact.s3_key:
+                try:
+                    storage.client.delete_object(Bucket=storage.bucket, Key=artifact.s3_key)
+                    results["s3_objects_deleted"] += 1
+                except Exception as e:
+                    logger.warning(f"Failed to delete S3 object {artifact.s3_key}: {e}")
+        logger.info(f"Deleted {results['s3_objects_deleted']} S3 objects")
+
+    # 5. Delete artifacts (only those with ref_count that would be 0 after our deletions)
+    # Since we deleted all versions pointing to these artifacts, we can delete them
+    if seed_artifact_ids:
+        count = db.query(Artifact).filter(Artifact.id.in_(seed_artifact_ids)).delete(
+            synchronize_session=False
+        )
+        results["artifacts_deleted"] = count
+        logger.info(f"Deleted {count} artifacts")
+
+    # 6. Delete packages
+    if seed_package_ids:
+        count = db.query(Package).filter(Package.id.in_(seed_package_ids)).delete(
+            synchronize_session=False
+        )
+        results["packages_deleted"] = count
+        logger.info(f"Deleted {count} packages")
+
+    # 7. Delete access permissions for seed projects
+    if seed_project_ids:
+        count = db.query(AccessPermission).filter(
+            AccessPermission.project_id.in_(seed_project_ids)
+        ).delete(synchronize_session=False)
+        results["permissions_deleted"] = count
+        logger.info(f"Deleted {count} access permissions")
+
+    # 8. Delete seed projects
+    count = db.query(Project).filter(Project.name.in_(SEED_PROJECT_NAMES)).delete(
+        synchronize_session=False
+    )
+    results["projects_deleted"] = count
+    logger.info(f"Deleted {count} projects")
+
+    # 9. Find and delete seed team
+    seed_team = db.query(Team).filter(Team.slug == SEED_TEAM_SLUG).first()
+    if seed_team:
+        # Delete team memberships first
+        count = db.query(TeamMembership).filter(
+            TeamMembership.team_id == seed_team.id
+        ).delete(synchronize_session=False)
+        results["team_memberships_deleted"] = count
+        logger.info(f"Deleted {count} team memberships")
+
+        # Delete the team
+        db.delete(seed_team)
+        results["teams_deleted"] = 1
+        logger.info(f"Deleted team: {SEED_TEAM_SLUG}")
+
+    # 10. Delete seed users (but NOT admin)
+    seed_users = db.query(User).filter(User.username.in_(SEED_USERNAMES)).all()
+    for user in seed_users:
+        # Delete any remaining team memberships for this user
+        db.query(TeamMembership).filter(TeamMembership.user_id == user.id).delete(
+            synchronize_session=False
+        )
+        # Delete any access permissions for this user
+        # Note: AccessPermission.user_id is VARCHAR (username), not UUID
+        db.query(AccessPermission).filter(AccessPermission.user_id == user.username).delete(
+            synchronize_session=False
+        )
+        db.delete(user)
+        results["users_deleted"] += 1
+
+    if results["users_deleted"] > 0:
+        logger.info(f"Deleted {results['users_deleted']} seed users")
+
+    db.commit()
+
+    logger.warning("SEED DATA PURGE COMPLETE")
+    logger.info(f"Purge results: {results}")
+
+    return results

backend/app/pypi_proxy.py

@@ -0,0 +1,899 @@
+"""
+Transparent PyPI proxy implementing PEP 503 (Simple API).
+
+Provides endpoints that allow pip to use Orchard as a PyPI index URL.
+Artifacts are cached on first access through configured upstream sources.
+"""
+
+import hashlib
+import json
+import logging
+import os
+import re
+import tarfile
+import tempfile
+import zipfile
+from io import BytesIO
+from typing import Optional, List, Tuple
+from urllib.parse import urljoin, urlparse, quote, unquote
+
+import httpx
+from fastapi import APIRouter, Depends, HTTPException, Request, Response
+from fastapi.responses import StreamingResponse, HTMLResponse, RedirectResponse
+from sqlalchemy.orm import Session
+
+from .database import get_db
+from .models import UpstreamSource, CachedUrl, Artifact, Project, Package, PackageVersion, ArtifactDependency
+from .storage import S3Storage, get_storage
+from .config import get_env_upstream_sources, get_settings
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/pypi", tags=["pypi-proxy"])
+
+
+# Timeout configuration for proxy requests
+PROXY_CONNECT_TIMEOUT = 30.0
+PROXY_READ_TIMEOUT = 60.0
+
+
+def _parse_requires_dist(requires_dist: str) -> Tuple[str, Optional[str]]:
+    """Parse a Requires-Dist line into (package_name, version_constraint).
+
+    Examples:
+        "requests (>=2.25.0)" -> ("requests", ">=2.25.0")
+        "typing-extensions; python_version < '3.8'" -> ("typing-extensions", None)
+        "numpy>=1.21.0" -> ("numpy", ">=1.21.0")
+        "certifi" -> ("certifi", None)
+
+    Returns:
+        Tuple of (normalized_package_name, version_constraint or None)
+    """
+    # Remove any environment markers (after semicolon)
+    if ';' in requires_dist:
+        requires_dist = requires_dist.split(';')[0].strip()
+
+    # Match patterns like "package (>=1.0)" or "package>=1.0" or "package"
+    match = re.match(
+        r'^([a-zA-Z0-9][-a-zA-Z0-9._]*)\s*(?:\(([^)]+)\)|([<>=!~][^\s;]+))?',
+        requires_dist.strip()
+    )
+
+    if not match:
+        return None, None
+
+    package_name = match.group(1)
+    # Version can be in parentheses (group 2) or directly after name (group 3)
+    version_constraint = match.group(2) or match.group(3)
+
+    # Normalize package name (PEP 503)
+    normalized_name = re.sub(r'[-_.]+', '-', package_name).lower()
+
+    # Clean up version constraint
+    if version_constraint:
+        version_constraint = version_constraint.strip()
+
+    return normalized_name, version_constraint
+
+
+def _extract_requires_from_metadata(metadata_content: str) -> List[Tuple[str, Optional[str]]]:
+    """Extract all Requires-Dist entries from METADATA/PKG-INFO content.
+
+    Args:
+        metadata_content: The content of a METADATA or PKG-INFO file
+
+    Returns:
+        List of (package_name, version_constraint) tuples
+    """
+    dependencies = []
+
+    for line in metadata_content.split('\n'):
+        if line.startswith('Requires-Dist:'):
+            value = line[len('Requires-Dist:'):].strip()
+            pkg_name, version = _parse_requires_dist(value)
+            if pkg_name:
+                dependencies.append((pkg_name, version))
+
+    return dependencies
+
+
+def _extract_metadata_from_wheel(file_path: str) -> Optional[str]:
+    """Extract METADATA file content from a wheel (zip) file.
+
+    Args:
+        file_path: Path to the wheel file
+
+    Returns:
+        METADATA file content as string, or None if not found
+    """
+    try:
+        with zipfile.ZipFile(file_path) as zf:
+            for name in zf.namelist():
+                if name.endswith('.dist-info/METADATA'):
+                    return zf.read(name).decode('utf-8', errors='replace')
+    except Exception as e:
+        logger.warning(f"Failed to extract metadata from wheel: {e}")
+    return None
+
+
+def _extract_metadata_from_sdist(file_path: str) -> Optional[str]:
+    """Extract PKG-INFO file content from a source distribution (.tar.gz).
+
+    Args:
+        file_path: Path to the tarball file
+
+    Returns:
+        PKG-INFO file content as string, or None if not found
+    """
+    try:
+        with tarfile.open(file_path, mode='r:gz') as tf:
+            for member in tf.getmembers():
+                if member.name.endswith('/PKG-INFO') and member.name.count('/') == 1:
+                    f = tf.extractfile(member)
+                    if f:
+                        return f.read().decode('utf-8', errors='replace')
+    except Exception as e:
+        logger.warning(f"Failed to extract metadata from sdist: {e}")
+    return None
+
+
+def _extract_dependencies_from_file(file_path: str, filename: str) -> List[Tuple[str, Optional[str]]]:
+    """Extract dependencies from a PyPI package file.
+
+    Supports wheel (.whl) and source distribution (.tar.gz) formats.
+
+    Args:
+        file_path: Path to the package file
+        filename: The original filename
+
+    Returns:
+        List of (package_name, version_constraint) tuples
+    """
+    metadata = None
+
+    if filename.endswith('.whl'):
+        metadata = _extract_metadata_from_wheel(file_path)
+    elif filename.endswith('.tar.gz'):
+        metadata = _extract_metadata_from_sdist(file_path)
+
+    if metadata:
+        return _extract_requires_from_metadata(metadata)
+
+    return []
+
+
+def _parse_upstream_error(response: httpx.Response) -> str:
+    """Parse upstream error response to extract useful error details.
+
+    Handles JFrog/Artifactory policy errors and other common formats.
+    Returns a user-friendly error message.
+    """
+    status = response.status_code
+
+    try:
+        body = response.text
+    except Exception:
+        return f"HTTP {status}"
+
+    # Try to parse as JSON (JFrog/Artifactory format)
+    try:
+        data = json.loads(body)
+
+        # JFrog Artifactory format: {"errors": [{"status": 403, "message": "..."}]}
+        if "errors" in data and isinstance(data["errors"], list):
+            messages = []
+            for err in data["errors"]:
+                if isinstance(err, dict) and "message" in err:
+                    messages.append(err["message"])
+            if messages:
+                return "; ".join(messages)
+
+        # Alternative format: {"message": "..."}
+        if "message" in data:
+            return data["message"]
+
+        # Alternative format: {"error": "..."}
+        if "error" in data:
+            return data["error"]
+
+    except (json.JSONDecodeError, ValueError):
+        pass
+
+    # Check for policy-related keywords in plain text response
+    policy_keywords = ["policy", "blocked", "forbidden", "curation", "security"]
+    if any(kw in body.lower() for kw in policy_keywords):
+        # Truncate long responses but preserve the message
+        if len(body) > 500:
+            return body[:500] + "..."
+        return body
+
+    # Default: just return status code
+    return f"HTTP {status}"
+
+
+def _extract_pypi_version(filename: str) -> Optional[str]:
+    """Extract version from PyPI filename.
+
+    Handles formats like:
+    - cowsay-6.1-py3-none-any.whl
+    - cowsay-1.0.tar.gz
+    - some_package-1.2.3.post1-cp39-cp39-linux_x86_64.whl
+    """
+    # Remove extension
+    if filename.endswith('.whl'):
+        # Wheel: name-version-pytag-abitag-platform.whl
+        parts = filename[:-4].split('-')
+        if len(parts) >= 2:
+            return parts[1]
+    elif filename.endswith('.tar.gz'):
+        # Source: name-version.tar.gz
+        base = filename[:-7]
+        # Find the last hyphen that precedes a version-like string
+        match = re.match(r'^(.+)-(\d+.*)$', base)
+        if match:
+            return match.group(2)
+    elif filename.endswith('.zip'):
+        # Egg/zip: name-version.zip
+        base = filename[:-4]
+        match = re.match(r'^(.+)-(\d+.*)$', base)
+        if match:
+            return match.group(2)
+    return None
+
+
+def _get_pypi_upstream_sources(db: Session) -> list[UpstreamSource]:
+    """Get all enabled upstream sources configured for PyPI."""
+    # Get database sources
+    db_sources = (
+        db.query(UpstreamSource)
+        .filter(
+            UpstreamSource.source_type == "pypi",
+            UpstreamSource.enabled == True,
+        )
+        .order_by(UpstreamSource.priority)
+        .all()
+    )
+
+    # Get env sources
+    env_sources = [
+        s for s in get_env_upstream_sources()
+        if s.source_type == "pypi" and s.enabled
+    ]
+
+    # Combine and sort by priority
+    all_sources = list(db_sources) + list(env_sources)
+    return sorted(all_sources, key=lambda s: s.priority)
+
+
+def _build_auth_headers(source) -> dict:
+    """Build authentication headers for an upstream source."""
+    headers = {}
+
+    if hasattr(source, 'auth_type'):
+        if source.auth_type == "bearer":
+            password = source.get_password() if hasattr(source, 'get_password') else getattr(source, 'password', None)
+            if password:
+                headers["Authorization"] = f"Bearer {password}"
+        elif source.auth_type == "api_key":
+            custom_headers = source.get_headers() if hasattr(source, 'get_headers') else {}
+            if custom_headers:
+                headers.update(custom_headers)
+
+    return headers
+
+
+def _get_basic_auth(source) -> Optional[tuple[str, str]]:
+    """Get basic auth credentials if applicable."""
+    if hasattr(source, 'auth_type') and source.auth_type == "basic":
+        username = getattr(source, 'username', None)
+        if username:
+            password = source.get_password() if hasattr(source, 'get_password') else getattr(source, 'password', '')
+            return (username, password or '')
+    return None
+
+
+def _get_base_url(request: Request) -> str:
+    """
+    Get the external base URL, respecting X-Forwarded-Proto header.
+
+    When behind a reverse proxy that terminates SSL, the request.base_url
+    will show http:// even though the external URL is https://. This function
+    checks the X-Forwarded-Proto header to determine the correct scheme.
+    """
+    base_url = str(request.base_url).rstrip('/')
+
+    # Check for X-Forwarded-Proto header (set by reverse proxies)
+    forwarded_proto = request.headers.get('x-forwarded-proto')
+    if forwarded_proto:
+        # Replace the scheme with the forwarded protocol
+        parsed = urlparse(base_url)
+        base_url = f"{forwarded_proto}://{parsed.netloc}{parsed.path}"
+
+    return base_url
+
+
+def _rewrite_package_links(html: str, base_url: str, package_name: str, upstream_base_url: str) -> str:
+    """
+    Rewrite download links in a PyPI simple page to go through our proxy.
+
+    Args:
+        html: The HTML content from upstream
+        base_url: Our server's base URL
+        package_name: The package name for the URL path
+        upstream_base_url: The upstream URL used to fetch this page (for resolving relative URLs)
+
+    Returns:
+        HTML with rewritten download links
+    """
+    # Pattern to match href attributes in anchor tags
+    # PyPI simple pages have links like:
+    # <a href="https://files.pythonhosted.org/packages/.../file.tar.gz#sha256=...">file.tar.gz</a>
+    # Or relative URLs from Artifactory like:
+    # <a href="../../packages/packages/62/35/.../requests-0.10.0.tar.gz#sha256=...">
+
+    def replace_href(match):
+        original_url = match.group(1)
+
+        # Resolve relative URLs to absolute using the upstream base URL
+        if not original_url.startswith(('http://', 'https://')):
+            # Split off fragment before resolving
+            url_without_fragment = original_url.split('#')[0]
+            fragment_part = original_url[len(url_without_fragment):]
+            absolute_url = urljoin(upstream_base_url, url_without_fragment) + fragment_part
+        else:
+            absolute_url = original_url
+
+        # Extract the filename from the URL
+        parsed = urlparse(absolute_url)
+        path_parts = parsed.path.split('/')
+        filename = path_parts[-1] if path_parts else ''
+
+        # Keep the hash fragment if present
+        fragment = f"#{parsed.fragment}" if parsed.fragment else ""
+
+        # Encode the absolute URL (without fragment) for safe transmission
+        encoded_url = quote(absolute_url.split('#')[0], safe='')
+
+        # Build new URL pointing to our proxy
+        new_url = f"{base_url}/pypi/simple/{package_name}/{filename}?upstream={encoded_url}{fragment}"
+
+        return f'href="{new_url}"'
+
+    # Match href="..." patterns
+    rewritten = re.sub(r'href="([^"]+)"', replace_href, html)
+
+    return rewritten
+
+
+@router.get("/simple/")
+async def pypi_simple_index(
+    request: Request,
+    db: Session = Depends(get_db),
+):
+    """
+    PyPI Simple API index - lists all packages.
+
+    Proxies to the first available upstream PyPI source.
+    """
+    sources = _get_pypi_upstream_sources(db)
+
+    if not sources:
+        raise HTTPException(
+            status_code=503,
+            detail="No PyPI upstream sources configured"
+        )
+
+    # Try each source in priority order
+    last_error = None
+    last_status = None
+    for source in sources:
+        try:
+            headers = {"User-Agent": "Orchard-PyPI-Proxy/1.0"}
+            headers.update(_build_auth_headers(source))
+            auth = _get_basic_auth(source)
+
+            # Use URL as-is - users should provide full path including /simple
+            simple_url = source.url.rstrip('/') + '/'
+
+            timeout = httpx.Timeout(PROXY_READ_TIMEOUT, connect=PROXY_CONNECT_TIMEOUT)
+
+            async with httpx.AsyncClient(timeout=timeout, follow_redirects=False) as client:
+                response = await client.get(
+                    simple_url,
+                    headers=headers,
+                    auth=auth,
+                )
+
+                # Handle redirects manually to avoid loops
+                if response.status_code in (301, 302, 303, 307, 308):
+                    redirect_url = response.headers.get('location')
+                    if redirect_url:
+                        # Follow the redirect once
+                        response = await client.get(
+                            redirect_url,
+                            headers=headers,
+                            auth=auth,
+                            follow_redirects=False,
+                        )
+
+                if response.status_code == 200:
+                    # Return the index as-is (links are to package pages, not files)
+                    # We could rewrite these too, but for now just proxy
+                    content = response.text
+
+                    # Rewrite package links to go through our proxy
+                    base_url = _get_base_url(request)
+                    content = re.sub(
+                        r'href="([^"]+)/"',
+                        lambda m: f'href="{base_url}/pypi/simple/{m.group(1)}/"',
+                        content
+                    )
+
+                    return HTMLResponse(content=content)
+
+                # Parse upstream error for policy/blocking messages
+                last_error = _parse_upstream_error(response)
+                last_status = response.status_code
+                logger.warning(f"PyPI proxy: upstream returned {response.status_code}: {last_error}")
+
+        except httpx.ConnectError as e:
+            last_error = f"Connection failed: {e}"
+            last_status = 502
+            logger.warning(f"PyPI proxy: failed to connect to {source.url}: {e}")
+        except httpx.TimeoutException as e:
+            last_error = f"Timeout: {e}"
+            last_status = 504
+            logger.warning(f"PyPI proxy: timeout connecting to {source.url}: {e}")
+        except Exception as e:
+            last_error = str(e)
+            last_status = 502
+            logger.warning(f"PyPI proxy: error fetching from {source.url}: {e}")
+
+    # Pass through 4xx errors (like 403 policy blocks) so users understand why
+    status_code = last_status if last_status and 400 <= last_status < 500 else 502
+    raise HTTPException(
+        status_code=status_code,
+        detail=f"Upstream error: {last_error}"
+    )
+
+
+@router.get("/simple/{package_name}/")
+async def pypi_package_versions(
+    request: Request,
+    package_name: str,
+    db: Session = Depends(get_db),
+):
+    """
+    PyPI Simple API package page - lists all versions/files for a package.
+
+    Proxies to upstream and rewrites download links to go through our cache.
+    """
+    sources = _get_pypi_upstream_sources(db)
+
+    if not sources:
+        raise HTTPException(
+            status_code=503,
+            detail="No PyPI upstream sources configured"
+        )
+
+    base_url = _get_base_url(request)
+
+    # Normalize package name (PEP 503)
+    normalized_name = re.sub(r'[-_.]+', '-', package_name).lower()
+
+    # Try each source in priority order
+    last_error = None
+    last_status = None
+    for source in sources:
+        try:
+            headers = {"User-Agent": "Orchard-PyPI-Proxy/1.0"}
+            headers.update(_build_auth_headers(source))
+            auth = _get_basic_auth(source)
+
+            # Use URL as-is - users should provide full path including /simple
+            package_url = source.url.rstrip('/') + f'/{normalized_name}/'
+            final_url = package_url  # Track final URL after redirects
+
+            timeout = httpx.Timeout(PROXY_READ_TIMEOUT, connect=PROXY_CONNECT_TIMEOUT)
+
+            async with httpx.AsyncClient(timeout=timeout, follow_redirects=False) as client:
+                response = await client.get(
+                    package_url,
+                    headers=headers,
+                    auth=auth,
+                )
+
+                # Handle redirects manually
+                redirect_count = 0
+                while response.status_code in (301, 302, 303, 307, 308) and redirect_count < 5:
+                    redirect_url = response.headers.get('location')
+                    if not redirect_url:
+                        break
+
+                    # Make redirect URL absolute if needed
+                    if not redirect_url.startswith('http'):
+                        redirect_url = urljoin(final_url, redirect_url)
+
+                    final_url = redirect_url  # Update final URL
+
+                    response = await client.get(
+                        redirect_url,
+                        headers=headers,
+                        auth=auth,
+                        follow_redirects=False,
+                    )
+                    redirect_count += 1
+
+                if response.status_code == 200:
+                    content = response.text
+
+                    # Rewrite download links to go through our proxy
+                    # Pass final_url so relative URLs can be resolved correctly
+                    content = _rewrite_package_links(content, base_url, normalized_name, final_url)
+
+                    return HTMLResponse(content=content)
+
+                if response.status_code == 404:
+                    # Package not found in this source, try next
+                    last_error = f"Package not found in {source.name}"
+                    last_status = 404
+                    continue
+
+                # Parse upstream error for policy/blocking messages
+                last_error = _parse_upstream_error(response)
+                last_status = response.status_code
+                logger.warning(f"PyPI proxy: upstream returned {response.status_code} for {package_name}: {last_error}")
+
+        except httpx.ConnectError as e:
+            last_error = f"Connection failed: {e}"
+            last_status = 502
+            logger.warning(f"PyPI proxy: failed to connect to {source.url}: {e}")
+        except httpx.TimeoutException as e:
+            last_error = f"Timeout: {e}"
+            last_status = 504
+            logger.warning(f"PyPI proxy: timeout connecting to {source.url}: {e}")
+        except Exception as e:
+            last_error = str(e)
+            last_status = 502
+            logger.warning(f"PyPI proxy: error fetching {package_name} from {source.url}: {e}")
+
+    # Pass through 4xx errors (like 403 policy blocks) so users understand why
+    status_code = last_status if last_status and 400 <= last_status < 500 else 404
+    raise HTTPException(
+        status_code=status_code,
+        detail=f"Package '{package_name}' error: {last_error}"
+    )
+
+
+@router.get("/simple/{package_name}/{filename}")
+async def pypi_download_file(
+    request: Request,
+    package_name: str,
+    filename: str,
+    upstream: Optional[str] = None,
+    db: Session = Depends(get_db),
+    storage: S3Storage = Depends(get_storage),
+):
+    """
+    Download a package file, caching it in Orchard.
+
+    Args:
+        package_name: The package name
+        filename: The filename to download
+        upstream: URL-encoded upstream URL to fetch from
+    """
+    if not upstream:
+        raise HTTPException(
+            status_code=400,
+            detail="Missing 'upstream' query parameter with source URL"
+        )
+
+    # Decode the upstream URL
+    upstream_url = unquote(upstream)
+
+    # Check if we already have this URL cached
+    url_hash = hashlib.sha256(upstream_url.encode()).hexdigest()
+    cached_url = db.query(CachedUrl).filter(CachedUrl.url_hash == url_hash).first()
+
+    if cached_url:
+        # Serve from cache
+        artifact = db.query(Artifact).filter(Artifact.id == cached_url.artifact_id).first()
+        if artifact:
+            logger.info(f"PyPI proxy: serving cached {filename} (artifact {artifact.id[:12]})")
+            settings = get_settings()
+
+            try:
+                if settings.pypi_download_mode == "redirect":
+                    # Redirect to S3 presigned URL - client downloads directly from S3
+                    presigned_url = storage.generate_presigned_url(artifact.s3_key)
+                    return RedirectResponse(
+                        url=presigned_url,
+                        status_code=302,
+                        headers={
+                            "X-Checksum-SHA256": artifact.id,
+                            "X-Cache": "HIT",
+                        }
+                    )
+                else:
+                    # Proxy mode - stream from S3 through Orchard
+                    stream, content_length, _ = storage.get_stream(artifact.s3_key)
+
+                    def stream_content():
+                        """Generator that yields chunks from the S3 stream."""
+                        try:
+                            for chunk in stream.iter_chunks():
+                                yield chunk
+                        finally:
+                            stream.close()
+
+                    return StreamingResponse(
+                        stream_content(),
+                        media_type=artifact.content_type or "application/octet-stream",
+                        headers={
+                            "Content-Disposition": f'attachment; filename="{filename}"',
+                            "Content-Length": str(content_length),
+                            "X-Checksum-SHA256": artifact.id,
+                            "X-Cache": "HIT",
+                        }
+                    )
+            except Exception as e:
+                logger.error(f"PyPI proxy: error serving cached artifact: {e}")
+                # Fall through to fetch from upstream
+
+    # Not cached - fetch from upstream
+    sources = _get_pypi_upstream_sources(db)
+
+    # Use the first available source for authentication headers
+    # Note: The upstream URL may point to files.pythonhosted.org or other CDNs,
+    # not the configured source URL directly, so we can't strictly validate the host
+    matched_source = sources[0] if sources else None
+
+    try:
+        headers = {"User-Agent": "Orchard-PyPI-Proxy/1.0"}
+        if matched_source:
+            headers.update(_build_auth_headers(matched_source))
+        auth = _get_basic_auth(matched_source) if matched_source else None
+
+        timeout = httpx.Timeout(300.0, connect=PROXY_CONNECT_TIMEOUT)  # 5 minutes for large files
+
+        # Initialize extracted dependencies list
+        extracted_deps = []
+
+        # Fetch the file
+        logger.info(f"PyPI proxy: fetching {filename} from {upstream_url}")
+
+        async with httpx.AsyncClient(timeout=timeout, follow_redirects=False) as client:
+            response = await client.get(
+                upstream_url,
+                headers=headers,
+                auth=auth,
+            )
+
+            # Handle redirects manually
+            redirect_count = 0
+            while response.status_code in (301, 302, 303, 307, 308) and redirect_count < 5:
+                redirect_url = response.headers.get('location')
+                if not redirect_url:
+                    break
+
+                if not redirect_url.startswith('http'):
+                    redirect_url = urljoin(upstream_url, redirect_url)
+
+                logger.info(f"PyPI proxy: following redirect to {redirect_url}")
+
+                # Don't send auth to different hosts
+                redirect_headers = {"User-Agent": "Orchard-PyPI-Proxy/1.0"}
+                redirect_auth = None
+                if urlparse(redirect_url).netloc == urlparse(upstream_url).netloc:
+                    redirect_headers.update(headers)
+                    redirect_auth = auth
+
+                response = await client.get(
+                    redirect_url,
+                    headers=redirect_headers,
+                    auth=redirect_auth,
+                    follow_redirects=False,
+                )
+                redirect_count += 1
+
+            if response.status_code != 200:
+                # Parse upstream error for policy/blocking messages
+                error_detail = _parse_upstream_error(response)
+                logger.warning(f"PyPI proxy: upstream returned {response.status_code} for {filename}: {error_detail}")
+                raise HTTPException(
+                    status_code=response.status_code,
+                    detail=f"Upstream error: {error_detail}"
+                )
+
+            content_type = response.headers.get('content-type', 'application/octet-stream')
+
+            # Stream to temp file to avoid loading large packages into memory
+            # This keeps memory usage constant regardless of package size
+            # Using async iteration to avoid blocking the event loop
+            tmp_path = None
+            try:
+                with tempfile.NamedTemporaryFile(delete=False, suffix=f"_{filename}") as tmp_file:
+                    tmp_path = tmp_file.name
+                    async for chunk in response.aiter_bytes(chunk_size=65536):  # 64KB chunks
+                        tmp_file.write(chunk)
+
+                # Store in S3 from temp file (computes hash and deduplicates automatically)
+                with open(tmp_path, 'rb') as f:
+                    result = storage.store(f)
+                sha256 = result.sha256
+                size = result.size
+                s3_key = result.s3_key
+
+                # Extract dependencies from the temp file before cleaning up
+                extracted_deps = _extract_dependencies_from_file(tmp_path, filename)
+                if extracted_deps:
+                    logger.info(f"PyPI proxy: extracted {len(extracted_deps)} dependencies from {filename}")
+
+                logger.info(f"PyPI proxy: downloaded {filename}, {size} bytes, sha256={sha256[:12]}")
+            finally:
+                # Clean up temp file
+                if tmp_path and os.path.exists(tmp_path):
+                    os.unlink(tmp_path)
+
+        # Check if artifact already exists
+        existing = db.query(Artifact).filter(Artifact.id == sha256).first()
+        if existing:
+            # Increment ref count
+            existing.ref_count += 1
+            db.flush()
+        else:
+            # Create artifact record
+            new_artifact = Artifact(
+                id=sha256,
+                original_name=filename,
+                content_type=content_type,
+                size=size,
+                ref_count=1,
+                created_by="pypi-proxy",
+                s3_key=result.s3_key,
+                checksum_md5=result.md5,
+                checksum_sha1=result.sha1,
+                s3_etag=result.s3_etag,
+            )
+            db.add(new_artifact)
+            db.flush()
+
+        # Create/get system project and package
+        system_project = db.query(Project).filter(Project.name == "_pypi").first()
+        if not system_project:
+            system_project = Project(
+                name="_pypi",
+                description="System project for cached PyPI packages",
+                is_public=True,
+                is_system=True,
+                created_by="pypi-proxy",
+            )
+            db.add(system_project)
+            db.flush()
+        elif not system_project.is_system:
+            # Ensure existing project is marked as system
+            system_project.is_system = True
+            db.flush()
+
+        # Normalize package name
+        normalized_name = re.sub(r'[-_.]+', '-', package_name).lower()
+
+        package = db.query(Package).filter(
+            Package.project_id == system_project.id,
+            Package.name == normalized_name,
+        ).first()
+        if not package:
+            package = Package(
+                project_id=system_project.id,
+                name=normalized_name,
+                description=f"PyPI package: {normalized_name}",
+                format="pypi",
+            )
+            db.add(package)
+            db.flush()
+
+        # Extract and create version
+        # Only create version for actual package files, not .metadata files
+        version = _extract_pypi_version(filename)
+        if version and not filename.endswith('.metadata'):
+            # Check by version string (the unique constraint is on package_id + version)
+            existing_version = db.query(PackageVersion).filter(
+                PackageVersion.package_id == package.id,
+                PackageVersion.version == version,
+            ).first()
+            if not existing_version:
+                pkg_version = PackageVersion(
+                    package_id=package.id,
+                    artifact_id=sha256,
+                    version=version,
+                    version_source="filename",
+                    created_by="pypi-proxy",
+                )
+                db.add(pkg_version)
+
+        # Cache the URL mapping
+        existing_cached = db.query(CachedUrl).filter(CachedUrl.url_hash == url_hash).first()
+        if not existing_cached:
+            cached_url_record = CachedUrl(
+                url_hash=url_hash,
+                url=upstream_url,
+                artifact_id=sha256,
+            )
+            db.add(cached_url_record)
+
+        # Store extracted dependencies (deduplicate first - METADATA can list same dep under multiple extras)
+        if extracted_deps:
+            # Deduplicate: keep first version constraint seen for each package name
+            seen_deps: dict[str, str] = {}
+            for dep_name, dep_version in extracted_deps:
+                if dep_name not in seen_deps:
+                    seen_deps[dep_name] = dep_version if dep_version else "*"
+
+            for dep_name, dep_version in seen_deps.items():
+                # Check if this dependency already exists for this artifact
+                existing_dep = db.query(ArtifactDependency).filter(
+                    ArtifactDependency.artifact_id == sha256,
+                    ArtifactDependency.dependency_project == "_pypi",
+                    ArtifactDependency.dependency_package == dep_name,
+                ).first()
+
+                if not existing_dep:
+                    dep = ArtifactDependency(
+                        artifact_id=sha256,
+                        dependency_project="_pypi",
+                        dependency_package=dep_name,
+                        version_constraint=dep_version,
+                    )
+                    db.add(dep)
+
+        db.commit()
+
+        # Serve the file from S3
+        settings = get_settings()
+        try:
+            if settings.pypi_download_mode == "redirect":
+                # Redirect to S3 presigned URL - client downloads directly from S3
+                presigned_url = storage.generate_presigned_url(s3_key)
+                return RedirectResponse(
+                    url=presigned_url,
+                    status_code=302,
+                    headers={
+                        "X-Checksum-SHA256": sha256,
+                        "X-Cache": "MISS",
+                    }
+                )
+            else:
+                # Proxy mode - stream from S3 through Orchard
+                stream, content_length, _ = storage.get_stream(s3_key)
+
+                def stream_content():
+                    """Generator that yields chunks from the S3 stream."""
+                    try:
+                        for chunk in stream.iter_chunks():
+                            yield chunk
+                    finally:
+                        stream.close()
+
+                return StreamingResponse(
+                    stream_content(),
+                    media_type=content_type,
+                    headers={
+                        "Content-Disposition": f'attachment; filename="{filename}"',
+                        "Content-Length": str(size),
+                        "X-Checksum-SHA256": sha256,
+                        "X-Cache": "MISS",
+                    }
+                )
+        except Exception as e:
+            logger.error(f"PyPI proxy: error serving from S3: {e}")
+            raise HTTPException(status_code=500, detail=f"Error serving file: {e}")
+
+    except httpx.ConnectError as e:
+        raise HTTPException(status_code=502, detail=f"Connection failed: {e}")
+    except httpx.TimeoutException as e:
+        raise HTTPException(status_code=504, detail=f"Timeout: {e}")
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception(f"PyPI proxy: error downloading {filename}")
+        raise HTTPException(status_code=500, detail=str(e))

backend/app/repositories/__init__.py

@@ -9,7 +9,6 @@ from .base import BaseRepository
 from .project import ProjectRepository
 from .package import PackageRepository
 from .artifact import ArtifactRepository
-from .tag import TagRepository
 from .upload import UploadRepository
 
 __all__ = [
@@ -17,6 +16,5 @@ __all__ = [
     "ProjectRepository",
     "PackageRepository",
     "ArtifactRepository",
-    "TagRepository",
     "UploadRepository",
 ]

backend/app/repositories/artifact.py

@@ -8,7 +8,7 @@ from sqlalchemy import func, or_
 from uuid import UUID
 
 from .base import BaseRepository
-from ..models import Artifact, Tag, Upload, Package, Project
+from ..models import Artifact, PackageVersion, Upload, Package, Project
 
 
 class ArtifactRepository(BaseRepository[Artifact]):
@@ -77,14 +77,14 @@ class ArtifactRepository(BaseRepository[Artifact]):
             .all()
         )
 
-    def get_artifacts_without_tags(self, limit: int = 100) -> List[Artifact]:
-        """Get artifacts that have no tags pointing to them."""
-        # Subquery to find artifact IDs that have tags
-        tagged_artifacts = self.db.query(Tag.artifact_id).distinct().subquery()
+    def get_artifacts_without_versions(self, limit: int = 100) -> List[Artifact]:
+        """Get artifacts that have no versions pointing to them."""
+        # Subquery to find artifact IDs that have versions
+        versioned_artifacts = self.db.query(PackageVersion.artifact_id).distinct().subquery()
 
         return (
             self.db.query(Artifact)
-            .filter(~Artifact.id.in_(tagged_artifacts))
+            .filter(~Artifact.id.in_(versioned_artifacts))
             .limit(limit)
             .all()
         )
@@ -115,34 +115,34 @@ class ArtifactRepository(BaseRepository[Artifact]):
 
         return artifacts, total
 
-    def get_referencing_tags(self, artifact_id: str) -> List[Tuple[Tag, Package, Project]]:
-        """Get all tags referencing this artifact with package and project info."""
+    def get_referencing_versions(self, artifact_id: str) -> List[Tuple[PackageVersion, Package, Project]]:
+        """Get all versions referencing this artifact with package and project info."""
         return (
-            self.db.query(Tag, Package, Project)
-            .join(Package, Tag.package_id == Package.id)
+            self.db.query(PackageVersion, Package, Project)
+            .join(Package, PackageVersion.package_id == Package.id)
             .join(Project, Package.project_id == Project.id)
-            .filter(Tag.artifact_id == artifact_id)
+            .filter(PackageVersion.artifact_id == artifact_id)
             .all()
         )
 
-    def search(self, query_str: str, limit: int = 10) -> List[Tuple[Tag, Artifact, str, str]]:
+    def search(self, query_str: str, limit: int = 10) -> List[Tuple[PackageVersion, Artifact, str, str]]:
         """
-        Search artifacts by tag name or original filename.
-        Returns (tag, artifact, package_name, project_name) tuples.
+        Search artifacts by version or original filename.
+        Returns (version, artifact, package_name, project_name) tuples.
         """
         search_lower = query_str.lower()
         return (
-            self.db.query(Tag, Artifact, Package.name, Project.name)
-            .join(Artifact, Tag.artifact_id == Artifact.id)
-            .join(Package, Tag.package_id == Package.id)
+            self.db.query(PackageVersion, Artifact, Package.name, Project.name)
+            .join(Artifact, PackageVersion.artifact_id == Artifact.id)
+            .join(Package, PackageVersion.package_id == Package.id)
             .join(Project, Package.project_id == Project.id)
             .filter(
                 or_(
-                    func.lower(Tag.name).contains(search_lower),
+                    func.lower(PackageVersion.version).contains(search_lower),
                     func.lower(Artifact.original_name).contains(search_lower)
                 )
             )
-            .order_by(Tag.name)
+            .order_by(PackageVersion.version)
             .limit(limit)
             .all()
         )

backend/app/repositories/package.py

@@ -8,7 +8,7 @@ from sqlalchemy import func, or_, asc, desc
 from uuid import UUID
 
 from .base import BaseRepository
-from ..models import Package, Project, Tag, Upload, Artifact
+from ..models import Package, Project, PackageVersion, Upload, Artifact
 
 
 class PackageRepository(BaseRepository[Package]):
@@ -136,10 +136,10 @@ class PackageRepository(BaseRepository[Package]):
         return self.update(package, **updates)
 
     def get_stats(self, package_id: UUID) -> dict:
-        """Get package statistics (tag count, artifact count, total size)."""
-        tag_count = (
-            self.db.query(func.count(Tag.id))
-            .filter(Tag.package_id == package_id)
+        """Get package statistics (version count, artifact count, total size)."""
+        version_count = (
+            self.db.query(func.count(PackageVersion.id))
+            .filter(PackageVersion.package_id == package_id)
             .scalar() or 0
         )
 
@@ -154,7 +154,7 @@ class PackageRepository(BaseRepository[Package]):
         )
 
         return {
-            "tag_count": tag_count,
+            "version_count": version_count,
             "artifact_count": artifact_stats[0] if artifact_stats else 0,
             "total_size": artifact_stats[1] if artifact_stats else 0,
         }

backend/app/repositories/tag.py

@@ -1,168 +0,0 @@
-"""
-Tag repository for data access operations.
-"""
-
-from typing import Optional, List, Tuple
-from sqlalchemy.orm import Session
-from sqlalchemy import func, or_, asc, desc
-from uuid import UUID
-
-from .base import BaseRepository
-from ..models import Tag, TagHistory, Artifact, Package, Project
-
-
-class TagRepository(BaseRepository[Tag]):
-    """Repository for Tag entity operations."""
-
-    model = Tag
-
-    def get_by_name(self, package_id: UUID, name: str) -> Optional[Tag]:
-        """Get tag by name within a package."""
-        return (
-            self.db.query(Tag)
-            .filter(Tag.package_id == package_id, Tag.name == name)
-            .first()
-        )
-
-    def get_with_artifact(self, package_id: UUID, name: str) -> Optional[Tuple[Tag, Artifact]]:
-        """Get tag with its artifact."""
-        return (
-            self.db.query(Tag, Artifact)
-            .join(Artifact, Tag.artifact_id == Artifact.id)
-            .filter(Tag.package_id == package_id, Tag.name == name)
-            .first()
-        )
-
-    def exists_by_name(self, package_id: UUID, name: str) -> bool:
-        """Check if tag with name exists in package."""
-        return self.db.query(
-            self.db.query(Tag)
-            .filter(Tag.package_id == package_id, Tag.name == name)
-            .exists()
-        ).scalar()
-
-    def list_by_package(
-        self,
-        package_id: UUID,
-        page: int = 1,
-        limit: int = 20,
-        search: Optional[str] = None,
-        sort: str = "name",
-        order: str = "asc",
-    ) -> Tuple[List[Tuple[Tag, Artifact]], int]:
-        """
-        List tags in a package with artifact metadata.
-
-        Returns tuple of ((tag, artifact) tuples, total_count).
-        """
-        query = (
-            self.db.query(Tag, Artifact)
-            .join(Artifact, Tag.artifact_id == Artifact.id)
-            .filter(Tag.package_id == package_id)
-        )
-
-        # Apply search filter (tag name or artifact original filename)
-        if search:
-            search_lower = search.lower()
-            query = query.filter(
-                or_(
-                    func.lower(Tag.name).contains(search_lower),
-                    func.lower(Artifact.original_name).contains(search_lower)
-                )
-            )
-
-        # Get total count
-        total = query.count()
-
-        # Apply sorting
-        sort_columns = {
-            "name": Tag.name,
-            "created_at": Tag.created_at,
-        }
-        sort_column = sort_columns.get(sort, Tag.name)
-        if order == "desc":
-            query = query.order_by(desc(sort_column))
-        else:
-            query = query.order_by(asc(sort_column))
-
-        # Apply pagination
-        offset = (page - 1) * limit
-        results = query.offset(offset).limit(limit).all()
-
-        return results, total
-
-    def create_tag(
-        self,
-        package_id: UUID,
-        name: str,
-        artifact_id: str,
-        created_by: str,
-    ) -> Tag:
-        """Create a new tag."""
-        return self.create(
-            package_id=package_id,
-            name=name,
-            artifact_id=artifact_id,
-            created_by=created_by,
-        )
-
-    def update_artifact(
-        self,
-        tag: Tag,
-        new_artifact_id: str,
-        changed_by: str,
-        record_history: bool = True,
-    ) -> Tag:
-        """
-        Update tag to point to a different artifact.
-        Optionally records change in tag history.
-        """
-        old_artifact_id = tag.artifact_id
-
-        if record_history and old_artifact_id != new_artifact_id:
-            history = TagHistory(
-                tag_id=tag.id,
-                old_artifact_id=old_artifact_id,
-                new_artifact_id=new_artifact_id,
-                changed_by=changed_by,
-            )
-            self.db.add(history)
-
-        tag.artifact_id = new_artifact_id
-        tag.created_by = changed_by
-        self.db.flush()
-        return tag
-
-    def get_history(self, tag_id: UUID) -> List[TagHistory]:
-        """Get tag change history."""
-        return (
-            self.db.query(TagHistory)
-            .filter(TagHistory.tag_id == tag_id)
-            .order_by(TagHistory.changed_at.desc())
-            .all()
-        )
-
-    def get_latest_in_package(self, package_id: UUID) -> Optional[Tag]:
-        """Get the most recently created/updated tag in a package."""
-        return (
-            self.db.query(Tag)
-            .filter(Tag.package_id == package_id)
-            .order_by(Tag.created_at.desc())
-            .first()
-        )
-
-    def get_by_artifact(self, artifact_id: str) -> List[Tag]:
-        """Get all tags pointing to an artifact."""
-        return (
-            self.db.query(Tag)
-            .filter(Tag.artifact_id == artifact_id)
-            .all()
-        )
-
-    def count_by_artifact(self, artifact_id: str) -> int:
-        """Count tags pointing to an artifact."""
-        return (
-            self.db.query(func.count(Tag.id))
-            .filter(Tag.artifact_id == artifact_id)
-            .scalar() or 0
-        )

backend/app/schemas.py

@@ -33,6 +33,7 @@ class ProjectResponse(BaseModel):
     name: str
     description: Optional[str]
     is_public: bool
+    is_system: bool = False
     created_at: datetime
     updated_at: datetime
     created_by: str
@@ -113,14 +114,6 @@ class PackageUpdate(BaseModel):
     platform: Optional[str] = None
 
 
-class TagSummary(BaseModel):
-    """Lightweight tag info for embedding in package responses"""
-
-    name: str
-    artifact_id: str
-    created_at: datetime
-
-
 class PackageDetailResponse(BaseModel):
     """Package with aggregated metadata"""
 
@@ -133,13 +126,9 @@ class PackageDetailResponse(BaseModel):
     created_at: datetime
     updated_at: datetime
     # Aggregated fields
-    tag_count: int = 0
     artifact_count: int = 0
     total_size: int = 0
-    latest_tag: Optional[str] = None
     latest_upload_at: Optional[datetime] = None
-    # Recent tags (limit 5)
-    recent_tags: List[TagSummary] = []
 
     class Config:
         from_attributes = True
@@ -164,79 +153,6 @@ class ArtifactResponse(BaseModel):
         from_attributes = True
 
 
-# Tag schemas
-class TagCreate(BaseModel):
-    name: str
-    artifact_id: str
-
-
-class TagResponse(BaseModel):
-    id: UUID
-    package_id: UUID
-    name: str
-    artifact_id: str
-    created_at: datetime
-    created_by: str
-    version: Optional[str] = None  # Version of the artifact this tag points to
-
-    class Config:
-        from_attributes = True
-
-
-class TagDetailResponse(BaseModel):
-    """Tag with embedded artifact metadata"""
-
-    id: UUID
-    package_id: UUID
-    name: str
-    artifact_id: str
-    created_at: datetime
-    created_by: str
-    version: Optional[str] = None  # Version of the artifact this tag points to
-    # Artifact metadata
-    artifact_size: int
-    artifact_content_type: Optional[str]
-    artifact_original_name: Optional[str]
-    artifact_created_at: datetime
-    artifact_format_metadata: Optional[Dict[str, Any]] = None
-
-    class Config:
-        from_attributes = True
-
-
-class TagHistoryResponse(BaseModel):
-    """History entry for tag changes"""
-
-    id: UUID
-    tag_id: UUID
-    old_artifact_id: Optional[str]
-    new_artifact_id: str
-    changed_at: datetime
-    changed_by: str
-
-    class Config:
-        from_attributes = True
-
-
-class TagHistoryDetailResponse(BaseModel):
-    """Tag history with artifact metadata for each version"""
-
-    id: UUID
-    tag_id: UUID
-    tag_name: str
-    old_artifact_id: Optional[str]
-    new_artifact_id: str
-    changed_at: datetime
-    changed_by: str
-    # Artifact metadata for new artifact
-    artifact_size: int
-    artifact_original_name: Optional[str]
-    artifact_content_type: Optional[str]
-
-    class Config:
-        from_attributes = True
-
-
 # Audit log schemas
 class AuditLogResponse(BaseModel):
     """Audit log entry response"""
@@ -263,7 +179,7 @@ class UploadHistoryResponse(BaseModel):
     package_name: str
     project_name: str
     original_name: Optional[str]
-    tag_name: Optional[str]
+    version: Optional[str]
     uploaded_at: datetime
     uploaded_by: str
     source_ip: Optional[str]
@@ -294,10 +210,10 @@ class ArtifactProvenanceResponse(BaseModel):
     # Usage statistics
     upload_count: int
     # References
-    packages: List[Dict[str, Any]]  # List of {project_name, package_name, tag_names}
-    tags: List[
+    packages: List[Dict[str, Any]]  # List of {project_name, package_name, versions}
+    versions: List[
         Dict[str, Any]
-    ]  # List of {project_name, package_name, tag_name, created_at}
+    ]  # List of {project_name, package_name, version, created_at}
     # Upload history
     uploads: List[Dict[str, Any]]  # List of upload events
 
@@ -305,18 +221,8 @@ class ArtifactProvenanceResponse(BaseModel):
         from_attributes = True
 
 
-class ArtifactTagInfo(BaseModel):
-    """Tag info for embedding in artifact responses"""
-
-    id: UUID
-    name: str
-    package_id: UUID
-    package_name: str
-    project_name: str
-
-
 class ArtifactDetailResponse(BaseModel):
-    """Artifact with list of tags/packages referencing it"""
+    """Artifact with metadata"""
 
     id: str
     sha256: str  # Explicit SHA256 field (same as id)
@@ -330,14 +236,14 @@ class ArtifactDetailResponse(BaseModel):
     created_by: str
     ref_count: int
     format_metadata: Optional[Dict[str, Any]] = None
-    tags: List[ArtifactTagInfo] = []
+    versions: List[Dict[str, Any]] = []  # List of {version, package_name, project_name}
 
     class Config:
         from_attributes = True
 
 
 class PackageArtifactResponse(BaseModel):
-    """Artifact with tags for package artifact listing"""
+    """Artifact for package artifact listing"""
 
     id: str
     sha256: str  # Explicit SHA256 field (same as id)
@@ -350,7 +256,7 @@ class PackageArtifactResponse(BaseModel):
     created_at: datetime
     created_by: str
     format_metadata: Optional[Dict[str, Any]] = None
-    tags: List[str] = []  # Tag names pointing to this artifact
+    version: Optional[str] = None  # Version from PackageVersion if exists
 
     class Config:
         from_attributes = True
@@ -368,28 +274,9 @@ class GlobalArtifactResponse(BaseModel):
     created_by: str
     format_metadata: Optional[Dict[str, Any]] = None
     ref_count: int = 0
-    # Context from tags/packages
+    # Context from versions/packages
     projects: List[str] = []  # List of project names containing this artifact
     packages: List[str] = []  # List of "project/package" paths
-    tags: List[str] = []  # List of "project/package:tag" references
-
-    class Config:
-        from_attributes = True
-
-
-class GlobalTagResponse(BaseModel):
-    """Tag with project/package context for global listing"""
-
-    id: UUID
-    name: str
-    artifact_id: str
-    created_at: datetime
-    created_by: str
-    project_name: str
-    package_name: str
-    artifact_size: Optional[int] = None
-    artifact_content_type: Optional[str] = None
-    version: Optional[str] = None  # Version of the artifact this tag points to
 
     class Config:
         from_attributes = True
@@ -402,7 +289,6 @@ class UploadResponse(BaseModel):
     size: int
     project: str
     package: str
-    tag: Optional[str]
     version: Optional[str] = None  # Version assigned to this artifact
     version_source: Optional[str] = None  # How version was determined: 'explicit', 'filename', 'metadata'
     checksum_md5: Optional[str] = None
@@ -429,7 +315,6 @@ class ResumableUploadInitRequest(BaseModel):
     filename: str
     content_type: Optional[str] = None
     size: int
-    tag: Optional[str] = None
     version: Optional[str] = None  # Explicit version (auto-detected if not provided)
 
     @field_validator("expected_hash")
@@ -464,7 +349,7 @@ class ResumableUploadPartResponse(BaseModel):
 class ResumableUploadCompleteRequest(BaseModel):
     """Request to complete a resumable upload"""
 
-    tag: Optional[str] = None
+    pass
 
 
 class ResumableUploadCompleteResponse(BaseModel):
@@ -474,7 +359,6 @@ class ResumableUploadCompleteResponse(BaseModel):
     size: int
     project: str
     package: str
-    tag: Optional[str]
 
 
 class ResumableUploadStatusResponse(BaseModel):
@@ -527,7 +411,6 @@ class PackageVersionResponse(BaseModel):
     size: Optional[int] = None
     content_type: Optional[str] = None
     original_name: Optional[str] = None
-    tags: List[str] = []  # Tag names pointing to this artifact
 
     class Config:
         from_attributes = True
@@ -569,11 +452,10 @@ class SearchResultPackage(BaseModel):
 
 
 class SearchResultArtifact(BaseModel):
-    """Artifact/tag result for global search"""
+    """Artifact result for global search"""
 
-    tag_id: UUID
-    tag_name: str
     artifact_id: str
+    version: Optional[str]
     package_id: UUID
     package_name: str
     project_name: str
@@ -686,7 +568,7 @@ class ProjectStatsResponse(BaseModel):
     project_id: str
     project_name: str
     package_count: int
-    tag_count: int
+    version_count: int
     artifact_count: int
     total_size_bytes: int
     upload_count: int
@@ -701,7 +583,7 @@ class PackageStatsResponse(BaseModel):
     package_id: str
     package_name: str
     project_name: str
-    tag_count: int
+    version_count: int
     artifact_count: int
     total_size_bytes: int
     upload_count: int
@@ -718,9 +600,9 @@ class ArtifactStatsResponse(BaseModel):
     size: int
     ref_count: int
     storage_savings: int  # (ref_count - 1) * size
-    tags: List[Dict[str, Any]]  # Tags referencing this artifact
     projects: List[str]  # Projects using this artifact
     packages: List[str]  # Packages using this artifact
+    versions: List[Dict[str, Any]] = []  # List of {version, package_name, project_name}
     first_uploaded: Optional[datetime] = None
     last_referenced: Optional[datetime] = None
 
@@ -929,20 +811,7 @@ class DependencyCreate(BaseModel):
     """Schema for creating a dependency"""
     project: str
     package: str
-    version: Optional[str] = None
-    tag: Optional[str] = None
-
-    @field_validator('version', 'tag')
-    @classmethod
-    def validate_constraint(cls, v, info):
-        return v
-
-    def model_post_init(self, __context):
-        """Validate that exactly one of version or tag is set"""
-        if self.version is None and self.tag is None:
-            raise ValueError("Either 'version' or 'tag' must be specified")
-        if self.version is not None and self.tag is not None:
-            raise ValueError("Cannot specify both 'version' and 'tag'")
+    version: str
 
 
 class DependencyResponse(BaseModel):
@@ -951,8 +820,7 @@ class DependencyResponse(BaseModel):
     artifact_id: str
     project: str
     package: str
-    version: Optional[str] = None
-    tag: Optional[str] = None
+    version: str
     created_at: datetime
 
     class Config:
@@ -967,7 +835,6 @@ class DependencyResponse(BaseModel):
             project=dep.dependency_project,
             package=dep.dependency_package,
             version=dep.version_constraint,
-            tag=dep.tag_constraint,
             created_at=dep.created_at,
         )
 
@@ -984,7 +851,6 @@ class DependentInfo(BaseModel):
     project: str
     package: str
     version: Optional[str] = None
-    constraint_type: str  # 'version' or 'tag'
     constraint_value: str
 
 
@@ -1000,20 +866,7 @@ class EnsureFileDependency(BaseModel):
     """Dependency entry from orchard.ensure file"""
     project: str
     package: str
-    version: Optional[str] = None
-    tag: Optional[str] = None
-
-    @field_validator('version', 'tag')
-    @classmethod
-    def validate_constraint(cls, v, info):
-        return v
-
-    def model_post_init(self, __context):
-        """Validate that exactly one of version or tag is set"""
-        if self.version is None and self.tag is None:
-            raise ValueError("Either 'version' or 'tag' must be specified")
-        if self.version is not None and self.tag is not None:
-            raise ValueError("Cannot specify both 'version' and 'tag'")
+    version: str
 
 
 class EnsureFileContent(BaseModel):
@@ -1027,15 +880,23 @@ class ResolvedArtifact(BaseModel):
     project: str
     package: str
     version: Optional[str] = None
-    tag: Optional[str] = None
     size: int
     download_url: str
 
 
+class MissingDependency(BaseModel):
+    """A dependency that could not be resolved (not cached on server)"""
+    project: str
+    package: str
+    constraint: Optional[str] = None
+    required_by: Optional[str] = None
+
+
 class DependencyResolutionResponse(BaseModel):
     """Response from dependency resolution endpoint"""
     requested: Dict[str, str]  # project, package, ref
     resolved: List[ResolvedArtifact]
+    missing: List[MissingDependency] = []
     total_size: int
     artifact_count: int
 
@@ -1044,7 +905,7 @@ class DependencyConflict(BaseModel):
     """Details about a dependency conflict"""
     project: str
     package: str
-    requirements: List[Dict[str, Any]]  # version/tag and required_by info
+    requirements: List[Dict[str, Any]]  # version and required_by info
 
 
 class DependencyConflictError(BaseModel):
@@ -1196,3 +1057,277 @@ class TeamMemberResponse(BaseModel):
     class Config:
         from_attributes = True
 
+
+# =============================================================================
+# Upstream Caching Schemas
+# =============================================================================
+
+# Valid source types
+SOURCE_TYPES = ["npm", "pypi", "maven", "docker", "helm", "nuget", "deb", "rpm", "generic"]
+
+# Valid auth types
+AUTH_TYPES = ["none", "basic", "bearer", "api_key"]
+
+
+class UpstreamSourceCreate(BaseModel):
+    """Create a new upstream source"""
+    name: str
+    source_type: str = "generic"
+    url: str
+    enabled: bool = False
+    auth_type: str = "none"
+    username: Optional[str] = None
+    password: Optional[str] = None  # Write-only
+    headers: Optional[dict] = None  # Write-only, custom headers
+    priority: int = 100
+
+    @field_validator('name')
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        v = v.strip()
+        if not v:
+            raise ValueError("name cannot be empty")
+        if len(v) > 255:
+            raise ValueError("name must be 255 characters or less")
+        return v
+
+    @field_validator('source_type')
+    @classmethod
+    def validate_source_type(cls, v: str) -> str:
+        if v not in SOURCE_TYPES:
+            raise ValueError(f"source_type must be one of: {', '.join(SOURCE_TYPES)}")
+        return v
+
+    @field_validator('url')
+    @classmethod
+    def validate_url(cls, v: str) -> str:
+        v = v.strip()
+        if not v:
+            raise ValueError("url cannot be empty")
+        if not (v.startswith('http://') or v.startswith('https://')):
+            raise ValueError("url must start with http:// or https://")
+        if len(v) > 2048:
+            raise ValueError("url must be 2048 characters or less")
+        return v
+
+    @field_validator('auth_type')
+    @classmethod
+    def validate_auth_type(cls, v: str) -> str:
+        if v not in AUTH_TYPES:
+            raise ValueError(f"auth_type must be one of: {', '.join(AUTH_TYPES)}")
+        return v
+
+    @field_validator('priority')
+    @classmethod
+    def validate_priority(cls, v: int) -> int:
+        if v <= 0:
+            raise ValueError("priority must be greater than 0")
+        return v
+
+
+class UpstreamSourceUpdate(BaseModel):
+    """Update an upstream source (partial)"""
+    name: Optional[str] = None
+    source_type: Optional[str] = None
+    url: Optional[str] = None
+    enabled: Optional[bool] = None
+    auth_type: Optional[str] = None
+    username: Optional[str] = None
+    password: Optional[str] = None  # Write-only, None = keep existing, empty string = clear
+    headers: Optional[dict] = None  # Write-only
+    priority: Optional[int] = None
+
+    @field_validator('name')
+    @classmethod
+    def validate_name(cls, v: Optional[str]) -> Optional[str]:
+        if v is not None:
+            v = v.strip()
+            if not v:
+                raise ValueError("name cannot be empty")
+            if len(v) > 255:
+                raise ValueError("name must be 255 characters or less")
+        return v
+
+    @field_validator('source_type')
+    @classmethod
+    def validate_source_type(cls, v: Optional[str]) -> Optional[str]:
+        if v is not None and v not in SOURCE_TYPES:
+            raise ValueError(f"source_type must be one of: {', '.join(SOURCE_TYPES)}")
+        return v
+
+    @field_validator('url')
+    @classmethod
+    def validate_url(cls, v: Optional[str]) -> Optional[str]:
+        if v is not None:
+            v = v.strip()
+            if not v:
+                raise ValueError("url cannot be empty")
+            if not (v.startswith('http://') or v.startswith('https://')):
+                raise ValueError("url must start with http:// or https://")
+            if len(v) > 2048:
+                raise ValueError("url must be 2048 characters or less")
+        return v
+
+    @field_validator('auth_type')
+    @classmethod
+    def validate_auth_type(cls, v: Optional[str]) -> Optional[str]:
+        if v is not None and v not in AUTH_TYPES:
+            raise ValueError(f"auth_type must be one of: {', '.join(AUTH_TYPES)}")
+        return v
+
+    @field_validator('priority')
+    @classmethod
+    def validate_priority(cls, v: Optional[int]) -> Optional[int]:
+        if v is not None and v <= 0:
+            raise ValueError("priority must be greater than 0")
+        return v
+
+
+class UpstreamSourceResponse(BaseModel):
+    """Upstream source response (credentials never included)"""
+    id: UUID
+    name: str
+    source_type: str
+    url: str
+    enabled: bool
+    auth_type: str
+    username: Optional[str]
+    has_password: bool  # True if password is set
+    has_headers: bool  # True if custom headers are set
+    priority: int
+    source: str = "database"  # "database" or "env" (env = defined via environment variables)
+    created_at: Optional[datetime] = None  # May be None for legacy/env data
+    updated_at: Optional[datetime] = None  # May be None for legacy/env data
+
+    class Config:
+        from_attributes = True
+
+
+class CacheSettingsResponse(BaseModel):
+    """Global cache settings response"""
+    auto_create_system_projects: bool
+    auto_create_system_projects_env_override: Optional[bool] = None  # Set if overridden by env var
+    created_at: Optional[datetime] = None  # May be None for legacy data
+    updated_at: Optional[datetime] = None  # May be None for legacy data
+
+    class Config:
+        from_attributes = True
+
+
+class CacheSettingsUpdate(BaseModel):
+    """Update cache settings (partial)"""
+    auto_create_system_projects: Optional[bool] = None
+
+
+class CachedUrlResponse(BaseModel):
+    """Cached URL response"""
+    id: UUID
+    url: str
+    url_hash: str
+    artifact_id: str
+    source_id: Optional[UUID]
+    source_name: Optional[str] = None  # Populated from join
+    fetched_at: datetime
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class CacheRequest(BaseModel):
+    """Request to cache an artifact from an upstream URL"""
+    url: str
+    source_type: str
+    package_name: Optional[str] = None  # Auto-derived from URL if not provided
+    version: Optional[str] = None  # Auto-derived from URL if not provided
+    user_project: Optional[str] = None  # Cross-reference to user project
+    user_package: Optional[str] = None
+    user_version: Optional[str] = None
+    expected_hash: Optional[str] = None  # Verify downloaded content
+
+    @field_validator('url')
+    @classmethod
+    def validate_url(cls, v: str) -> str:
+        v = v.strip()
+        if not v:
+            raise ValueError("url cannot be empty")
+        if not (v.startswith('http://') or v.startswith('https://')):
+            raise ValueError("url must start with http:// or https://")
+        if len(v) > 4096:
+            raise ValueError("url must be 4096 characters or less")
+        return v
+
+    @field_validator('source_type')
+    @classmethod
+    def validate_source_type(cls, v: str) -> str:
+        if v not in SOURCE_TYPES:
+            raise ValueError(f"source_type must be one of: {', '.join(SOURCE_TYPES)}")
+        return v
+
+    @field_validator('expected_hash')
+    @classmethod
+    def validate_expected_hash(cls, v: Optional[str]) -> Optional[str]:
+        if v is not None:
+            v = v.strip().lower()
+            # Remove sha256: prefix if present
+            if v.startswith('sha256:'):
+                v = v[7:]
+            # Validate hex format
+            if len(v) != 64 or not all(c in '0123456789abcdef' for c in v):
+                raise ValueError("expected_hash must be a 64-character hex string (SHA256)")
+        return v
+
+
+class CacheResponse(BaseModel):
+    """Response from caching an artifact"""
+    artifact_id: str
+    sha256: str
+    size: int
+    content_type: Optional[str]
+    already_cached: bool
+    source_url: str
+    source_name: Optional[str]
+    system_project: str
+    system_package: str
+    system_version: Optional[str]
+    user_reference: Optional[str] = None  # e.g., "my-app/npm-deps/+/4.17.21"
+
+
+class CacheResolveRequest(BaseModel):
+    """Request to cache an artifact by package coordinates (no URL required).
+
+    The server will construct the appropriate URL based on source_type and
+    configured upstream sources.
+    """
+    source_type: str
+    package: str
+    version: str
+    user_project: Optional[str] = None
+    user_package: Optional[str] = None
+    user_version: Optional[str] = None
+
+    @field_validator('source_type')
+    @classmethod
+    def validate_source_type(cls, v: str) -> str:
+        if v not in SOURCE_TYPES:
+            raise ValueError(f"source_type must be one of: {', '.join(SOURCE_TYPES)}")
+        return v
+
+    @field_validator('package')
+    @classmethod
+    def validate_package(cls, v: str) -> str:
+        v = v.strip()
+        if not v:
+            raise ValueError("package cannot be empty")
+        return v
+
+    @field_validator('version')
+    @classmethod
+    def validate_version(cls, v: str) -> str:
+        v = v.strip()
+        if not v:
+            raise ValueError("version cannot be empty")
+        return v
+
+
+

backend/app/seed.py

@@ -5,7 +5,7 @@ import hashlib
 import logging
 from sqlalchemy.orm import Session
 
-from .models import Project, Package, Artifact, Tag, Upload, PackageVersion, ArtifactDependency, Team, TeamMembership, User
+from .models import Project, Package, Artifact, Upload, PackageVersion, ArtifactDependency, Team, TeamMembership, User
 from .storage import get_storage
 from .auth import hash_password
 
@@ -125,14 +125,14 @@ TEST_ARTIFACTS = [
 ]
 
 # Dependencies to create (source artifact -> dependency)
-# Format: (source_project, source_package, source_version, dep_project, dep_package, version_constraint, tag_constraint)
+# Format: (source_project, source_package, source_version, dep_project, dep_package, version_constraint)
 TEST_DEPENDENCIES = [
     # ui-components v1.1.0 depends on design-tokens v1.0.0
-    ("frontend-libs", "ui-components", "1.1.0", "frontend-libs", "design-tokens", "1.0.0", None),
+    ("frontend-libs", "ui-components", "1.1.0", "frontend-libs", "design-tokens", "1.0.0"),
     # auth-lib v1.0.0 depends on common-utils v2.0.0
-    ("backend-services", "auth-lib", "1.0.0", "backend-services", "common-utils", "2.0.0", None),
-    # auth-lib v1.0.0 also depends on design-tokens (stable tag)
-    ("backend-services", "auth-lib", "1.0.0", "frontend-libs", "design-tokens", None, "latest"),
+    ("backend-services", "auth-lib", "1.0.0", "backend-services", "common-utils", "2.0.0"),
+    # auth-lib v1.0.0 also depends on design-tokens v1.0.0
+    ("backend-services", "auth-lib", "1.0.0", "frontend-libs", "design-tokens", "1.0.0"),
 ]
 
 
@@ -252,9 +252,8 @@ def seed_database(db: Session) -> None:
 
     logger.info(f"Created {len(project_map)} projects and {len(package_map)} packages (assigned to {demo_team.slug})")
 
-    # Create artifacts, tags, and versions
+    # Create artifacts and versions
     artifact_count = 0
-    tag_count = 0
     version_count = 0
 
     for artifact_data in TEST_ARTIFACTS:
@@ -316,23 +315,12 @@ def seed_database(db: Session) -> None:
             db.add(version)
             version_count += 1
 
-        # Create tags
-        for tag_name in artifact_data["tags"]:
-            tag = Tag(
-                package_id=package.id,
-                name=tag_name,
-                artifact_id=sha256_hash,
-                created_by=team_owner_username,
-            )
-            db.add(tag)
-            tag_count += 1
-
     db.flush()
 
     # Create dependencies
     dependency_count = 0
     for dep_data in TEST_DEPENDENCIES:
-        src_project, src_package, src_version, dep_project, dep_package, version_constraint, tag_constraint = dep_data
+        src_project, src_package, src_version, dep_project, dep_package, version_constraint = dep_data
 
         # Find the source artifact by looking up its version
         src_pkg = package_map.get((src_project, src_package))
@@ -356,11 +344,10 @@ def seed_database(db: Session) -> None:
             dependency_project=dep_project,
             dependency_package=dep_package,
             version_constraint=version_constraint,
-            tag_constraint=tag_constraint,
         )
         db.add(dependency)
         dependency_count += 1
 
     db.commit()
-    logger.info(f"Created {artifact_count} artifacts, {tag_count} tags, {version_count} versions, and {dependency_count} dependencies")
+    logger.info(f"Created {artifact_count} artifacts, {version_count} versions, and {dependency_count} dependencies")
     logger.info("Database seeding complete")

backend/app/services/artifact_cleanup.py

@@ -6,9 +6,8 @@ from typing import List, Optional, Tuple
 from sqlalchemy.orm import Session
 import logging
 
-from ..models import Artifact, Tag
+from ..models import Artifact, PackageVersion
 from ..repositories.artifact import ArtifactRepository
-from ..repositories.tag import TagRepository
 from ..storage import S3Storage
 
 logger = logging.getLogger(__name__)
@@ -21,8 +20,8 @@ class ArtifactCleanupService:
     Reference counting rules:
     - ref_count starts at 1 when artifact is first uploaded
     - ref_count increments when the same artifact is uploaded again (deduplication)
-    - ref_count decrements when a tag is deleted or updated to point elsewhere
-    - ref_count decrements when a package is deleted (for each tag pointing to artifact)
+    - ref_count decrements when a version is deleted or updated to point elsewhere
+    - ref_count decrements when a package is deleted (for each version pointing to artifact)
     - When ref_count reaches 0, artifact is a candidate for deletion from S3
     """
 
@@ -30,12 +29,11 @@ class ArtifactCleanupService:
         self.db = db
         self.storage = storage
         self.artifact_repo = ArtifactRepository(db)
-        self.tag_repo = TagRepository(db)
 
-    def on_tag_deleted(self, artifact_id: str) -> Artifact:
+    def on_version_deleted(self, artifact_id: str) -> Artifact:
         """
-        Called when a tag is deleted.
-        Decrements ref_count for the artifact the tag was pointing to.
+        Called when a version is deleted.
+        Decrements ref_count for the artifact the version was pointing to.
         """
         artifact = self.artifact_repo.get_by_sha256(artifact_id)
         if artifact:
@@ -45,11 +43,11 @@ class ArtifactCleanupService:
             )
         return artifact
 
-    def on_tag_updated(
+    def on_version_updated(
         self, old_artifact_id: str, new_artifact_id: str
     ) -> Tuple[Optional[Artifact], Optional[Artifact]]:
         """
-        Called when a tag is updated to point to a different artifact.
+        Called when a version is updated to point to a different artifact.
         Decrements ref_count for old artifact, increments for new (if different).
 
         Returns (old_artifact, new_artifact) tuple.
@@ -79,21 +77,21 @@ class ArtifactCleanupService:
     def on_package_deleted(self, package_id) -> List[str]:
         """
         Called when a package is deleted.
-        Decrements ref_count for all artifacts that had tags in the package.
+        Decrements ref_count for all artifacts that had versions in the package.
 
         Returns list of artifact IDs that were affected.
         """
-        # Get all tags in the package before deletion
-        tags = self.db.query(Tag).filter(Tag.package_id == package_id).all()
+        # Get all versions in the package before deletion
+        versions = self.db.query(PackageVersion).filter(PackageVersion.package_id == package_id).all()
 
         affected_artifacts = []
-        for tag in tags:
-            artifact = self.artifact_repo.get_by_sha256(tag.artifact_id)
+        for version in versions:
+            artifact = self.artifact_repo.get_by_sha256(version.artifact_id)
             if artifact:
                 self.artifact_repo.decrement_ref_count(artifact)
-                affected_artifacts.append(tag.artifact_id)
+                affected_artifacts.append(version.artifact_id)
                 logger.info(
-                    f"Decremented ref_count for artifact {tag.artifact_id} (package delete)"
+                    f"Decremented ref_count for artifact {version.artifact_id} (package delete)"
                 )
 
         return affected_artifacts
@@ -152,7 +150,7 @@ class ArtifactCleanupService:
 
     def verify_ref_counts(self, fix: bool = False) -> List[dict]:
         """
-        Verify that ref_counts match actual tag references.
+        Verify that ref_counts match actual version references.
 
         Args:
             fix: If True, fix any mismatched ref_counts
@@ -162,28 +160,28 @@ class ArtifactCleanupService:
         """
         from sqlalchemy import func
 
-        # Get actual tag counts per artifact
-        tag_counts = (
-            self.db.query(Tag.artifact_id, func.count(Tag.id).label("tag_count"))
-            .group_by(Tag.artifact_id)
+        # Get actual version counts per artifact
+        version_counts = (
+            self.db.query(PackageVersion.artifact_id, func.count(PackageVersion.id).label("version_count"))
+            .group_by(PackageVersion.artifact_id)
             .all()
         )
-        tag_count_map = {artifact_id: count for artifact_id, count in tag_counts}
+        version_count_map = {artifact_id: count for artifact_id, count in version_counts}
 
         # Check all artifacts
         artifacts = self.db.query(Artifact).all()
         mismatches = []
 
         for artifact in artifacts:
-            actual_count = tag_count_map.get(artifact.id, 0)
+            actual_count = version_count_map.get(artifact.id, 0)
             # ref_count should be at least 1 (initial upload) + additional uploads
-            # But tags are the primary reference, so we check against tag count
+            # But versions are the primary reference, so we check against version count
 
             if artifact.ref_count < actual_count:
                 mismatch = {
                     "artifact_id": artifact.id,
                     "stored_ref_count": artifact.ref_count,
-                    "actual_tag_count": actual_count,
+                    "actual_version_count": actual_count,
                 }
                 mismatches.append(mismatch)
 

backend/app/upstream.py

@@ -0,0 +1,565 @@
+"""
+HTTP client for fetching artifacts from upstream sources.
+
+Provides streaming downloads with SHA256 computation, authentication support,
+and automatic source matching based on URL prefixes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import tempfile
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import BinaryIO, Optional, TYPE_CHECKING
+from urllib.parse import urlparse
+
+import httpx
+
+if TYPE_CHECKING:
+    from .models import CacheSettings, UpstreamSource
+
+logger = logging.getLogger(__name__)
+
+
+class UpstreamError(Exception):
+    """Base exception for upstream client errors."""
+
+    pass
+
+
+class UpstreamConnectionError(UpstreamError):
+    """Connection to upstream failed (network error, DNS, etc.)."""
+
+    pass
+
+
+class UpstreamTimeoutError(UpstreamError):
+    """Request to upstream timed out."""
+
+    pass
+
+
+class UpstreamHTTPError(UpstreamError):
+    """Upstream returned an HTTP error response."""
+
+    def __init__(self, message: str, status_code: int, response_headers: dict = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_headers = response_headers or {}
+
+
+class UpstreamSSLError(UpstreamError):
+    """SSL/TLS error when connecting to upstream."""
+
+    pass
+
+
+
+
+class FileSizeExceededError(UpstreamError):
+    """File size exceeds the maximum allowed."""
+
+    def __init__(self, message: str, content_length: int, max_size: int):
+        super().__init__(message)
+        self.content_length = content_length
+        self.max_size = max_size
+
+
+class SourceNotFoundError(UpstreamError):
+    """No matching upstream source found for URL."""
+
+    pass
+
+
+class SourceDisabledError(UpstreamError):
+    """The matching upstream source is disabled."""
+
+    pass
+
+
+@dataclass
+class FetchResult:
+    """Result of fetching an artifact from upstream."""
+
+    content: BinaryIO  # File-like object with content
+    sha256: str  # SHA256 hash of content
+    size: int  # Size in bytes
+    content_type: Optional[str]  # Content-Type header
+    response_headers: dict  # All response headers for provenance
+    source_name: Optional[str] = None  # Name of matched upstream source
+    temp_path: Optional[Path] = None  # Path to temp file (for cleanup)
+
+    def close(self):
+        """Close and clean up resources."""
+        if self.content:
+            try:
+                self.content.close()
+            except Exception:
+                pass
+        if self.temp_path and self.temp_path.exists():
+            try:
+                self.temp_path.unlink()
+            except Exception:
+                pass
+
+
+@dataclass
+class UpstreamClientConfig:
+    """Configuration for the upstream client."""
+
+    connect_timeout: float = 30.0  # Connection timeout in seconds
+    read_timeout: float = 300.0  # Read timeout in seconds (5 minutes for large files)
+    max_retries: int = 3  # Maximum number of retry attempts
+    retry_backoff_base: float = 1.0  # Base delay for exponential backoff
+    retry_backoff_max: float = 30.0  # Maximum delay between retries
+    follow_redirects: bool = True  # Whether to follow redirects
+    max_redirects: int = 5  # Maximum number of redirects to follow
+    max_file_size: Optional[int] = None  # Maximum file size (None = unlimited)
+    verify_ssl: bool = True  # Verify SSL certificates
+    user_agent: str = "Orchard-UpstreamClient/1.0"
+
+
+class UpstreamClient:
+    """
+    HTTP client for fetching artifacts from upstream sources.
+
+    Supports streaming downloads, multiple authentication methods,
+    automatic source matching, and air-gap mode enforcement.
+    """
+
+    def __init__(
+        self,
+        sources: list[UpstreamSource] = None,
+        cache_settings: CacheSettings = None,
+        config: UpstreamClientConfig = None,
+    ):
+        """
+        Initialize the upstream client.
+
+        Args:
+            sources: List of upstream sources for URL matching and auth.
+                    Should be sorted by priority (lowest first).
+            cache_settings: Global cache settings including air-gap mode.
+            config: Client configuration options.
+        """
+        self.sources = sources or []
+        self.cache_settings = cache_settings
+        self.config = config or UpstreamClientConfig()
+
+        # Sort sources by priority (lower = higher priority)
+        self.sources = sorted(self.sources, key=lambda s: s.priority)
+
+    def _match_source(self, url: str) -> Optional[UpstreamSource]:
+        """
+        Find the upstream source that matches the given URL.
+
+        Matches by URL prefix, returns the highest priority match.
+
+        Args:
+            url: The URL to match.
+
+        Returns:
+            The matching UpstreamSource or None if no match.
+        """
+        for source in self.sources:
+            # Check if URL starts with source URL (prefix match)
+            if url.startswith(source.url.rstrip("/")):
+                return source
+
+        return None
+
+    def _build_auth_headers(self, source: UpstreamSource) -> dict:
+        """
+        Build authentication headers for the given source.
+
+        Args:
+            source: The upstream source with auth configuration.
+
+        Returns:
+            Dictionary of headers to add to the request.
+        """
+        headers = {}
+
+        if source.auth_type == "none":
+            pass
+        elif source.auth_type == "basic":
+            # httpx handles basic auth via auth parameter, but we can also
+            # do it manually if needed. We'll use the auth parameter instead.
+            pass
+        elif source.auth_type == "bearer":
+            password = source.get_password()
+            if password:
+                headers["Authorization"] = f"Bearer {password}"
+        elif source.auth_type == "api_key":
+            # API key auth uses custom headers
+            custom_headers = source.get_headers()
+            if custom_headers:
+                headers.update(custom_headers)
+
+        return headers
+
+    def _get_basic_auth(self, source: UpstreamSource) -> Optional[tuple[str, str]]:
+        """
+        Get basic auth credentials if applicable.
+
+        Args:
+            source: The upstream source.
+
+        Returns:
+            Tuple of (username, password) or None.
+        """
+        if source.auth_type == "basic" and source.username:
+            password = source.get_password() or ""
+            return (source.username, password)
+        return None
+
+    def _should_retry(self, error: Exception, attempt: int) -> bool:
+        """
+        Determine if a request should be retried.
+
+        Args:
+            error: The exception that occurred.
+            attempt: Current attempt number (0-indexed).
+
+        Returns:
+            True if the request should be retried.
+        """
+        if attempt >= self.config.max_retries - 1:
+            return False
+
+        # Retry on connection errors and timeouts
+        if isinstance(error, (httpx.ConnectError, httpx.ConnectTimeout)):
+            return True
+
+        # Retry on read timeouts
+        if isinstance(error, httpx.ReadTimeout):
+            return True
+
+        # Retry on certain HTTP errors (502, 503, 504)
+        if isinstance(error, httpx.HTTPStatusError):
+            return error.response.status_code in (502, 503, 504)
+
+        return False
+
+    def _calculate_backoff(self, attempt: int) -> float:
+        """
+        Calculate backoff delay for retry.
+
+        Uses exponential backoff with jitter.
+
+        Args:
+            attempt: Current attempt number (0-indexed).
+
+        Returns:
+            Delay in seconds.
+        """
+        import random
+
+        delay = self.config.retry_backoff_base * (2**attempt)
+        # Add jitter (±25%)
+        delay *= 0.75 + random.random() * 0.5
+        return min(delay, self.config.retry_backoff_max)
+
+    def fetch(self, url: str, expected_hash: Optional[str] = None) -> FetchResult:
+        """
+        Fetch an artifact from the given URL.
+
+        Streams the response to a temp file while computing the SHA256 hash.
+        Handles authentication, retries, and error cases.
+
+        Args:
+            url: The URL to fetch.
+            expected_hash: Optional expected SHA256 hash for verification.
+
+        Returns:
+            FetchResult with content, hash, size, and headers.
+
+        Raises:
+            SourceDisabledError: If the matching source is disabled.
+            UpstreamConnectionError: On connection failures.
+            UpstreamTimeoutError: On timeout.
+            UpstreamHTTPError: On HTTP error responses.
+            UpstreamSSLError: On SSL/TLS errors.
+            FileSizeExceededError: If Content-Length exceeds max_file_size.
+        """
+        start_time = time.time()
+
+        # Match URL to source
+        source = self._match_source(url)
+
+        # Check if source is enabled (if we have a match)
+        if source is not None and not source.enabled:
+            raise SourceDisabledError(
+                f"Upstream source '{source.name}' is disabled"
+            )
+
+        source_name = source.name if source else None
+        logger.info(
+            f"Fetching URL: {url} (source: {source_name or 'none'})"
+        )
+
+        # Build request parameters
+        headers = {"User-Agent": self.config.user_agent}
+        auth = None
+
+        if source:
+            headers.update(self._build_auth_headers(source))
+            auth = self._get_basic_auth(source)
+
+        timeout = httpx.Timeout(
+            connect=self.config.connect_timeout,
+            read=self.config.read_timeout,
+            write=30.0,
+            pool=10.0,
+        )
+
+        # Attempt fetch with retries
+        last_error = None
+        for attempt in range(self.config.max_retries):
+            try:
+                return self._do_fetch(
+                    url=url,
+                    headers=headers,
+                    auth=auth,
+                    timeout=timeout,
+                    source_name=source_name,
+                    start_time=start_time,
+                    expected_hash=expected_hash,
+                )
+            except (
+                httpx.ConnectError,
+                httpx.ConnectTimeout,
+                httpx.ReadTimeout,
+                httpx.HTTPStatusError,
+            ) as e:
+                last_error = e
+                if self._should_retry(e, attempt):
+                    delay = self._calculate_backoff(attempt)
+                    logger.warning(
+                        f"Fetch failed (attempt {attempt + 1}/{self.config.max_retries}), "
+                        f"retrying in {delay:.1f}s: {e}"
+                    )
+                    time.sleep(delay)
+                else:
+                    break
+
+        # Convert final error to our exception types
+        self._raise_upstream_error(last_error, url)
+
+    def _do_fetch(
+        self,
+        url: str,
+        headers: dict,
+        auth: Optional[tuple[str, str]],
+        timeout: httpx.Timeout,
+        source_name: Optional[str],
+        start_time: float,
+        expected_hash: Optional[str] = None,
+    ) -> FetchResult:
+        """
+        Perform the actual fetch operation.
+
+        Args:
+            url: URL to fetch.
+            headers: Request headers.
+            auth: Basic auth credentials or None.
+            timeout: Request timeout configuration.
+            source_name: Name of matched source for logging.
+            start_time: Request start time for timing.
+            expected_hash: Optional expected hash for verification.
+
+        Returns:
+            FetchResult with content and metadata.
+        """
+        with httpx.Client(
+            timeout=timeout,
+            follow_redirects=self.config.follow_redirects,
+            max_redirects=self.config.max_redirects,
+            verify=self.config.verify_ssl,
+        ) as client:
+            with client.stream("GET", url, headers=headers, auth=auth) as response:
+                # Check for HTTP errors
+                response.raise_for_status()
+
+                # Check Content-Length against max size
+                content_length = response.headers.get("content-length")
+                if content_length:
+                    content_length = int(content_length)
+                    if (
+                        self.config.max_file_size
+                        and content_length > self.config.max_file_size
+                    ):
+                        raise FileSizeExceededError(
+                            f"File size {content_length} exceeds maximum {self.config.max_file_size}",
+                            content_length,
+                            self.config.max_file_size,
+                        )
+
+                # Stream to temp file while computing hash
+                hasher = hashlib.sha256()
+                size = 0
+
+                # Create temp file
+                temp_file = tempfile.NamedTemporaryFile(
+                    delete=False, prefix="orchard_upstream_"
+                )
+                temp_path = Path(temp_file.name)
+
+                try:
+                    for chunk in response.iter_bytes(chunk_size=65536):
+                        temp_file.write(chunk)
+                        hasher.update(chunk)
+                        size += len(chunk)
+
+                        # Check size while streaming if max_file_size is set
+                        if self.config.max_file_size and size > self.config.max_file_size:
+                            temp_file.close()
+                            temp_path.unlink()
+                            raise FileSizeExceededError(
+                                f"Downloaded size {size} exceeds maximum {self.config.max_file_size}",
+                                size,
+                                self.config.max_file_size,
+                            )
+
+                    temp_file.close()
+
+                    sha256 = hasher.hexdigest()
+
+                    # Verify hash if expected
+                    if expected_hash and sha256 != expected_hash.lower():
+                        temp_path.unlink()
+                        raise UpstreamError(
+                            f"Hash mismatch: expected {expected_hash}, got {sha256}"
+                        )
+
+                    # Capture response headers
+                    response_headers = dict(response.headers)
+
+                    # Get content type
+                    content_type = response.headers.get("content-type")
+
+                    elapsed = time.time() - start_time
+                    logger.info(
+                        f"Fetched {url}: {size} bytes, sha256={sha256[:12]}..., "
+                        f"source={source_name}, time={elapsed:.2f}s"
+                    )
+
+                    # Return file handle positioned at start
+                    content = open(temp_path, "rb")
+
+                    return FetchResult(
+                        content=content,
+                        sha256=sha256,
+                        size=size,
+                        content_type=content_type,
+                        response_headers=response_headers,
+                        source_name=source_name,
+                        temp_path=temp_path,
+                    )
+
+                except Exception:
+                    # Clean up on error
+                    try:
+                        temp_file.close()
+                    except Exception:
+                        pass
+                    if temp_path.exists():
+                        temp_path.unlink()
+                    raise
+
+    def _raise_upstream_error(self, error: Exception, url: str):
+        """
+        Convert httpx exception to appropriate UpstreamError.
+
+        Args:
+            error: The httpx exception.
+            url: The URL that was being fetched.
+
+        Raises:
+            Appropriate UpstreamError subclass.
+        """
+        if error is None:
+            raise UpstreamError(f"Unknown error fetching {url}")
+
+        if isinstance(error, httpx.ConnectError):
+            raise UpstreamConnectionError(
+                f"Failed to connect to upstream: {error}"
+            ) from error
+
+        if isinstance(error, (httpx.ConnectTimeout, httpx.ReadTimeout)):
+            raise UpstreamTimeoutError(
+                f"Request timed out: {error}"
+            ) from error
+
+        if isinstance(error, httpx.HTTPStatusError):
+            raise UpstreamHTTPError(
+                f"HTTP {error.response.status_code}: {error}",
+                error.response.status_code,
+                dict(error.response.headers),
+            ) from error
+
+        # Check for SSL errors in the error chain
+        if "ssl" in str(error).lower() or "certificate" in str(error).lower():
+            raise UpstreamSSLError(f"SSL/TLS error: {error}") from error
+
+        raise UpstreamError(f"Error fetching {url}: {error}") from error
+
+    def test_connection(self, source: UpstreamSource) -> tuple[bool, Optional[str], Optional[int]]:
+        """
+        Test connectivity to an upstream source.
+
+        Performs a HEAD request to the source URL to verify connectivity
+        and authentication. Does not follow redirects - a 3xx response
+        is considered successful since it proves the server is reachable.
+
+        Args:
+            source: The upstream source to test.
+
+        Returns:
+            Tuple of (success, error_message, status_code).
+        """
+        headers = {"User-Agent": self.config.user_agent}
+        headers.update(self._build_auth_headers(source))
+        auth = self._get_basic_auth(source)
+
+        timeout = httpx.Timeout(
+            connect=self.config.connect_timeout,
+            read=30.0,
+            write=30.0,
+            pool=10.0,
+        )
+
+        try:
+            with httpx.Client(
+                timeout=timeout,
+                verify=self.config.verify_ssl,
+            ) as client:
+                response = client.head(
+                    source.url,
+                    headers=headers,
+                    auth=auth,
+                    follow_redirects=False,
+                )
+                # Consider 2xx and 3xx as success, also 405 (Method Not Allowed)
+                # since some servers don't support HEAD
+                if response.status_code < 400 or response.status_code == 405:
+                    return (True, None, response.status_code)
+                else:
+                    return (
+                        False,
+                        f"HTTP {response.status_code}",
+                        response.status_code,
+                    )
+        except httpx.ConnectError as e:
+            return (False, f"Connection failed: {e}", None)
+        except httpx.ConnectTimeout as e:
+            return (False, f"Connection timed out: {e}", None)
+        except httpx.ReadTimeout as e:
+            return (False, f"Read timed out: {e}", None)
+        except httpx.TooManyRedirects as e:
+            return (False, f"Too many redirects: {e}", None)
+        except Exception as e:
+            return (False, f"Error: {e}", None)

backend/requirements.txt

@@ -11,10 +11,10 @@ python-jose[cryptography]==3.3.0
 passlib[bcrypt]==1.7.4
 bcrypt==4.0.1
 slowapi==0.1.9
+httpx>=0.25.0
 
 # Test dependencies
 pytest>=7.4.0
 pytest-asyncio>=0.21.0
 pytest-cov>=4.1.0
-httpx>=0.25.0
 moto[s3]>=4.2.0

backend/scripts/__init__.py

@@ -0,0 +1 @@
+# Scripts package

backend/scripts/backfill_pypi_dependencies.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""
+Backfill script to extract dependencies from cached PyPI packages.
+
+This script scans all artifacts in the _pypi project and extracts
+Requires-Dist metadata from wheel and sdist files that don't already
+have dependencies recorded.
+
+Usage:
+    # From within the container:
+    python -m scripts.backfill_pypi_dependencies
+
+    # Or with docker exec:
+    docker exec orchard_orchard-server_1 python -m scripts.backfill_pypi_dependencies
+
+    # Dry run (preview only):
+    docker exec orchard_orchard-server_1 python -m scripts.backfill_pypi_dependencies --dry-run
+"""
+
+import argparse
+import logging
+import re
+import sys
+import tarfile
+import zipfile
+from io import BytesIO
+from typing import List, Optional, Tuple
+
+# Add parent directory to path for imports
+sys.path.insert(0, "/app")
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+from backend.app.config import get_settings
+from backend.app.models import (
+    Artifact,
+    ArtifactDependency,
+    Package,
+    Project,
+    Tag,
+)
+from backend.app.storage import get_storage
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+def parse_requires_dist(requires_dist: str) -> Tuple[Optional[str], Optional[str]]:
+    """Parse a Requires-Dist line into (package_name, version_constraint)."""
+    # Remove any environment markers (after semicolon)
+    if ";" in requires_dist:
+        requires_dist = requires_dist.split(";")[0].strip()
+
+    # Match patterns like "package (>=1.0)" or "package>=1.0" or "package"
+    match = re.match(
+        r"^([a-zA-Z0-9][-a-zA-Z0-9._]*)\s*(?:\(([^)]+)\)|([<>=!~][^\s;]+))?",
+        requires_dist.strip(),
+    )
+
+    if not match:
+        return None, None
+
+    package_name = match.group(1)
+    version_constraint = match.group(2) or match.group(3)
+
+    # Normalize package name (PEP 503)
+    normalized_name = re.sub(r"[-_.]+", "-", package_name).lower()
+
+    if version_constraint:
+        version_constraint = version_constraint.strip()
+
+    return normalized_name, version_constraint
+
+
+def extract_requires_from_metadata(metadata_content: str) -> List[Tuple[str, Optional[str]]]:
+    """Extract all Requires-Dist entries from METADATA/PKG-INFO content."""
+    dependencies = []
+
+    for line in metadata_content.split("\n"):
+        if line.startswith("Requires-Dist:"):
+            value = line[len("Requires-Dist:"):].strip()
+            pkg_name, version = parse_requires_dist(value)
+            if pkg_name:
+                dependencies.append((pkg_name, version))
+
+    return dependencies
+
+
+def extract_metadata_from_wheel(content: bytes) -> Optional[str]:
+    """Extract METADATA file content from a wheel (zip) file."""
+    try:
+        with zipfile.ZipFile(BytesIO(content)) as zf:
+            for name in zf.namelist():
+                if name.endswith(".dist-info/METADATA"):
+                    return zf.read(name).decode("utf-8", errors="replace")
+    except Exception as e:
+        logger.warning(f"Failed to extract metadata from wheel: {e}")
+    return None
+
+
+def extract_metadata_from_sdist(content: bytes) -> Optional[str]:
+    """Extract PKG-INFO file content from a source distribution (.tar.gz)."""
+    try:
+        with tarfile.open(fileobj=BytesIO(content), mode="r:gz") as tf:
+            for member in tf.getmembers():
+                if member.name.endswith("/PKG-INFO") and member.name.count("/") == 1:
+                    f = tf.extractfile(member)
+                    if f:
+                        return f.read().decode("utf-8", errors="replace")
+    except Exception as e:
+        logger.warning(f"Failed to extract metadata from sdist: {e}")
+    return None
+
+
+def extract_dependencies(content: bytes, filename: str) -> List[Tuple[str, Optional[str]]]:
+    """Extract dependencies from a PyPI package file."""
+    metadata = None
+
+    if filename.endswith(".whl"):
+        metadata = extract_metadata_from_wheel(content)
+    elif filename.endswith(".tar.gz"):
+        metadata = extract_metadata_from_sdist(content)
+
+    if metadata:
+        return extract_requires_from_metadata(metadata)
+
+    return []
+
+
+def backfill_dependencies(dry_run: bool = False):
+    """Main backfill function."""
+    settings = get_settings()
+
+    # Create database connection
+    engine = create_engine(settings.database_url)
+    Session = sessionmaker(bind=engine)
+    db = Session()
+
+    # Create storage client
+    storage = get_storage()
+
+    try:
+        # Find the _pypi project
+        pypi_project = db.query(Project).filter(Project.name == "_pypi").first()
+        if not pypi_project:
+            logger.info("No _pypi project found. Nothing to backfill.")
+            return
+
+        # Get all packages in _pypi
+        packages = db.query(Package).filter(Package.project_id == pypi_project.id).all()
+        logger.info(f"Found {len(packages)} packages in _pypi project")
+
+        total_artifacts = 0
+        artifacts_with_deps = 0
+        artifacts_processed = 0
+        dependencies_added = 0
+
+        for package in packages:
+            # Get all tags (each tag points to an artifact)
+            tags = db.query(Tag).filter(Tag.package_id == package.id).all()
+
+            for tag in tags:
+                total_artifacts += 1
+                filename = tag.name
+
+                # Skip non-package files (like .metadata files)
+                if not (filename.endswith(".whl") or filename.endswith(".tar.gz")):
+                    continue
+
+                # Check if this artifact already has dependencies
+                existing_deps = db.query(ArtifactDependency).filter(
+                    ArtifactDependency.artifact_id == tag.artifact_id
+                ).count()
+
+                if existing_deps > 0:
+                    artifacts_with_deps += 1
+                    continue
+
+                # Get the artifact
+                artifact = db.query(Artifact).filter(Artifact.id == tag.artifact_id).first()
+                if not artifact:
+                    logger.warning(f"Artifact {tag.artifact_id} not found for tag {filename}")
+                    continue
+
+                logger.info(f"Processing {package.name}/{filename}...")
+
+                if dry_run:
+                    logger.info(f"  [DRY RUN] Would extract dependencies from {filename}")
+                    artifacts_processed += 1
+                    continue
+
+                # Download the artifact from S3
+                try:
+                    content = storage.get(artifact.s3_key)
+                except Exception as e:
+                    logger.error(f"  Failed to download {filename}: {e}")
+                    continue
+
+                # Extract dependencies
+                deps = extract_dependencies(content, filename)
+
+                if deps:
+                    logger.info(f"  Found {len(deps)} dependencies")
+                    for dep_name, dep_version in deps:
+                        # Check if already exists (race condition protection)
+                        existing = db.query(ArtifactDependency).filter(
+                            ArtifactDependency.artifact_id == tag.artifact_id,
+                            ArtifactDependency.dependency_project == "_pypi",
+                            ArtifactDependency.dependency_package == dep_name,
+                        ).first()
+
+                        if not existing:
+                            dep = ArtifactDependency(
+                                artifact_id=tag.artifact_id,
+                                dependency_project="_pypi",
+                                dependency_package=dep_name,
+                                version_constraint=dep_version if dep_version else "*",
+                            )
+                            db.add(dep)
+                            dependencies_added += 1
+                            logger.info(f"    + {dep_name} {dep_version or '*'}")
+
+                    db.commit()
+                else:
+                    logger.info(f"  No dependencies found")
+
+                artifacts_processed += 1
+
+        logger.info("")
+        logger.info("=" * 50)
+        logger.info("Backfill complete!")
+        logger.info(f"  Total artifacts: {total_artifacts}")
+        logger.info(f"  Already had deps: {artifacts_with_deps}")
+        logger.info(f"  Processed: {artifacts_processed}")
+        logger.info(f"  Dependencies added: {dependencies_added}")
+        if dry_run:
+            logger.info("  (DRY RUN - no changes made)")
+
+    finally:
+        db.close()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Backfill dependencies for cached PyPI packages"
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview what would be done without making changes",
+    )
+    args = parser.parse_args()
+
+    backfill_dependencies(dry_run=args.dry_run)
+
+
+if __name__ == "__main__":
+    main()

backend/tests/factories.py

@@ -96,7 +96,6 @@ def upload_test_file(
     package: str,
     content: bytes,
     filename: str = "test.bin",
-    tag: Optional[str] = None,
     version: Optional[str] = None,
 ) -> dict:
     """
@@ -108,7 +107,6 @@ def upload_test_file(
         package: Package name
         content: File content as bytes
         filename: Original filename
-        tag: Optional tag to assign
         version: Optional version to assign
 
     Returns:
@@ -116,8 +114,6 @@ def upload_test_file(
     """
     files = {"file": (filename, io.BytesIO(content), "application/octet-stream")}
     data = {}
-    if tag:
-        data["tag"] = tag
     if version:
         data["version"] = version
 

backend/tests/integration/test_artifacts_api.py

@@ -25,7 +25,7 @@ class TestArtifactRetrieval:
         expected_hash = compute_sha256(content)
 
         upload_test_file(
-            integration_client, project_name, package_name, content, tag="v1"
+            integration_client, project_name, package_name, content, version="v1"
         )
 
         response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
@@ -46,27 +46,27 @@ class TestArtifactRetrieval:
         assert response.status_code == 404
 
     @pytest.mark.integration
-    def test_artifact_includes_tags(self, integration_client, test_package):
-        """Test artifact response includes tags pointing to it."""
+    def test_artifact_includes_versions(self, integration_client, test_package):
+        """Test artifact response includes versions pointing to it."""
         project_name, package_name = test_package
-        content = b"artifact with tags test"
+        content = b"artifact with versions test"
         expected_hash = compute_sha256(content)
 
         upload_test_file(
-            integration_client, project_name, package_name, content, tag="tagged-v1"
+            integration_client, project_name, package_name, content, version="1.0.0"
         )
 
         response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
         assert response.status_code == 200
 
         data = response.json()
-        assert "tags" in data
-        assert len(data["tags"]) >= 1
+        assert "versions" in data
+        assert len(data["versions"]) >= 1
 
-        tag = data["tags"][0]
-        assert "name" in tag
-        assert "package_name" in tag
-        assert "project_name" in tag
+        version = data["versions"][0]
+        assert "version" in version
+        assert "package_name" in version
+        assert "project_name" in version
 
 
 class TestArtifactStats:
@@ -82,7 +82,7 @@ class TestArtifactStats:
         expected_hash = compute_sha256(content)
 
         upload_test_file(
-            integration_client, project, package, content, tag=f"art-{unique_test_id}"
+            integration_client, project, package, content, version=f"art-{unique_test_id}"
         )
 
         response = integration_client.get(f"/api/v1/artifact/{expected_hash}/stats")
@@ -94,7 +94,7 @@ class TestArtifactStats:
         assert "size" in data
         assert "ref_count" in data
         assert "storage_savings" in data
-        assert "tags" in data
+        assert "versions" in data
         assert "projects" in data
         assert "packages" in data
 
@@ -136,8 +136,8 @@ class TestArtifactStats:
             )
 
             # Upload same content to both projects
-            upload_test_file(integration_client, proj1, "pkg", content, tag="v1")
-            upload_test_file(integration_client, proj2, "pkg", content, tag="v1")
+            upload_test_file(integration_client, proj1, "pkg", content, version="v1")
+            upload_test_file(integration_client, proj2, "pkg", content, version="v1")
 
             # Check artifact stats
             response = integration_client.get(f"/api/v1/artifact/{expected_hash}/stats")
@@ -203,7 +203,7 @@ class TestArtifactProvenance:
         assert "first_uploaded_by" in data
         assert "upload_count" in data
         assert "packages" in data
-        assert "tags" in data
+        assert "versions" in data
         assert "uploads" in data
 
     @pytest.mark.integration
@@ -214,17 +214,17 @@ class TestArtifactProvenance:
         assert response.status_code == 404
 
     @pytest.mark.integration
-    def test_artifact_history_with_tag(self, integration_client, test_package):
-        """Test artifact history includes tag information when tagged."""
+    def test_artifact_history_with_version(self, integration_client, test_package):
+        """Test artifact history includes version information when versioned."""
         project_name, package_name = test_package
 
         upload_result = upload_test_file(
             integration_client,
             project_name,
             package_name,
-            b"tagged provenance test",
-            "tagged.txt",
-            tag="v1.0.0",
+            b"versioned provenance test",
+            "versioned.txt",
+            version="v1.0.0",
         )
         artifact_id = upload_result["artifact_id"]
 
@@ -232,12 +232,12 @@ class TestArtifactProvenance:
         assert response.status_code == 200
 
         data = response.json()
-        assert len(data["tags"]) >= 1
+        assert len(data["versions"]) >= 1
 
-        tag = data["tags"][0]
-        assert "project_name" in tag
-        assert "package_name" in tag
-        assert "tag_name" in tag
+        version = data["versions"][0]
+        assert "project_name" in version
+        assert "package_name" in version
+        assert "version" in version
 
 
 class TestArtifactUploads:
@@ -306,24 +306,24 @@ class TestOrphanedArtifacts:
         assert len(response.json()) <= 5
 
     @pytest.mark.integration
-    def test_artifact_becomes_orphaned_when_tag_deleted(
+    def test_artifact_becomes_orphaned_when_version_deleted(
         self, integration_client, test_package, unique_test_id
     ):
-        """Test artifact appears in orphaned list after tag is deleted."""
+        """Test artifact appears in orphaned list after version is deleted."""
         project, package = test_package
         content = f"orphan test {unique_test_id}".encode()
         expected_hash = compute_sha256(content)
 
-        # Upload with tag
-        upload_test_file(integration_client, project, package, content, tag="temp-tag")
+        # Upload with version
+        upload_test_file(integration_client, project, package, content, version="1.0.0-temp")
 
         # Verify not in orphaned list
         response = integration_client.get("/api/v1/admin/orphaned-artifacts?limit=1000")
         orphaned_ids = [a["id"] for a in response.json()]
         assert expected_hash not in orphaned_ids
 
-        # Delete the tag
-        integration_client.delete(f"/api/v1/project/{project}/{package}/tags/temp-tag")
+        # Delete the version
+        integration_client.delete(f"/api/v1/project/{project}/{package}/versions/1.0.0-temp")
 
         # Verify now in orphaned list
         response = integration_client.get("/api/v1/admin/orphaned-artifacts?limit=1000")
@@ -356,9 +356,9 @@ class TestGarbageCollection:
         content = f"dry run test {unique_test_id}".encode()
         expected_hash = compute_sha256(content)
 
-        # Upload and delete tag to create orphan
-        upload_test_file(integration_client, project, package, content, tag="dry-run")
-        integration_client.delete(f"/api/v1/project/{project}/{package}/tags/dry-run")
+        # Upload and delete version to create orphan
+        upload_test_file(integration_client, project, package, content, version="1.0.0-dryrun")
+        integration_client.delete(f"/api/v1/project/{project}/{package}/versions/1.0.0-dryrun")
 
         # Verify artifact exists
         response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
@@ -385,7 +385,7 @@ class TestGarbageCollection:
         expected_hash = compute_sha256(content)
 
         # Upload with tag (ref_count=1)
-        upload_test_file(integration_client, project, package, content, tag="keep-this")
+        upload_test_file(integration_client, project, package, content, version="keep-this")
 
         # Verify artifact exists with ref_count=1
         response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
@@ -534,50 +534,6 @@ class TestGlobalArtifacts:
         assert response.status_code == 400
 
 
-class TestGlobalTags:
-    """Tests for global tags endpoint."""
-
-    @pytest.mark.integration
-    def test_global_tags_returns_200(self, integration_client):
-        """Test global tags endpoint returns 200."""
-        response = integration_client.get("/api/v1/tags")
-        assert response.status_code == 200
-
-        data = response.json()
-        assert "items" in data
-        assert "pagination" in data
-
-    @pytest.mark.integration
-    def test_global_tags_pagination(self, integration_client):
-        """Test global tags endpoint respects pagination."""
-        response = integration_client.get("/api/v1/tags?limit=5&page=1")
-        assert response.status_code == 200
-
-        data = response.json()
-        assert len(data["items"]) <= 5
-        assert data["pagination"]["limit"] == 5
-
-    @pytest.mark.integration
-    def test_global_tags_has_project_context(self, integration_client):
-        """Test global tags response includes project/package context."""
-        response = integration_client.get("/api/v1/tags?limit=1")
-        assert response.status_code == 200
-
-        data = response.json()
-        if len(data["items"]) > 0:
-            item = data["items"][0]
-            assert "project_name" in item
-            assert "package_name" in item
-            assert "artifact_id" in item
-
-    @pytest.mark.integration
-    def test_global_tags_search_with_wildcard(self, integration_client):
-        """Test global tags search supports wildcards."""
-        response = integration_client.get("/api/v1/tags?search=v*")
-        assert response.status_code == 200
-        # Just verify it doesn't error; results may vary
-
-
 class TestAuditLogs:
     """Tests for global audit logs endpoint."""
 

backend/tests/integration/test_concurrent_operations.py

@@ -63,7 +63,7 @@ class TestConcurrentUploads:
                     response = client.post(
                         f"/api/v1/project/{project}/{package}/upload",
                         files=files,
-                        data={"tag": f"concurrent-{idx}"},
+                        data={"version": f"concurrent-{idx}"},
                         headers={"Authorization": f"Bearer {api_key}"},
                     )
                     if response.status_code == 200:
@@ -117,7 +117,7 @@ class TestConcurrentUploads:
                     response = client.post(
                         f"/api/v1/project/{project}/{package}/upload",
                         files=files,
-                        data={"tag": f"concurrent5-{idx}"},
+                        data={"version": f"concurrent5-{idx}"},
                         headers={"Authorization": f"Bearer {api_key}"},
                     )
                     if response.status_code == 200:
@@ -171,7 +171,7 @@ class TestConcurrentUploads:
                     response = client.post(
                         f"/api/v1/project/{project}/{package}/upload",
                         files=files,
-                        data={"tag": f"concurrent10-{idx}"},
+                        data={"version": f"concurrent10-{idx}"},
                         headers={"Authorization": f"Bearer {api_key}"},
                     )
                     if response.status_code == 200:
@@ -195,19 +195,38 @@ class TestConcurrentUploads:
 
     @pytest.mark.integration
     @pytest.mark.concurrent
-    def test_concurrent_uploads_same_file_deduplication(self, integration_client, test_package):
-        """Test concurrent uploads of same file handle deduplication correctly."""
-        project, package = test_package
+    def test_concurrent_uploads_same_file_deduplication(
+        self, integration_client, test_project, unique_test_id
+    ):
+        """Test concurrent uploads of same file handle deduplication correctly.
+
+        Same content uploaded to different packages should result in:
+        - Same artifact_id (content-addressable)
+        - ref_count = number of packages (one version per package)
+        """
+        project = test_project
         api_key = get_api_key(integration_client)
         assert api_key, "Failed to create API key"
 
-        content, expected_hash = generate_content_with_hash(4096, seed=999)
         num_concurrent = 5
+        package_names = []
+
+        # Create multiple packages for concurrent uploads
+        for i in range(num_concurrent):
+            pkg_name = f"dedup-pkg-{unique_test_id}-{i}"
+            response = integration_client.post(
+                f"/api/v1/project/{project}/packages",
+                json={"name": pkg_name, "description": f"Dedup test package {i}"},
+            )
+            assert response.status_code == 200
+            package_names.append(pkg_name)
+
+        content, expected_hash = generate_content_with_hash(4096, seed=999)
 
         results = []
         errors = []
 
-        def upload_worker(idx):
+        def upload_worker(idx, package):
             try:
                 from httpx import Client
                 base_url = os.environ.get("ORCHARD_TEST_URL", "http://localhost:8080")
@@ -219,7 +238,7 @@ class TestConcurrentUploads:
                     response = client.post(
                         f"/api/v1/project/{project}/{package}/upload",
                         files=files,
-                        data={"tag": f"dedup-{idx}"},
+                        data={"version": "1.0.0"},
                         headers={"Authorization": f"Bearer {api_key}"},
                     )
                     if response.status_code == 200:
@@ -230,7 +249,10 @@ class TestConcurrentUploads:
                 errors.append(f"Worker {idx}: {str(e)}")
 
         with ThreadPoolExecutor(max_workers=num_concurrent) as executor:
-            futures = [executor.submit(upload_worker, i) for i in range(num_concurrent)]
+            futures = [
+                executor.submit(upload_worker, i, package_names[i])
+                for i in range(num_concurrent)
+            ]
             for future in as_completed(futures):
                 pass
 
@@ -242,7 +264,7 @@ class TestConcurrentUploads:
         assert len(artifact_ids) == 1
         assert expected_hash in artifact_ids
 
-        # Verify final ref_count equals number of uploads
+        # Verify final ref_count equals number of packages
         response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
         assert response.status_code == 200
         assert response.json()["ref_count"] == num_concurrent
@@ -287,7 +309,7 @@ class TestConcurrentUploads:
                     response = client.post(
                         f"/api/v1/project/{project}/{package}/upload",
                         files=files,
-                        data={"tag": "latest"},
+                        data={"version": "latest"},
                         headers={"Authorization": f"Bearer {api_key}"},
                     )
                     if response.status_code == 200:
@@ -321,7 +343,7 @@ class TestConcurrentDownloads:
         content, expected_hash = generate_content_with_hash(2048, seed=400)
 
         # Upload first
-        upload_test_file(integration_client, project, package, content, tag="download-test")
+        upload_test_file(integration_client, project, package, content, version="download-test")
 
         results = []
         errors = []
@@ -362,7 +384,7 @@ class TestConcurrentDownloads:
         project, package = test_package
         content, expected_hash = generate_content_with_hash(4096, seed=500)
 
-        upload_test_file(integration_client, project, package, content, tag="download5-test")
+        upload_test_file(integration_client, project, package, content, version="download5-test")
 
         num_downloads = 5
         results = []
@@ -403,7 +425,7 @@ class TestConcurrentDownloads:
         project, package = test_package
         content, expected_hash = generate_content_with_hash(8192, seed=600)
 
-        upload_test_file(integration_client, project, package, content, tag="download10-test")
+        upload_test_file(integration_client, project, package, content, version="download10-test")
 
         num_downloads = 10
         results = []
@@ -450,7 +472,7 @@ class TestConcurrentDownloads:
             content, expected_hash = generate_content_with_hash(1024, seed=700 + i)
             upload_test_file(
                 integration_client, project, package, content,
-                tag=f"multi-download-{i}"
+                version=f"multi-download-{i}"
             )
             uploads.append((f"multi-download-{i}", content))
 
@@ -502,7 +524,7 @@ class TestMixedConcurrentOperations:
 
         # Upload initial content
         content1, hash1 = generate_content_with_hash(10240, seed=800)  # 10KB
-        upload_test_file(integration_client, project, package, content1, tag="initial")
+        upload_test_file(integration_client, project, package, content1, version="initial")
 
         # New content for upload during download
         content2, hash2 = generate_content_with_hash(10240, seed=801)
@@ -539,7 +561,7 @@ class TestMixedConcurrentOperations:
                     response = client.post(
                         f"/api/v1/project/{project}/{package}/upload",
                         files=files,
-                        data={"tag": "during-download"},
+                        data={"version": "during-download"},
                         headers={"Authorization": f"Bearer {api_key}"},
                     )
                     if response.status_code == 200:
@@ -579,7 +601,7 @@ class TestMixedConcurrentOperations:
         existing_files = []
         for i in range(3):
             content, hash = generate_content_with_hash(2048, seed=900 + i)
-            upload_test_file(integration_client, project, package, content, tag=f"existing-{i}")
+            upload_test_file(integration_client, project, package, content, version=f"existing-{i}")
             existing_files.append((f"existing-{i}", content))
 
         # New files for uploading
@@ -619,7 +641,7 @@ class TestMixedConcurrentOperations:
                     response = client.post(
                         f"/api/v1/project/{project}/{package}/upload",
                         files=files,
-                        data={"tag": f"new-{idx}"},
+                        data={"version": f"new-{idx}"},
                         headers={"Authorization": f"Bearer {api_key}"},
                     )
                     if response.status_code == 200:
@@ -689,7 +711,7 @@ class TestMixedConcurrentOperations:
                     upload_resp = client.post(
                         f"/api/v1/project/{project}/{package}/upload",
                         files=files,
-                        data={"tag": f"pattern-{idx}"},
+                        data={"version": f"pattern-{idx}"},
                         headers={"Authorization": f"Bearer {api_key}"},
                     )
                     if upload_resp.status_code != 200:

backend/tests/integration/test_error_handling.py

@@ -68,7 +68,7 @@ class TestUploadErrorHandling:
 
         response = integration_client.post(
             f"/api/v1/project/{project}/{package}/upload",
-            data={"tag": "no-file-provided"},
+            data={"version": "no-file-provided"},
         )
         assert response.status_code == 422
 
@@ -200,7 +200,7 @@ class TestTimeoutBehavior:
 
         start_time = time.time()
         result = upload_test_file(
-            integration_client, project, package, content, tag="timeout-test"
+            integration_client, project, package, content, version="timeout-test"
         )
         elapsed = time.time() - start_time
 
@@ -219,7 +219,7 @@ class TestTimeoutBehavior:
 
         # First upload
         upload_test_file(
-            integration_client, project, package, content, tag="download-timeout-test"
+            integration_client, project, package, content, version="download-timeout-test"
         )
 
         # Then download and time it

backend/tests/integration/test_integrity_verification.py

@@ -41,7 +41,7 @@ class TestRoundTripVerification:
 
         # Upload and capture returned hash
         result = upload_test_file(
-            integration_client, project, package, content, tag="roundtrip"
+            integration_client, project, package, content, version="roundtrip"
         )
         uploaded_hash = result["artifact_id"]
 
@@ -84,7 +84,7 @@ class TestRoundTripVerification:
         expected_hash = compute_sha256(content)
 
         upload_test_file(
-            integration_client, project, package, content, tag="header-check"
+            integration_client, project, package, content, version="header-check"
         )
 
         response = integration_client.get(
@@ -102,7 +102,7 @@ class TestRoundTripVerification:
         expected_hash = compute_sha256(content)
 
         upload_test_file(
-            integration_client, project, package, content, tag="etag-check"
+            integration_client, project, package, content, version="etag-check"
         )
 
         response = integration_client.get(
@@ -186,7 +186,7 @@ class TestClientSideVerificationWorkflow:
         content = b"Client post-download verification"
 
         upload_test_file(
-            integration_client, project, package, content, tag="verify-after"
+            integration_client, project, package, content, version="verify-after"
         )
 
         response = integration_client.get(
@@ -215,7 +215,7 @@ class TestIntegritySizeVariants:
         content, expected_hash = sized_content(SIZE_1KB, seed=100)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="int-1kb"
+            integration_client, project, package, content, version="int-1kb"
         )
         assert result["artifact_id"] == expected_hash
 
@@ -234,7 +234,7 @@ class TestIntegritySizeVariants:
         content, expected_hash = sized_content(SIZE_100KB, seed=101)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="int-100kb"
+            integration_client, project, package, content, version="int-100kb"
         )
         assert result["artifact_id"] == expected_hash
 
@@ -253,7 +253,7 @@ class TestIntegritySizeVariants:
         content, expected_hash = sized_content(SIZE_1MB, seed=102)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="int-1mb"
+            integration_client, project, package, content, version="int-1mb"
         )
         assert result["artifact_id"] == expected_hash
 
@@ -273,7 +273,7 @@ class TestIntegritySizeVariants:
         content, expected_hash = sized_content(SIZE_10MB, seed=103)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="int-10mb"
+            integration_client, project, package, content, version="int-10mb"
         )
         assert result["artifact_id"] == expected_hash
 
@@ -323,7 +323,13 @@ class TestConsistencyCheck:
 
     @pytest.mark.integration
     def test_consistency_check_after_upload(self, integration_client, test_package):
-        """Test consistency check passes after valid upload."""
+        """Test consistency check runs successfully after a valid upload.
+
+        Note: We don't assert healthy=True because other tests (especially
+        corruption detection tests) may leave orphaned S3 objects behind.
+        This test validates the consistency check endpoint works and the
+        uploaded artifact is included in the check count.
+        """
         project, package = test_package
         content = b"Consistency check test content"
 
@@ -335,9 +341,10 @@ class TestConsistencyCheck:
         assert response.status_code == 200
         data = response.json()
 
-        # Verify check ran and no issues
+        # Verify check ran - at least 1 artifact was checked
         assert data["total_artifacts_checked"] >= 1
-        assert data["healthy"] is True
+        # Verify no missing S3 objects (uploaded artifact should exist)
+        assert data["missing_s3_objects"] == 0
 
     @pytest.mark.integration
     def test_consistency_check_limit_parameter(self, integration_client):
@@ -366,7 +373,7 @@ class TestDigestHeader:
         expected_hash = compute_sha256(content)
 
         upload_test_file(
-            integration_client, project, package, content, tag="digest-test"
+            integration_client, project, package, content, version="digest-test"
         )
 
         response = integration_client.get(
@@ -390,7 +397,7 @@ class TestDigestHeader:
         expected_hash = compute_sha256(content)
 
         upload_test_file(
-            integration_client, project, package, content, tag="digest-b64"
+            integration_client, project, package, content, version="digest-b64"
         )
 
         response = integration_client.get(
@@ -420,7 +427,7 @@ class TestVerificationModes:
         content = b"Pre-verification mode test"
 
         upload_test_file(
-            integration_client, project, package, content, tag="pre-verify"
+            integration_client, project, package, content, version="pre-verify"
         )
 
         response = integration_client.get(
@@ -440,7 +447,7 @@ class TestVerificationModes:
         content = b"Stream verification mode test"
 
         upload_test_file(
-            integration_client, project, package, content, tag="stream-verify"
+            integration_client, project, package, content, version="stream-verify"
         )
 
         response = integration_client.get(
@@ -477,7 +484,7 @@ class TestArtifactIntegrityEndpoint:
         expected_size = len(content)
 
         upload_test_file(
-            integration_client, project, package, content, tag="content-len"
+            integration_client, project, package, content, version="content-len"
         )
 
         response = integration_client.get(
@@ -513,7 +520,7 @@ class TestCorruptionDetection:
 
         # Upload original content
         result = upload_test_file(
-            integration_client, project, package, content, tag="corrupt-test"
+            integration_client, project, package, content, version="corrupt-test"
         )
         assert result["artifact_id"] == expected_hash
 
@@ -555,7 +562,7 @@ class TestCorruptionDetection:
         expected_hash = compute_sha256(content)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="bitflip-test"
+            integration_client, project, package, content, version="bitflip-test"
         )
         assert result["artifact_id"] == expected_hash
 
@@ -592,7 +599,7 @@ class TestCorruptionDetection:
         expected_hash = compute_sha256(content)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="truncate-test"
+            integration_client, project, package, content, version="truncate-test"
         )
         assert result["artifact_id"] == expected_hash
 
@@ -627,7 +634,7 @@ class TestCorruptionDetection:
         expected_hash = compute_sha256(content)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="append-test"
+            integration_client, project, package, content, version="append-test"
         )
         assert result["artifact_id"] == expected_hash
 
@@ -670,7 +677,7 @@ class TestCorruptionDetection:
         expected_hash = compute_sha256(content)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="client-detect"
+            integration_client, project, package, content, version="client-detect"
         )
 
         # Corrupt the S3 object
@@ -713,7 +720,7 @@ class TestCorruptionDetection:
         expected_hash = compute_sha256(content)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="size-mismatch"
+            integration_client, project, package, content, version="size-mismatch"
         )
 
         # Modify S3 object to have different size
@@ -747,7 +754,7 @@ class TestCorruptionDetection:
         expected_hash = compute_sha256(content)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="missing-s3"
+            integration_client, project, package, content, version="missing-s3"
         )
 
         # Delete the S3 object

backend/tests/integration/test_large_uploads.py

@@ -41,7 +41,7 @@ class TestUploadMetrics:
         content = b"duration test content"
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="duration-test"
+            integration_client, project, package, content, version="duration-test"
         )
 
         assert "duration_ms" in result
@@ -55,7 +55,7 @@ class TestUploadMetrics:
         content = b"throughput test content"
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="throughput-test"
+            integration_client, project, package, content, version="throughput-test"
         )
 
         assert "throughput_mbps" in result
@@ -72,7 +72,7 @@ class TestUploadMetrics:
 
         start = time.time()
         result = upload_test_file(
-            integration_client, project, package, content, tag="duration-check"
+            integration_client, project, package, content, version="duration-check"
         )
         actual_duration = (time.time() - start) * 1000  # ms
 
@@ -92,7 +92,7 @@ class TestLargeFileUploads:
         content, expected_hash = sized_content(SIZE_10MB, seed=200)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="large-10mb"
+            integration_client, project, package, content, version="large-10mb"
         )
 
         assert result["artifact_id"] == expected_hash
@@ -109,7 +109,7 @@ class TestLargeFileUploads:
         content, expected_hash = sized_content(SIZE_100MB, seed=300)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="large-100mb"
+            integration_client, project, package, content, version="large-100mb"
         )
 
         assert result["artifact_id"] == expected_hash
@@ -126,7 +126,7 @@ class TestLargeFileUploads:
         content, expected_hash = sized_content(SIZE_1GB, seed=400)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="large-1gb"
+            integration_client, project, package, content, version="large-1gb"
         )
 
         assert result["artifact_id"] == expected_hash
@@ -147,14 +147,14 @@ class TestLargeFileUploads:
 
         # First upload
         result1 = upload_test_file(
-            integration_client, project, package, content, tag=f"dedup-{unique_test_id}-1"
+            integration_client, project, package, content, version=f"dedup-{unique_test_id}-1"
         )
         # Note: may be True if previous test uploaded same content
         first_dedupe = result1["deduplicated"]
 
         # Second upload of same content
         result2 = upload_test_file(
-            integration_client, project, package, content, tag=f"dedup-{unique_test_id}-2"
+            integration_client, project, package, content, version=f"dedup-{unique_test_id}-2"
         )
         assert result2["artifact_id"] == expected_hash
         # Second upload MUST be deduplicated
@@ -277,7 +277,7 @@ class TestUploadSizeLimits:
         content = b"X"
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="min-size"
+            integration_client, project, package, content, version="min-size"
         )
 
         assert result["size"] == 1
@@ -289,7 +289,7 @@ class TestUploadSizeLimits:
         content = b"content length verification test"
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="content-length-test"
+            integration_client, project, package, content, version="content-length-test"
         )
 
         # Size in response should match actual content length
@@ -336,7 +336,7 @@ class TestUploadErrorHandling:
 
         response = integration_client.post(
             f"/api/v1/project/{project}/{package}/upload",
-            data={"tag": "no-file"},
+            data={"version": "no-file"},
         )
 
         assert response.status_code == 422
@@ -459,7 +459,7 @@ class TestUploadTimeout:
 
         # httpx client should handle this quickly
         result = upload_test_file(
-            integration_client, project, package, content, tag="timeout-small"
+            integration_client, project, package, content, version="timeout-small"
         )
 
         assert result["artifact_id"] is not None
@@ -474,7 +474,7 @@ class TestUploadTimeout:
 
         start = time.time()
         result = upload_test_file(
-            integration_client, project, package, content, tag="timeout-check"
+            integration_client, project, package, content, version="timeout-check"
         )
         duration = time.time() - start
 
@@ -525,7 +525,7 @@ class TestConcurrentUploads:
                     response = client.post(
                         f"/api/v1/project/{project}/{package}/upload",
                         files=files,
-                        data={"tag": f"concurrent-diff-{idx}"},
+                        data={"version": f"concurrent-diff-{idx}"},
                         headers={"Authorization": f"Bearer {api_key}"},
                     )
                     if response.status_code == 200:

backend/tests/integration/test_packages_api.py

@@ -175,7 +175,7 @@ class TestPackageStats:
         assert "package_id" in data
         assert "package_name" in data
         assert "project_name" in data
-        assert "tag_count" in data
+        assert "version_count" in data
         assert "artifact_count" in data
         assert "total_size_bytes" in data
         assert "upload_count" in data
@@ -234,7 +234,11 @@ class TestPackageCascadeDelete:
     def test_ref_count_decrements_on_package_delete(
         self, integration_client, unique_test_id
     ):
-        """Test ref_count decrements for all tags when package is deleted."""
+        """Test ref_count decrements when package is deleted.
+
+        Each package can only have one version per artifact (same content = same version).
+        This test verifies that deleting a package decrements the artifact's ref_count.
+        """
         project_name = f"cascade-pkg-{unique_test_id}"
         package_name = f"test-pkg-{unique_test_id}"
 
@@ -256,23 +260,17 @@ class TestPackageCascadeDelete:
         )
         assert response.status_code == 200
 
-        # Upload content with multiple tags
+        # Upload content with version
         content = f"cascade delete test {unique_test_id}".encode()
         expected_hash = compute_sha256(content)
 
         upload_test_file(
-            integration_client, project_name, package_name, content, tag="v1"
-        )
-        upload_test_file(
-            integration_client, project_name, package_name, content, tag="v2"
-        )
-        upload_test_file(
-            integration_client, project_name, package_name, content, tag="v3"
+            integration_client, project_name, package_name, content, version="1.0.0"
         )
 
-        # Verify ref_count is 3
+        # Verify ref_count is 1
         response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
-        assert response.json()["ref_count"] == 3
+        assert response.json()["ref_count"] == 1
 
         # Delete the package
         delete_response = integration_client.delete(

backend/tests/integration/test_projects_api.py

@@ -128,7 +128,9 @@ class TestProjectListingFilters:
         assert response.status_code == 200
 
         data = response.json()
-        names = [p["name"] for p in data["items"]]
+        # Filter out system projects (names starting with "_") as they may have
+        # collation-specific sort behavior and aren't part of the test data
+        names = [p["name"] for p in data["items"] if not p["name"].startswith("_")]
         assert names == sorted(names)
 
 
@@ -147,7 +149,7 @@ class TestProjectStats:
         assert "project_id" in data
         assert "project_name" in data
         assert "package_count" in data
-        assert "tag_count" in data
+        assert "version_count" in data
         assert "artifact_count" in data
         assert "total_size_bytes" in data
         assert "upload_count" in data
@@ -227,7 +229,11 @@ class TestProjectCascadeDelete:
     def test_ref_count_decrements_on_project_delete(
         self, integration_client, unique_test_id
     ):
-        """Test ref_count decrements for all tags when project is deleted."""
+        """Test ref_count decrements for all versions when project is deleted.
+
+        Each package can only have one version per artifact (same content = same version).
+        With 2 packages, ref_count should be 2, and go to 0 when project is deleted.
+        """
         project_name = f"cascade-proj-{unique_test_id}"
         package1_name = f"pkg1-{unique_test_id}"
         package2_name = f"pkg2-{unique_test_id}"
@@ -251,26 +257,20 @@ class TestProjectCascadeDelete:
             )
             assert response.status_code == 200
 
-        # Upload same content with tags in both packages
+        # Upload same content to both packages
         content = f"project cascade test {unique_test_id}".encode()
         expected_hash = compute_sha256(content)
 
         upload_test_file(
-            integration_client, project_name, package1_name, content, tag="v1"
+            integration_client, project_name, package1_name, content, version="1.0.0"
         )
         upload_test_file(
-            integration_client, project_name, package1_name, content, tag="v2"
-        )
-        upload_test_file(
-            integration_client, project_name, package2_name, content, tag="latest"
-        )
-        upload_test_file(
-            integration_client, project_name, package2_name, content, tag="stable"
+            integration_client, project_name, package2_name, content, version="1.0.0"
         )
 
-        # Verify ref_count is 4 (2 tags in each of 2 packages)
+        # Verify ref_count is 2 (1 version in each of 2 packages)
         response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
-        assert response.json()["ref_count"] == 4
+        assert response.json()["ref_count"] == 2
 
         # Delete the project
         delete_response = integration_client.delete(f"/api/v1/projects/{project_name}")

backend/tests/integration/test_pypi_proxy.py

@@ -0,0 +1,137 @@
+"""Integration tests for PyPI transparent proxy."""
+
+import os
+import pytest
+import httpx
+
+
+def get_base_url():
+    """Get the base URL for the Orchard server from environment."""
+    return os.environ.get("ORCHARD_TEST_URL", "http://localhost:8080")
+
+
+class TestPyPIProxyEndpoints:
+    """Tests for PyPI proxy endpoints.
+
+    These endpoints are public (no auth required) since pip needs to use them.
+    """
+
+    @pytest.mark.integration
+    def test_pypi_simple_index(self):
+        """Test that /pypi/simple/ returns HTML response."""
+        with httpx.Client(base_url=get_base_url(), timeout=30.0) as client:
+            response = client.get("/pypi/simple/")
+            # Returns 200 if sources configured, 503 if not
+            assert response.status_code in (200, 503)
+            if response.status_code == 200:
+                assert "text/html" in response.headers.get("content-type", "")
+            else:
+                assert "No PyPI upstream sources configured" in response.json()["detail"]
+
+    @pytest.mark.integration
+    def test_pypi_package_endpoint(self):
+        """Test that /pypi/simple/{package}/ returns appropriate response."""
+        with httpx.Client(base_url=get_base_url(), timeout=30.0) as client:
+            response = client.get("/pypi/simple/requests/")
+            # Returns 200 if sources configured and package found,
+            # 404 if package not found, 503 if no sources
+            assert response.status_code in (200, 404, 503)
+            if response.status_code == 200:
+                assert "text/html" in response.headers.get("content-type", "")
+            elif response.status_code == 404:
+                assert "not found" in response.json()["detail"].lower()
+            else:  # 503
+                assert "No PyPI upstream sources configured" in response.json()["detail"]
+
+    @pytest.mark.integration
+    def test_pypi_download_missing_upstream_param(self):
+        """Test that /pypi/simple/{package}/{filename} requires upstream param."""
+        with httpx.Client(base_url=get_base_url(), timeout=30.0) as client:
+            response = client.get("/pypi/simple/requests/requests-2.31.0.tar.gz")
+            assert response.status_code == 400
+            assert "upstream" in response.json()["detail"].lower()
+
+
+class TestPyPILinkRewriting:
+    """Tests for URL rewriting in PyPI proxy responses."""
+
+    def test_rewrite_package_links(self):
+        """Test that download links are rewritten to go through proxy."""
+        from app.pypi_proxy import _rewrite_package_links
+
+        html = '''
+        <html>
+        <body>
+        <a href="https://files.pythonhosted.org/packages/ab/cd/requests-2.31.0.tar.gz#sha256=abc123">requests-2.31.0.tar.gz</a>
+        <a href="https://files.pythonhosted.org/packages/ef/gh/requests-2.31.0-py3-none-any.whl#sha256=def456">requests-2.31.0-py3-none-any.whl</a>
+        </body>
+        </html>
+        '''
+
+        # upstream_base_url is used to resolve relative URLs (not needed here since URLs are absolute)
+        result = _rewrite_package_links(
+            html,
+            "http://localhost:8080",
+            "requests",
+            "https://pypi.org/simple/requests/"
+        )
+
+        # Links should be rewritten to go through our proxy
+        assert "/pypi/simple/requests/requests-2.31.0.tar.gz?upstream=" in result
+        assert "/pypi/simple/requests/requests-2.31.0-py3-none-any.whl?upstream=" in result
+        # Original URLs should be encoded in upstream param
+        assert "files.pythonhosted.org" in result
+        # Hash fragments should be preserved
+        assert "#sha256=abc123" in result
+        assert "#sha256=def456" in result
+
+    def test_rewrite_relative_links(self):
+        """Test that relative URLs are resolved to absolute URLs."""
+        from app.pypi_proxy import _rewrite_package_links
+
+        # Artifactory-style relative URLs
+        html = '''
+        <html>
+        <body>
+        <a href="../../packages/ab/cd/requests-2.31.0.tar.gz#sha256=abc123">requests-2.31.0.tar.gz</a>
+        </body>
+        </html>
+        '''
+
+        result = _rewrite_package_links(
+            html,
+            "https://orchard.example.com",
+            "requests",
+            "https://artifactory.example.com/api/pypi/pypi-remote/simple/requests/"
+        )
+
+        # The relative URL should be resolved to absolute
+        # ../../packages/ab/cd/... from /api/pypi/pypi-remote/simple/requests/ resolves to /api/pypi/pypi-remote/packages/ab/cd/...
+        assert "upstream=https%3A%2F%2Fartifactory.example.com%2Fapi%2Fpypi%2Fpypi-remote%2Fpackages" in result
+        # Hash fragment should be preserved
+        assert "#sha256=abc123" in result
+
+
+class TestPyPIPackageNormalization:
+    """Tests for PyPI package name normalization."""
+
+    @pytest.mark.integration
+    def test_package_name_normalized(self):
+        """Test that package names are normalized per PEP 503.
+
+        Different capitalizations/separators should all be valid paths.
+        The endpoint normalizes to lowercase with hyphens before lookup.
+        """
+        with httpx.Client(base_url=get_base_url(), timeout=30.0) as client:
+            # Test various name formats - all should be valid endpoint paths
+            for package_name in ["Requests", "some_package", "some-package"]:
+                response = client.get(f"/pypi/simple/{package_name}/")
+                # 200 = found, 404 = not found, 503 = no sources configured
+                assert response.status_code in (200, 404, 503), \
+                    f"Unexpected status {response.status_code} for {package_name}"
+
+                # Verify response is appropriate for the status code
+                if response.status_code == 200:
+                    assert "text/html" in response.headers.get("content-type", "")
+                elif response.status_code == 503:
+                    assert "No PyPI upstream sources configured" in response.json()["detail"]

backend/tests/integration/test_size_boundary.py

@@ -48,7 +48,7 @@ class TestSmallFileSizes:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="1byte.bin", tag="1byte"
+            filename="1byte.bin", version="1byte"
         )
         assert result["artifact_id"] == expected_hash
         assert result["size"] == SIZE_1B
@@ -70,7 +70,7 @@ class TestSmallFileSizes:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="1kb.bin", tag="1kb"
+            filename="1kb.bin", version="1kb"
         )
         assert result["artifact_id"] == expected_hash
         assert result["size"] == SIZE_1KB
@@ -90,7 +90,7 @@ class TestSmallFileSizes:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="10kb.bin", tag="10kb"
+            filename="10kb.bin", version="10kb"
         )
         assert result["artifact_id"] == expected_hash
         assert result["size"] == SIZE_10KB
@@ -110,7 +110,7 @@ class TestSmallFileSizes:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="100kb.bin", tag="100kb"
+            filename="100kb.bin", version="100kb"
         )
         assert result["artifact_id"] == expected_hash
         assert result["size"] == SIZE_100KB
@@ -134,7 +134,7 @@ class TestMediumFileSizes:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="1mb.bin", tag="1mb"
+            filename="1mb.bin", version="1mb"
         )
         assert result["artifact_id"] == expected_hash
         assert result["size"] == SIZE_1MB
@@ -155,7 +155,7 @@ class TestMediumFileSizes:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="5mb.bin", tag="5mb"
+            filename="5mb.bin", version="5mb"
         )
         assert result["artifact_id"] == expected_hash
         assert result["size"] == SIZE_5MB
@@ -177,7 +177,7 @@ class TestMediumFileSizes:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="10mb.bin", tag="10mb"
+            filename="10mb.bin", version="10mb"
         )
         assert result["artifact_id"] == expected_hash
         assert result["size"] == SIZE_10MB
@@ -200,7 +200,7 @@ class TestMediumFileSizes:
         start_time = time.time()
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="50mb.bin", tag="50mb"
+            filename="50mb.bin", version="50mb"
         )
         upload_time = time.time() - start_time
 
@@ -240,7 +240,7 @@ class TestLargeFileSizes:
         start_time = time.time()
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="100mb.bin", tag="100mb"
+            filename="100mb.bin", version="100mb"
         )
         upload_time = time.time() - start_time
 
@@ -271,7 +271,7 @@ class TestLargeFileSizes:
         start_time = time.time()
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="250mb.bin", tag="250mb"
+            filename="250mb.bin", version="250mb"
         )
         upload_time = time.time() - start_time
 
@@ -302,7 +302,7 @@ class TestLargeFileSizes:
         start_time = time.time()
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="500mb.bin", tag="500mb"
+            filename="500mb.bin", version="500mb"
         )
         upload_time = time.time() - start_time
 
@@ -336,7 +336,7 @@ class TestLargeFileSizes:
         start_time = time.time()
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="1gb.bin", tag="1gb"
+            filename="1gb.bin", version="1gb"
         )
         upload_time = time.time() - start_time
 
@@ -368,7 +368,7 @@ class TestChunkBoundaries:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="chunk.bin", tag="chunk-exact"
+            filename="chunk.bin", version="chunk-exact"
         )
         assert result["artifact_id"] == expected_hash
         assert result["size"] == CHUNK_SIZE
@@ -389,7 +389,7 @@ class TestChunkBoundaries:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="chunk_plus.bin", tag="chunk-plus"
+            filename="chunk_plus.bin", version="chunk-plus"
         )
         assert result["artifact_id"] == expected_hash
         assert result["size"] == size
@@ -410,7 +410,7 @@ class TestChunkBoundaries:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="chunk_minus.bin", tag="chunk-minus"
+            filename="chunk_minus.bin", version="chunk-minus"
         )
         assert result["artifact_id"] == expected_hash
         assert result["size"] == size
@@ -431,7 +431,7 @@ class TestChunkBoundaries:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="multi_chunk.bin", tag="multi-chunk"
+            filename="multi_chunk.bin", version="multi-chunk"
         )
         assert result["artifact_id"] == expected_hash
         assert result["size"] == size
@@ -457,7 +457,7 @@ class TestDataIntegrity:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="binary.bin", tag="binary"
+            filename="binary.bin", version="binary"
         )
         assert result["artifact_id"] == expected_hash
 
@@ -477,7 +477,7 @@ class TestDataIntegrity:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="text.txt", tag="text"
+            filename="text.txt", version="text"
         )
         assert result["artifact_id"] == expected_hash
 
@@ -498,7 +498,7 @@ class TestDataIntegrity:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="nulls.bin", tag="nulls"
+            filename="nulls.bin", version="nulls"
         )
         assert result["artifact_id"] == expected_hash
 
@@ -519,7 +519,7 @@ class TestDataIntegrity:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="文件名.txt", tag="unicode-name"
+            filename="文件名.txt", version="unicode-name"
         )
         assert result["artifact_id"] == expected_hash
         assert result["original_name"] == "文件名.txt"
@@ -543,7 +543,7 @@ class TestDataIntegrity:
 
         result = upload_test_file(
             integration_client, project, package, content,
-            filename="data.gz", tag="compressed"
+            filename="data.gz", version="compressed"
         )
         assert result["artifact_id"] == expected_hash
 
@@ -568,7 +568,7 @@ class TestDataIntegrity:
 
             result = upload_test_file(
                 integration_client, project, package, content,
-                filename=f"hash_test_{size}.bin", tag=f"hash-{size}"
+                filename=f"hash_test_{size}.bin", version=f"hash-{size}"
             )
 
             # Verify artifact_id matches expected hash

backend/tests/integration/test_streaming_download.py

@@ -32,7 +32,7 @@ class TestRangeRequests:
         """Test range request for first N bytes."""
         project, package = test_package
         content = b"0123456789" * 100  # 1000 bytes
-        upload_test_file(integration_client, project, package, content, tag="range-test")
+        upload_test_file(integration_client, project, package, content, version="range-test")
 
         # Request first 10 bytes
         response = integration_client.get(
@@ -50,7 +50,7 @@ class TestRangeRequests:
         """Test range request for bytes in the middle."""
         project, package = test_package
         content = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ"
-        upload_test_file(integration_client, project, package, content, tag="range-mid")
+        upload_test_file(integration_client, project, package, content, version="range-mid")
 
         # Request bytes 10-19 (KLMNOPQRST)
         response = integration_client.get(
@@ -66,7 +66,7 @@ class TestRangeRequests:
         """Test range request for last N bytes (suffix range)."""
         project, package = test_package
         content = b"0123456789ABCDEF"  # 16 bytes
-        upload_test_file(integration_client, project, package, content, tag="range-suffix")
+        upload_test_file(integration_client, project, package, content, version="range-suffix")
 
         # Request last 4 bytes
         response = integration_client.get(
@@ -82,7 +82,7 @@ class TestRangeRequests:
         """Test range request from offset to end."""
         project, package = test_package
         content = b"0123456789"
-        upload_test_file(integration_client, project, package, content, tag="range-open")
+        upload_test_file(integration_client, project, package, content, version="range-open")
 
         # Request from byte 5 to end
         response = integration_client.get(
@@ -100,7 +100,7 @@ class TestRangeRequests:
         """Test that range requests include Accept-Ranges header."""
         project, package = test_package
         content = b"test content"
-        upload_test_file(integration_client, project, package, content, tag="accept-ranges")
+        upload_test_file(integration_client, project, package, content, version="accept-ranges")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/accept-ranges",
@@ -117,7 +117,7 @@ class TestRangeRequests:
         """Test that full downloads advertise range support."""
         project, package = test_package
         content = b"test content"
-        upload_test_file(integration_client, project, package, content, tag="full-accept")
+        upload_test_file(integration_client, project, package, content, version="full-accept")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/full-accept",
@@ -136,7 +136,7 @@ class TestConditionalRequests:
         project, package = test_package
         content = b"conditional request test content"
         expected_hash = compute_sha256(content)
-        upload_test_file(integration_client, project, package, content, tag="cond-etag")
+        upload_test_file(integration_client, project, package, content, version="cond-etag")
 
         # Request with matching ETag
         response = integration_client.get(
@@ -153,7 +153,7 @@ class TestConditionalRequests:
         project, package = test_package
         content = b"etag no quotes test"
         expected_hash = compute_sha256(content)
-        upload_test_file(integration_client, project, package, content, tag="cond-noquote")
+        upload_test_file(integration_client, project, package, content, version="cond-noquote")
 
         # Request with ETag without quotes
         response = integration_client.get(
@@ -168,7 +168,7 @@ class TestConditionalRequests:
         """Test If-None-Match with non-matching ETag returns 200."""
         project, package = test_package
         content = b"etag mismatch test"
-        upload_test_file(integration_client, project, package, content, tag="cond-mismatch")
+        upload_test_file(integration_client, project, package, content, version="cond-mismatch")
 
         # Request with different ETag
         response = integration_client.get(
@@ -184,7 +184,7 @@ class TestConditionalRequests:
         """Test If-Modified-Since with future date returns 304."""
         project, package = test_package
         content = b"modified since test"
-        upload_test_file(integration_client, project, package, content, tag="cond-modified")
+        upload_test_file(integration_client, project, package, content, version="cond-modified")
 
         # Request with future date (artifact was definitely created before this)
         future_date = formatdate(time.time() + 86400, usegmt=True)  # Tomorrow
@@ -202,7 +202,7 @@ class TestConditionalRequests:
         """Test If-Modified-Since with old date returns 200."""
         project, package = test_package
         content = b"old date test"
-        upload_test_file(integration_client, project, package, content, tag="cond-old")
+        upload_test_file(integration_client, project, package, content, version="cond-old")
 
         # Request with old date (2020-01-01)
         old_date = "Wed, 01 Jan 2020 00:00:00 GMT"
@@ -220,7 +220,7 @@ class TestConditionalRequests:
         project, package = test_package
         content = b"304 etag test"
         expected_hash = compute_sha256(content)
-        upload_test_file(integration_client, project, package, content, tag="304-etag")
+        upload_test_file(integration_client, project, package, content, version="304-etag")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/304-etag",
@@ -236,7 +236,7 @@ class TestConditionalRequests:
         project, package = test_package
         content = b"304 cache test"
         expected_hash = compute_sha256(content)
-        upload_test_file(integration_client, project, package, content, tag="304-cache")
+        upload_test_file(integration_client, project, package, content, version="304-cache")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/304-cache",
@@ -255,7 +255,7 @@ class TestCachingHeaders:
         """Test download response includes Cache-Control header."""
         project, package = test_package
         content = b"cache control test"
-        upload_test_file(integration_client, project, package, content, tag="cache-ctl")
+        upload_test_file(integration_client, project, package, content, version="cache-ctl")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/cache-ctl",
@@ -272,7 +272,7 @@ class TestCachingHeaders:
         """Test download response includes Last-Modified header."""
         project, package = test_package
         content = b"last modified test"
-        upload_test_file(integration_client, project, package, content, tag="last-mod")
+        upload_test_file(integration_client, project, package, content, version="last-mod")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/last-mod",
@@ -290,7 +290,7 @@ class TestCachingHeaders:
         project, package = test_package
         content = b"etag header test"
         expected_hash = compute_sha256(content)
-        upload_test_file(integration_client, project, package, content, tag="etag-hdr")
+        upload_test_file(integration_client, project, package, content, version="etag-hdr")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/etag-hdr",
@@ -308,7 +308,7 @@ class TestDownloadResume:
         """Test resuming download from where it left off."""
         project, package = test_package
         content = b"ABCDEFGHIJ" * 100  # 1000 bytes
-        upload_test_file(integration_client, project, package, content, tag="resume-test")
+        upload_test_file(integration_client, project, package, content, version="resume-test")
 
         # Simulate partial download (first 500 bytes)
         response1 = integration_client.get(
@@ -340,7 +340,7 @@ class TestDownloadResume:
         project, package = test_package
         content = b"resume etag verification test content"
         expected_hash = compute_sha256(content)
-        upload_test_file(integration_client, project, package, content, tag="resume-etag")
+        upload_test_file(integration_client, project, package, content, version="resume-etag")
 
         # Get ETag from first request
         response1 = integration_client.get(
@@ -373,7 +373,7 @@ class TestLargeFileStreaming:
         project, package = test_package
         content, expected_hash = sized_content(SIZE_1MB, seed=500)
 
-        upload_test_file(integration_client, project, package, content, tag="stream-1mb")
+        upload_test_file(integration_client, project, package, content, version="stream-1mb")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/stream-1mb",
@@ -391,7 +391,7 @@ class TestLargeFileStreaming:
         project, package = test_package
         content, expected_hash = sized_content(SIZE_100KB, seed=501)
 
-        upload_test_file(integration_client, project, package, content, tag="stream-hdr")
+        upload_test_file(integration_client, project, package, content, version="stream-hdr")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/stream-hdr",
@@ -410,7 +410,7 @@ class TestLargeFileStreaming:
         project, package = test_package
         content, _ = sized_content(SIZE_100KB, seed=502)
 
-        upload_test_file(integration_client, project, package, content, tag="range-large")
+        upload_test_file(integration_client, project, package, content, version="range-large")
 
         # Request a slice from the middle
         start = 50000
@@ -433,7 +433,7 @@ class TestDownloadModes:
         """Test proxy mode streams content through backend."""
         project, package = test_package
         content = b"proxy mode test content"
-        upload_test_file(integration_client, project, package, content, tag="mode-proxy")
+        upload_test_file(integration_client, project, package, content, version="mode-proxy")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/mode-proxy",
@@ -447,7 +447,7 @@ class TestDownloadModes:
         """Test presigned mode returns JSON with URL."""
         project, package = test_package
         content = b"presigned mode test"
-        upload_test_file(integration_client, project, package, content, tag="mode-presign")
+        upload_test_file(integration_client, project, package, content, version="mode-presign")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/mode-presign",
@@ -464,7 +464,7 @@ class TestDownloadModes:
         """Test redirect mode returns 302 to presigned URL."""
         project, package = test_package
         content = b"redirect mode test"
-        upload_test_file(integration_client, project, package, content, tag="mode-redir")
+        upload_test_file(integration_client, project, package, content, version="mode-redir")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/mode-redir",
@@ -484,7 +484,7 @@ class TestIntegrityDuringStreaming:
         project, package = test_package
         content = b"integrity check content"
         expected_hash = compute_sha256(content)
-        upload_test_file(integration_client, project, package, content, tag="integrity")
+        upload_test_file(integration_client, project, package, content, version="integrity")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/integrity",
@@ -505,7 +505,7 @@ class TestIntegrityDuringStreaming:
         project, package = test_package
         content = b"etag integrity test"
         expected_hash = compute_sha256(content)
-        upload_test_file(integration_client, project, package, content, tag="etag-int")
+        upload_test_file(integration_client, project, package, content, version="etag-int")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/etag-int",
@@ -524,7 +524,7 @@ class TestIntegrityDuringStreaming:
         """Test Digest header is present in RFC 3230 format."""
         project, package = test_package
         content = b"digest header test"
-        upload_test_file(integration_client, project, package, content, tag="digest")
+        upload_test_file(integration_client, project, package, content, version="digest")
 
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/digest",

backend/tests/integration/test_tags_api.py

@@ -1,403 +0,0 @@
-"""
-Integration tests for tag API endpoints.
-
-Tests cover:
-- Tag CRUD operations
-- Tag listing with pagination and search
-- Tag history tracking
-- ref_count behavior with tag operations
-"""
-
-import pytest
-from tests.factories import compute_sha256, upload_test_file
-
-
-class TestTagCRUD:
-    """Tests for tag create, read, delete operations."""
-
-    @pytest.mark.integration
-    def test_create_tag_via_upload(self, integration_client, test_package):
-        """Test creating a tag via upload endpoint."""
-        project_name, package_name = test_package
-
-        result = upload_test_file(
-            integration_client,
-            project_name,
-            package_name,
-            b"tag create test",
-            tag="v1.0.0",
-        )
-
-        assert result["tag"] == "v1.0.0"
-        assert result["artifact_id"]
-
-    @pytest.mark.integration
-    def test_create_tag_via_post(
-        self, integration_client, test_package, unique_test_id
-    ):
-        """Test creating a tag via POST /tags endpoint."""
-        project_name, package_name = test_package
-
-        # First upload an artifact
-        result = upload_test_file(
-            integration_client,
-            project_name,
-            package_name,
-            b"artifact for tag",
-        )
-        artifact_id = result["artifact_id"]
-
-        # Create tag via POST
-        tag_name = f"post-tag-{unique_test_id}"
-        response = integration_client.post(
-            f"/api/v1/project/{project_name}/{package_name}/tags",
-            json={"name": tag_name, "artifact_id": artifact_id},
-        )
-        assert response.status_code == 200
-
-        data = response.json()
-        assert data["name"] == tag_name
-        assert data["artifact_id"] == artifact_id
-
-    @pytest.mark.integration
-    def test_get_tag(self, integration_client, test_package):
-        """Test getting a tag by name."""
-        project_name, package_name = test_package
-
-        upload_test_file(
-            integration_client,
-            project_name,
-            package_name,
-            b"get tag test",
-            tag="get-tag",
-        )
-
-        response = integration_client.get(
-            f"/api/v1/project/{project_name}/{package_name}/tags/get-tag"
-        )
-        assert response.status_code == 200
-
-        data = response.json()
-        assert data["name"] == "get-tag"
-        assert "artifact_id" in data
-        assert "artifact_size" in data
-        assert "artifact_content_type" in data
-
-    @pytest.mark.integration
-    def test_list_tags(self, integration_client, test_package):
-        """Test listing tags for a package."""
-        project_name, package_name = test_package
-
-        # Create some tags
-        upload_test_file(
-            integration_client,
-            project_name,
-            package_name,
-            b"list tags test",
-            tag="list-v1",
-        )
-
-        response = integration_client.get(
-            f"/api/v1/project/{project_name}/{package_name}/tags"
-        )
-        assert response.status_code == 200
-
-        data = response.json()
-        assert "items" in data
-        assert "pagination" in data
-
-        tag_names = [t["name"] for t in data["items"]]
-        assert "list-v1" in tag_names
-
-    @pytest.mark.integration
-    def test_delete_tag(self, integration_client, test_package):
-        """Test deleting a tag."""
-        project_name, package_name = test_package
-
-        upload_test_file(
-            integration_client,
-            project_name,
-            package_name,
-            b"delete tag test",
-            tag="to-delete",
-        )
-
-        # Delete tag
-        response = integration_client.delete(
-            f"/api/v1/project/{project_name}/{package_name}/tags/to-delete"
-        )
-        assert response.status_code == 204
-
-        # Verify deleted
-        response = integration_client.get(
-            f"/api/v1/project/{project_name}/{package_name}/tags/to-delete"
-        )
-        assert response.status_code == 404
-
-
-class TestTagListingFilters:
-    """Tests for tag listing with filters and search."""
-
-    @pytest.mark.integration
-    def test_tags_pagination(self, integration_client, test_package):
-        """Test tag listing respects pagination."""
-        project_name, package_name = test_package
-
-        response = integration_client.get(
-            f"/api/v1/project/{project_name}/{package_name}/tags?limit=5"
-        )
-        assert response.status_code == 200
-
-        data = response.json()
-        assert len(data["items"]) <= 5
-        assert data["pagination"]["limit"] == 5
-
-    @pytest.mark.integration
-    def test_tags_search(self, integration_client, test_package, unique_test_id):
-        """Test tag search by name."""
-        project_name, package_name = test_package
-
-        tag_name = f"searchable-{unique_test_id}"
-        upload_test_file(
-            integration_client,
-            project_name,
-            package_name,
-            b"search test",
-            tag=tag_name,
-        )
-
-        response = integration_client.get(
-            f"/api/v1/project/{project_name}/{package_name}/tags?search=searchable"
-        )
-        assert response.status_code == 200
-
-        data = response.json()
-        tag_names = [t["name"] for t in data["items"]]
-        assert tag_name in tag_names
-
-
-class TestTagHistory:
-    """Tests for tag history tracking."""
-
-    @pytest.mark.integration
-    def test_tag_history_on_create(self, integration_client, test_package):
-        """Test tag history is created when tag is created."""
-        project_name, package_name = test_package
-
-        upload_test_file(
-            integration_client,
-            project_name,
-            package_name,
-            b"history create test",
-            tag="history-create",
-        )
-
-        response = integration_client.get(
-            f"/api/v1/project/{project_name}/{package_name}/tags/history-create/history"
-        )
-        assert response.status_code == 200
-
-        data = response.json()
-        assert len(data) >= 1
-
-    @pytest.mark.integration
-    def test_tag_history_on_update(
-        self, integration_client, test_package, unique_test_id
-    ):
-        """Test tag history is created when tag is updated."""
-        project_name, package_name = test_package
-
-        tag_name = f"history-update-{unique_test_id}"
-
-        # Create tag with first artifact
-        upload_test_file(
-            integration_client,
-            project_name,
-            package_name,
-            b"first content",
-            tag=tag_name,
-        )
-
-        # Update tag with second artifact
-        upload_test_file(
-            integration_client,
-            project_name,
-            package_name,
-            b"second content",
-            tag=tag_name,
-        )
-
-        response = integration_client.get(
-            f"/api/v1/project/{project_name}/{package_name}/tags/{tag_name}/history"
-        )
-        assert response.status_code == 200
-
-        data = response.json()
-        # Should have at least 2 history entries (create + update)
-        assert len(data) >= 2
-
-
-class TestTagRefCount:
-    """Tests for ref_count behavior with tag operations."""
-
-    @pytest.mark.integration
-    def test_ref_count_decrements_on_tag_delete(self, integration_client, test_package):
-        """Test ref_count decrements when a tag is deleted."""
-        project_name, package_name = test_package
-        content = b"ref count delete test"
-        expected_hash = compute_sha256(content)
-
-        # Upload with two tags
-        upload_test_file(
-            integration_client, project_name, package_name, content, tag="rc-v1"
-        )
-        upload_test_file(
-            integration_client, project_name, package_name, content, tag="rc-v2"
-        )
-
-        # Verify ref_count is 2
-        response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
-        assert response.json()["ref_count"] == 2
-
-        # Delete one tag
-        delete_response = integration_client.delete(
-            f"/api/v1/project/{project_name}/{package_name}/tags/rc-v1"
-        )
-        assert delete_response.status_code == 204
-
-        # Verify ref_count is now 1
-        response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
-        assert response.json()["ref_count"] == 1
-
-    @pytest.mark.integration
-    def test_ref_count_zero_after_all_tags_deleted(
-        self, integration_client, test_package
-    ):
-        """Test ref_count goes to 0 when all tags are deleted."""
-        project_name, package_name = test_package
-        content = b"orphan test content"
-        expected_hash = compute_sha256(content)
-
-        # Upload with one tag
-        upload_test_file(
-            integration_client, project_name, package_name, content, tag="only-tag"
-        )
-
-        # Delete the tag
-        integration_client.delete(
-            f"/api/v1/project/{project_name}/{package_name}/tags/only-tag"
-        )
-
-        # Verify ref_count is 0
-        response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
-        assert response.json()["ref_count"] == 0
-
-    @pytest.mark.integration
-    def test_ref_count_adjusts_on_tag_update(
-        self, integration_client, test_package, unique_test_id
-    ):
-        """Test ref_count adjusts when a tag is updated to point to different artifact."""
-        project_name, package_name = test_package
-
-        # Upload two different artifacts
-        content1 = f"artifact one {unique_test_id}".encode()
-        content2 = f"artifact two {unique_test_id}".encode()
-        hash1 = compute_sha256(content1)
-        hash2 = compute_sha256(content2)
-
-        # Upload first artifact with tag "latest"
-        upload_test_file(
-            integration_client, project_name, package_name, content1, tag="latest"
-        )
-
-        # Verify first artifact has ref_count 1
-        response = integration_client.get(f"/api/v1/artifact/{hash1}")
-        assert response.json()["ref_count"] == 1
-
-        # Upload second artifact with different tag
-        upload_test_file(
-            integration_client, project_name, package_name, content2, tag="stable"
-        )
-
-        # Now update "latest" tag to point to second artifact
-        upload_test_file(
-            integration_client, project_name, package_name, content2, tag="latest"
-        )
-
-        # Verify first artifact ref_count decreased to 0
-        response = integration_client.get(f"/api/v1/artifact/{hash1}")
-        assert response.json()["ref_count"] == 0
-
-        # Verify second artifact ref_count increased to 2
-        response = integration_client.get(f"/api/v1/artifact/{hash2}")
-        assert response.json()["ref_count"] == 2
-
-    @pytest.mark.integration
-    def test_ref_count_unchanged_when_tag_same_artifact(
-        self, integration_client, test_package, unique_test_id
-    ):
-        """Test ref_count doesn't change when tag is 'updated' to same artifact."""
-        project_name, package_name = test_package
-
-        content = f"same artifact {unique_test_id}".encode()
-        expected_hash = compute_sha256(content)
-
-        # Upload with tag
-        upload_test_file(
-            integration_client, project_name, package_name, content, tag="same-v1"
-        )
-
-        # Verify ref_count is 1
-        response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
-        assert response.json()["ref_count"] == 1
-
-        # Upload same content with same tag (no-op)
-        upload_test_file(
-            integration_client, project_name, package_name, content, tag="same-v1"
-        )
-
-        # Verify ref_count is still 1
-        response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
-        assert response.json()["ref_count"] == 1
-
-    @pytest.mark.integration
-    def test_tag_via_post_endpoint_increments_ref_count(
-        self, integration_client, test_package, unique_test_id
-    ):
-        """Test creating tag via POST /tags endpoint increments ref_count."""
-        project_name, package_name = test_package
-
-        content = f"tag endpoint test {unique_test_id}".encode()
-        expected_hash = compute_sha256(content)
-
-        # Upload artifact without tag
-        result = upload_test_file(
-            integration_client, project_name, package_name, content, filename="test.bin"
-        )
-        artifact_id = result["artifact_id"]
-
-        # Verify ref_count is 0 (no tags yet)
-        response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
-        assert response.json()["ref_count"] == 0
-
-        # Create tag via POST endpoint
-        tag_response = integration_client.post(
-            f"/api/v1/project/{project_name}/{package_name}/tags",
-            json={"name": "post-v1", "artifact_id": artifact_id},
-        )
-        assert tag_response.status_code == 200
-
-        # Verify ref_count is now 1
-        response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
-        assert response.json()["ref_count"] == 1
-
-        # Create another tag via POST endpoint
-        tag_response = integration_client.post(
-            f"/api/v1/project/{project_name}/{package_name}/tags",
-            json={"name": "post-latest", "artifact_id": artifact_id},
-        )
-        assert tag_response.status_code == 200
-
-        # Verify ref_count is now 2
-        response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
-        assert response.json()["ref_count"] == 2

backend/tests/integration/test_upload_download_api.py

@@ -47,7 +47,7 @@ class TestUploadBasics:
         expected_hash = compute_sha256(content)
 
         result = upload_test_file(
-            integration_client, project_name, package_name, content, tag="v1"
+            integration_client, project_name, package_name, content, version="v1"
         )
 
         assert result["artifact_id"] == expected_hash
@@ -116,31 +116,23 @@ class TestUploadBasics:
         assert result["created_at"] is not None
 
     @pytest.mark.integration
-    def test_upload_without_tag_succeeds(self, integration_client, test_package):
-        """Test upload without tag succeeds (no tag created)."""
+    def test_upload_without_version_succeeds(self, integration_client, test_package):
+        """Test upload without version succeeds (no version created)."""
         project, package = test_package
-        content = b"upload without tag test"
+        content = b"upload without version test"
         expected_hash = compute_sha256(content)
 
-        files = {"file": ("no_tag.bin", io.BytesIO(content), "application/octet-stream")}
+        files = {"file": ("no_version.bin", io.BytesIO(content), "application/octet-stream")}
         response = integration_client.post(
             f"/api/v1/project/{project}/{package}/upload",
             files=files,
-            # No tag parameter
+            # No version parameter
         )
         assert response.status_code == 200
         result = response.json()
         assert result["artifact_id"] == expected_hash
-
-        # Verify no tag was created - list tags and check
-        tags_response = integration_client.get(
-            f"/api/v1/project/{project}/{package}/tags"
-        )
-        assert tags_response.status_code == 200
-        tags = tags_response.json()
-        # Filter for tags pointing to this artifact
-        artifact_tags = [t for t in tags.get("items", tags) if t.get("artifact_id") == expected_hash]
-        assert len(artifact_tags) == 0, "Tag should not be created when not specified"
+        # Version should be None when not specified
+        assert result.get("version") is None
 
     @pytest.mark.integration
     def test_upload_creates_artifact_in_database(self, integration_client, test_package):
@@ -172,25 +164,29 @@ class TestUploadBasics:
         assert s3_object_exists(expected_hash), "S3 object should exist after upload"
 
     @pytest.mark.integration
-    def test_upload_with_tag_creates_tag_record(self, integration_client, test_package):
-        """Test upload with tag creates tag record."""
+    def test_upload_with_version_creates_version_record(self, integration_client, test_package):
+        """Test upload with version creates version record."""
         project, package = test_package
-        content = b"tag creation test"
+        content = b"version creation test"
         expected_hash = compute_sha256(content)
-        tag_name = "my-tag-v1"
+        version_name = "1.0.0"
 
-        upload_test_file(
-            integration_client, project, package, content, tag=tag_name
+        result = upload_test_file(
+            integration_client, project, package, content, version=version_name
         )
 
-        # Verify tag exists
-        tags_response = integration_client.get(
-            f"/api/v1/project/{project}/{package}/tags"
+        # Verify version was created
+        assert result.get("version") == version_name
+        assert result["artifact_id"] == expected_hash
+
+        # Verify version exists in versions list
+        versions_response = integration_client.get(
+            f"/api/v1/project/{project}/{package}/versions"
         )
-        assert tags_response.status_code == 200
-        tags = tags_response.json()
-        tag_names = [t["name"] for t in tags.get("items", tags)]
-        assert tag_name in tag_names
+        assert versions_response.status_code == 200
+        versions = versions_response.json()
+        version_names = [v["version"] for v in versions.get("items", [])]
+        assert version_name in version_names
 
 
 class TestDuplicateUploads:
@@ -207,36 +203,44 @@ class TestDuplicateUploads:
 
         # First upload
         result1 = upload_test_file(
-            integration_client, project, package, content, tag="first"
+            integration_client, project, package, content, version="first"
         )
         assert result1["artifact_id"] == expected_hash
 
         # Second upload
         result2 = upload_test_file(
-            integration_client, project, package, content, tag="second"
+            integration_client, project, package, content, version="second"
         )
         assert result2["artifact_id"] == expected_hash
         assert result1["artifact_id"] == result2["artifact_id"]
 
     @pytest.mark.integration
-    def test_same_file_twice_increments_ref_count(
+    def test_same_file_twice_returns_existing_version(
         self, integration_client, test_package
     ):
-        """Test uploading same file twice increments ref_count to 2."""
+        """Test uploading same file twice in same package returns existing version.
+
+        Same artifact can only have one version per package. Uploading the same content
+        with a different version name returns the existing version, not a new one.
+        ref_count stays at 1 because there's still only one PackageVersion reference.
+        """
         project, package = test_package
         content = b"content for ref count increment test"
 
         # First upload
         result1 = upload_test_file(
-            integration_client, project, package, content, tag="v1"
+            integration_client, project, package, content, version="v1"
         )
         assert result1["ref_count"] == 1
 
-        # Second upload
+        # Second upload with different version name returns existing version
         result2 = upload_test_file(
-            integration_client, project, package, content, tag="v2"
+            integration_client, project, package, content, version="v2"
         )
-        assert result2["ref_count"] == 2
+        # Same artifact, same package = same version returned, ref_count stays 1
+        assert result2["ref_count"] == 1
+        assert result2["deduplicated"] is True
+        assert result1["version"] == result2["version"]  # Both return "v1"
 
     @pytest.mark.integration
     def test_same_file_different_packages_shares_artifact(
@@ -261,12 +265,12 @@ class TestDuplicateUploads:
         )
 
         # Upload to first package
-        result1 = upload_test_file(integration_client, project, pkg1, content, tag="v1")
+        result1 = upload_test_file(integration_client, project, pkg1, content, version="v1")
         assert result1["artifact_id"] == expected_hash
         assert result1["deduplicated"] is False
 
         # Upload to second package
-        result2 = upload_test_file(integration_client, project, pkg2, content, tag="v1")
+        result2 = upload_test_file(integration_client, project, pkg2, content, version="v1")
         assert result2["artifact_id"] == expected_hash
         assert result2["deduplicated"] is True
 
@@ -286,7 +290,7 @@ class TestDuplicateUploads:
             package,
             content,
             filename="file1.bin",
-            tag="v1",
+            version="v1",
         )
         assert result1["artifact_id"] == expected_hash
 
@@ -297,7 +301,7 @@ class TestDuplicateUploads:
             package,
             content,
             filename="file2.bin",
-            tag="v2",
+            version="v2",
         )
         assert result2["artifact_id"] == expected_hash
         assert result2["deduplicated"] is True
@@ -307,17 +311,17 @@ class TestDownload:
     """Tests for download functionality."""
 
     @pytest.mark.integration
-    def test_download_by_tag(self, integration_client, test_package):
-        """Test downloading artifact by tag name."""
+    def test_download_by_version(self, integration_client, test_package):
+        """Test downloading artifact by version."""
         project, package = test_package
-        original_content = b"download by tag test"
+        original_content = b"download by version test"
 
         upload_test_file(
-            integration_client, project, package, original_content, tag="download-tag"
+            integration_client, project, package, original_content, version="1.0.0"
         )
 
         response = integration_client.get(
-            f"/api/v1/project/{project}/{package}/+/download-tag",
+            f"/api/v1/project/{project}/{package}/+/1.0.0",
             params={"mode": "proxy"},
         )
         assert response.status_code == 200
@@ -340,29 +344,29 @@ class TestDownload:
         assert response.content == original_content
 
     @pytest.mark.integration
-    def test_download_by_tag_prefix(self, integration_client, test_package):
-        """Test downloading artifact using tag: prefix."""
+    def test_download_by_version_prefix(self, integration_client, test_package):
+        """Test downloading artifact using version: prefix."""
         project, package = test_package
-        original_content = b"download by tag prefix test"
+        original_content = b"download by version prefix test"
 
         upload_test_file(
-            integration_client, project, package, original_content, tag="prefix-tag"
+            integration_client, project, package, original_content, version="2.0.0"
         )
 
         response = integration_client.get(
-            f"/api/v1/project/{project}/{package}/+/tag:prefix-tag",
+            f"/api/v1/project/{project}/{package}/+/version:2.0.0",
             params={"mode": "proxy"},
         )
         assert response.status_code == 200
         assert response.content == original_content
 
     @pytest.mark.integration
-    def test_download_nonexistent_tag(self, integration_client, test_package):
-        """Test downloading nonexistent tag returns 404."""
+    def test_download_nonexistent_version(self, integration_client, test_package):
+        """Test downloading nonexistent version returns 404."""
         project, package = test_package
 
         response = integration_client.get(
-            f"/api/v1/project/{project}/{package}/+/nonexistent-tag"
+            f"/api/v1/project/{project}/{package}/+/nonexistent-version"
         )
         assert response.status_code == 404
 
@@ -400,7 +404,7 @@ class TestDownload:
         original_content = b"exact content verification test data 12345"
 
         upload_test_file(
-            integration_client, project, package, original_content, tag="verify"
+            integration_client, project, package, original_content, version="verify"
         )
 
         response = integration_client.get(
@@ -421,7 +425,7 @@ class TestDownloadHeaders:
 
         upload_test_file(
             integration_client, project, package, content,
-            filename="test.txt", tag="content-type-test"
+            filename="test.txt", version="content-type-test"
         )
 
         response = integration_client.get(
@@ -440,7 +444,7 @@ class TestDownloadHeaders:
         expected_length = len(content)
 
         upload_test_file(
-            integration_client, project, package, content, tag="content-length-test"
+            integration_client, project, package, content, version="content-length-test"
         )
 
         response = integration_client.get(
@@ -460,7 +464,7 @@ class TestDownloadHeaders:
 
         upload_test_file(
             integration_client, project, package, content,
-            filename=filename, tag="disposition-test"
+            filename=filename, version="disposition-test"
         )
 
         response = integration_client.get(
@@ -481,7 +485,7 @@ class TestDownloadHeaders:
         expected_hash = compute_sha256(content)
 
         upload_test_file(
-            integration_client, project, package, content, tag="checksum-headers"
+            integration_client, project, package, content, version="checksum-headers"
         )
 
         response = integration_client.get(
@@ -501,7 +505,7 @@ class TestDownloadHeaders:
         expected_hash = compute_sha256(content)
 
         upload_test_file(
-            integration_client, project, package, content, tag="etag-test"
+            integration_client, project, package, content, version="etag-test"
         )
 
         response = integration_client.get(
@@ -519,17 +523,31 @@ class TestConcurrentUploads:
     """Tests for concurrent upload handling."""
 
     @pytest.mark.integration
-    def test_concurrent_uploads_same_file(self, integration_client, test_package):
-        """Test concurrent uploads of same file handle deduplication correctly."""
-        project, package = test_package
+    def test_concurrent_uploads_same_file(self, integration_client, test_project, unique_test_id):
+        """Test concurrent uploads of same file to different packages handle deduplication correctly.
+
+        Same artifact can only have one version per package, so we create multiple packages
+        to test that concurrent uploads to different packages correctly increment ref_count.
+        """
         content = b"content for concurrent upload test"
         expected_hash = compute_sha256(content)
         num_concurrent = 5
 
+        # Create packages for each concurrent upload
+        packages = []
+        for i in range(num_concurrent):
+            pkg_name = f"concurrent-pkg-{unique_test_id}-{i}"
+            response = integration_client.post(
+                f"/api/v1/project/{test_project}/packages",
+                json={"name": pkg_name},
+            )
+            assert response.status_code == 200
+            packages.append(pkg_name)
+
         # Create an API key for worker threads
         api_key_response = integration_client.post(
             "/api/v1/auth/keys",
-            json={"name": "concurrent-test-key"},
+            json={"name": f"concurrent-test-key-{unique_test_id}"},
         )
         assert api_key_response.status_code == 200, f"Failed to create API key: {api_key_response.text}"
         api_key = api_key_response.json()["key"]
@@ -537,7 +555,7 @@ class TestConcurrentUploads:
         results = []
         errors = []
 
-        def upload_worker(tag_suffix):
+        def upload_worker(idx):
             try:
                 from httpx import Client
 
@@ -545,15 +563,15 @@ class TestConcurrentUploads:
                 with Client(base_url=base_url, timeout=30.0) as client:
                     files = {
                         "file": (
-                            f"concurrent-{tag_suffix}.bin",
+                            f"concurrent-{idx}.bin",
                             io.BytesIO(content),
                             "application/octet-stream",
                         )
                     }
                     response = client.post(
-                        f"/api/v1/project/{project}/{package}/upload",
+                        f"/api/v1/project/{test_project}/{packages[idx]}/upload",
                         files=files,
-                        data={"tag": f"concurrent-{tag_suffix}"},
+                        data={"version": "1.0.0"},
                         headers={"Authorization": f"Bearer {api_key}"},
                     )
                     if response.status_code == 200:
@@ -576,7 +594,7 @@ class TestConcurrentUploads:
         assert len(artifact_ids) == 1
         assert expected_hash in artifact_ids
 
-        # Verify final ref_count
+        # Verify final ref_count equals number of packages
         response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
         assert response.status_code == 200
         assert response.json()["ref_count"] == num_concurrent
@@ -605,7 +623,7 @@ class TestFileSizeValidation:
         content = b"X"
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="tiny"
+            integration_client, project, package, content, version="tiny"
         )
 
         assert result["artifact_id"] is not None
@@ -621,7 +639,7 @@ class TestFileSizeValidation:
         expected_size = len(content)
 
         result = upload_test_file(
-            integration_client, project, package, content, tag="size-test"
+            integration_client, project, package, content, version="size-test"
         )
 
         assert result["size"] == expected_size
@@ -649,7 +667,7 @@ class TestUploadFailureCleanup:
         response = integration_client.post(
             f"/api/v1/project/nonexistent-project-{unique_test_id}/nonexistent-pkg/upload",
             files=files,
-            data={"tag": "test"},
+            data={"version": "test"},
         )
 
         assert response.status_code == 404
@@ -672,7 +690,7 @@ class TestUploadFailureCleanup:
         response = integration_client.post(
             f"/api/v1/project/{test_project}/nonexistent-package-{unique_test_id}/upload",
             files=files,
-            data={"tag": "test"},
+            data={"version": "test"},
         )
 
         assert response.status_code == 404
@@ -693,7 +711,7 @@ class TestUploadFailureCleanup:
         response = integration_client.post(
             f"/api/v1/project/{test_project}/nonexistent-package-{unique_test_id}/upload",
             files=files,
-            data={"tag": "test"},
+            data={"version": "test"},
         )
 
         assert response.status_code == 404
@@ -719,7 +737,7 @@ class TestS3StorageVerification:
 
         # Upload same content multiple times
         for tag in ["s3test1", "s3test2", "s3test3"]:
-            upload_test_file(integration_client, project, package, content, tag=tag)
+            upload_test_file(integration_client, project, package, content, version=tag)
 
         # Verify only one S3 object exists
         s3_objects = list_s3_objects_by_hash(expected_hash)
@@ -735,16 +753,26 @@ class TestS3StorageVerification:
 
     @pytest.mark.integration
     def test_artifact_table_single_row_after_duplicates(
-        self, integration_client, test_package
+        self, integration_client, test_project, unique_test_id
     ):
-        """Test artifact table contains only one row after duplicate uploads."""
-        project, package = test_package
+        """Test artifact table contains only one row after duplicate uploads to different packages.
+
+        Same artifact can only have one version per package, so we create multiple packages
+        to test deduplication across packages.
+        """
         content = b"content for single row test"
         expected_hash = compute_sha256(content)
 
-        # Upload same content multiple times
-        for tag in ["v1", "v2", "v3"]:
-            upload_test_file(integration_client, project, package, content, tag=tag)
+        # Create 3 packages and upload same content to each
+        for i in range(3):
+            pkg_name = f"single-row-pkg-{unique_test_id}-{i}"
+            integration_client.post(
+                f"/api/v1/project/{test_project}/packages",
+                json={"name": pkg_name},
+            )
+            upload_test_file(
+                integration_client, test_project, pkg_name, content, version="1.0.0"
+            )
 
         # Query artifact
         response = integration_client.get(f"/api/v1/artifact/{expected_hash}")
@@ -783,7 +811,7 @@ class TestSecurityPathTraversal:
         response = integration_client.post(
             f"/api/v1/project/{project}/{package}/upload",
             files=files,
-            data={"tag": "traversal-test"},
+            data={"version": "traversal-test"},
         )
         assert response.status_code == 200
         result = response.json()
@@ -801,48 +829,16 @@ class TestSecurityPathTraversal:
         assert response.status_code in [400, 404, 422]
 
     @pytest.mark.integration
-    def test_path_traversal_in_tag_name(self, integration_client, test_package):
-        """Test tag names with path traversal are handled safely."""
+    def test_path_traversal_in_version_name(self, integration_client, test_package):
+        """Test version names with path traversal are handled safely."""
         project, package = test_package
-        content = b"tag traversal test"
+        content = b"version traversal test"
 
         files = {"file": ("test.bin", io.BytesIO(content), "application/octet-stream")}
         response = integration_client.post(
             f"/api/v1/project/{project}/{package}/upload",
             files=files,
-            data={"tag": "../../../etc/passwd"},
-        )
-        assert response.status_code in [200, 400, 422]
-
-    @pytest.mark.integration
-    def test_download_path_traversal_in_ref(self, integration_client, test_package):
-        """Test download ref with path traversal is rejected."""
-        project, package = test_package
-
-        response = integration_client.get(
-            f"/api/v1/project/{project}/{package}/+/../../../etc/passwd"
-        )
-        assert response.status_code in [400, 404, 422]
-
-    @pytest.mark.integration
-    def test_path_traversal_in_package_name(self, integration_client, test_project):
-        """Test package names with path traversal sequences are rejected."""
-        response = integration_client.get(
-            f"/api/v1/project/{test_project}/packages/../../../etc/passwd"
-        )
-        assert response.status_code in [400, 404, 422]
-
-    @pytest.mark.integration
-    def test_path_traversal_in_tag_name(self, integration_client, test_package):
-        """Test tag names with path traversal are rejected or handled safely."""
-        project, package = test_package
-        content = b"tag traversal test"
-
-        files = {"file": ("test.bin", io.BytesIO(content), "application/octet-stream")}
-        response = integration_client.post(
-            f"/api/v1/project/{project}/{package}/upload",
-            files=files,
-            data={"tag": "../../../etc/passwd"},
+            data={"version": "../../../etc/passwd"},
         )
         assert response.status_code in [200, 400, 422]
 
@@ -867,7 +863,7 @@ class TestSecurityMalformedRequests:
 
         response = integration_client.post(
             f"/api/v1/project/{project}/{package}/upload",
-            data={"tag": "no-file"},
+            data={"version": "no-file"},
         )
         assert response.status_code == 422
 

backend/tests/integration/test_version_api.py

@@ -39,31 +39,6 @@ class TestVersionCreation:
         assert result.get("version") == "1.0.0"
         assert result.get("version_source") == "explicit"
 
-    @pytest.mark.integration
-    def test_upload_with_version_and_tag(self, integration_client, test_package):
-        """Test upload with both version and tag creates both records."""
-        project, package = test_package
-        content = b"version and tag test"
-
-        files = {"file": ("app.tar.gz", io.BytesIO(content), "application/octet-stream")}
-        response = integration_client.post(
-            f"/api/v1/project/{project}/{package}/upload",
-            files=files,
-            data={"version": "2.0.0", "tag": "latest"},
-        )
-        assert response.status_code == 200
-        result = response.json()
-        assert result.get("version") == "2.0.0"
-
-        # Verify tag was also created
-        tags_response = integration_client.get(
-            f"/api/v1/project/{project}/{package}/tags"
-        )
-        assert tags_response.status_code == 200
-        tags = tags_response.json()
-        tag_names = [t["name"] for t in tags.get("items", tags)]
-        assert "latest" in tag_names
-
     @pytest.mark.integration
     def test_duplicate_version_same_content_succeeds(self, integration_client, test_package):
         """Test uploading same version with same content succeeds (deduplication)."""
@@ -262,11 +237,10 @@ class TestDownloadByVersion:
         assert response.status_code == 404
 
     @pytest.mark.integration
-    def test_version_resolution_priority(self, integration_client, test_package):
-        """Test that version: prefix explicitly resolves to version, not tag."""
+    def test_version_resolution_with_prefix(self, integration_client, test_package):
+        """Test that version: prefix explicitly resolves to version."""
         project, package = test_package
         version_content = b"this is the version content"
-        tag_content = b"this is the tag content"
 
         # Create a version 6.0.0
         files1 = {"file": ("app-v.tar.gz", io.BytesIO(version_content), "application/octet-stream")}
@@ -276,14 +250,6 @@ class TestDownloadByVersion:
             data={"version": "6.0.0"},
         )
 
-        # Create a tag named "6.0.0" pointing to different content
-        files2 = {"file": ("app-t.tar.gz", io.BytesIO(tag_content), "application/octet-stream")}
-        integration_client.post(
-            f"/api/v1/project/{project}/{package}/upload",
-            files=files2,
-            data={"tag": "6.0.0"},
-        )
-
         # Download with version: prefix should get version content
         response = integration_client.get(
             f"/api/v1/project/{project}/{package}/+/version:6.0.0",
@@ -292,14 +258,6 @@ class TestDownloadByVersion:
         assert response.status_code == 200
         assert response.content == version_content
 
-        # Download with tag: prefix should get tag content
-        response2 = integration_client.get(
-            f"/api/v1/project/{project}/{package}/+/tag:6.0.0",
-            params={"mode": "proxy"},
-        )
-        assert response2.status_code == 200
-        assert response2.content == tag_content
-
 
 class TestVersionDeletion:
     """Tests for deleting versions."""

backend/tests/integration/test_versions_api.py

@@ -27,11 +27,9 @@ class TestVersionCreation:
             project_name,
             package_name,
             b"version create test",
-            tag="latest",
             version="1.0.0",
         )
 
-        assert result["tag"] == "latest"
         assert result["version"] == "1.0.0"
         assert result["version_source"] == "explicit"
         assert result["artifact_id"]
@@ -149,7 +147,6 @@ class TestVersionCRUD:
             package_name,
             b"version with info",
             version="1.0.0",
-            tag="release",
         )
 
         response = integration_client.get(
@@ -166,8 +163,6 @@ class TestVersionCRUD:
         assert version_item is not None
         assert "size" in version_item
         assert "artifact_id" in version_item
-        assert "tags" in version_item
-        assert "release" in version_item["tags"]
 
     @pytest.mark.integration
     def test_get_version(self, integration_client, test_package):
@@ -272,94 +267,9 @@ class TestVersionDownload:
             follow_redirects=False,
         )
 
-        # Should resolve version first (before tag)
+        # Should resolve version
         assert response.status_code in [200, 302, 307]
 
-    @pytest.mark.integration
-    def test_version_takes_precedence_over_tag(self, integration_client, test_package):
-        """Test that version is checked before tag when resolving refs."""
-        project_name, package_name = test_package
-
-        # Upload with version "1.0"
-        version_result = upload_test_file(
-            integration_client,
-            project_name,
-            package_name,
-            b"version content",
-            version="1.0",
-        )
-
-        # Create a tag with the same name "1.0" pointing to different artifact
-        tag_result = upload_test_file(
-            integration_client,
-            project_name,
-            package_name,
-            b"tag content different",
-            tag="1.0",
-        )
-
-        # Download by "1.0" should resolve to version, not tag
-        # Since version:1.0 artifact was uploaded first
-        response = integration_client.get(
-            f"/api/v1/project/{project_name}/{package_name}/+/1.0",
-            follow_redirects=False,
-        )
-
-        assert response.status_code in [200, 302, 307]
-
-
-class TestTagVersionEnrichment:
-    """Tests for tag responses including version information."""
-
-    @pytest.mark.integration
-    def test_tag_response_includes_version(self, integration_client, test_package):
-        """Test that tag responses include version of the artifact."""
-        project_name, package_name = test_package
-
-        # Upload with both version and tag
-        upload_test_file(
-            integration_client,
-            project_name,
-            package_name,
-            b"enriched tag test",
-            version="7.0.0",
-            tag="stable",
-        )
-
-        # Get tag and check version field
-        response = integration_client.get(
-            f"/api/v1/project/{project_name}/{package_name}/tags/stable"
-        )
-        assert response.status_code == 200
-
-        data = response.json()
-        assert data["name"] == "stable"
-        assert data["version"] == "7.0.0"
-
-    @pytest.mark.integration
-    def test_tag_list_includes_versions(self, integration_client, test_package):
-        """Test that tag list responses include version for each tag."""
-        project_name, package_name = test_package
-
-        upload_test_file(
-            integration_client,
-            project_name,
-            package_name,
-            b"list version test",
-            version="8.0.0",
-            tag="latest",
-        )
-
-        response = integration_client.get(
-            f"/api/v1/project/{project_name}/{package_name}/tags"
-        )
-        assert response.status_code == 200
-
-        data = response.json()
-        tag_item = next((t for t in data["items"] if t["name"] == "latest"), None)
-        assert tag_item is not None
-        assert tag_item.get("version") == "8.0.0"
-
 
 class TestVersionPagination:
     """Tests for version listing pagination and sorting."""

backend/tests/test_dependencies.py

@@ -39,7 +39,7 @@ class TestDependencySchema:
         response = integration_client.post(
             f"/api/v1/project/{project_name}/{package_name}/upload",
             files=files,
-            data={"tag": f"v1.0.0-{unique_test_id}"},
+            data={"version": f"v1.0.0-{unique_test_id}"},
         )
         assert response.status_code == 200
 
@@ -59,29 +59,17 @@ class TestDependencySchema:
             integration_client.delete(f"/api/v1/projects/{dep_project_name}")
 
     @pytest.mark.integration
-    def test_dependency_requires_version_or_tag(self, integration_client):
-        """Test that dependency must have either version or tag, not both or neither."""
+    def test_dependency_requires_version(self, integration_client):
+        """Test that dependency requires version."""
         from app.schemas import DependencyCreate
 
-        # Test: neither version nor tag
-        with pytest.raises(ValidationError) as exc_info:
+        # Test: missing version
+        with pytest.raises(ValidationError):
             DependencyCreate(project="proj", package="pkg")
-        assert "Either 'version' or 'tag' must be specified" in str(exc_info.value)
-
-        # Test: both version and tag
-        with pytest.raises(ValidationError) as exc_info:
-            DependencyCreate(project="proj", package="pkg", version="1.0.0", tag="stable")
-        assert "Cannot specify both 'version' and 'tag'" in str(exc_info.value)
 
         # Test: valid with version
         dep = DependencyCreate(project="proj", package="pkg", version="1.0.0")
         assert dep.version == "1.0.0"
-        assert dep.tag is None
-
-        # Test: valid with tag
-        dep = DependencyCreate(project="proj", package="pkg", tag="stable")
-        assert dep.tag == "stable"
-        assert dep.version is None
 
     @pytest.mark.integration
     def test_dependency_unique_constraint(
@@ -126,7 +114,7 @@ class TestEnsureFileParsing:
             response = integration_client.post(
                 f"/api/v1/project/{project_name}/{package_name}/upload",
                 files=files,
-                data={"tag": f"v1.0.0-{unique_test_id}"},
+                data={"version": f"v1.0.0-{unique_test_id}"},
             )
             assert response.status_code == 200
             data = response.json()
@@ -162,7 +150,7 @@ class TestEnsureFileParsing:
         response = integration_client.post(
             f"/api/v1/project/{project_name}/{package_name}/upload",
             files=files,
-            data={"tag": f"v1.0.0-{unique_test_id}"},
+            data={"version": f"v1.0.0-{unique_test_id}"},
         )
         assert response.status_code == 400
         assert "Invalid ensure file" in response.json().get("detail", "")
@@ -188,7 +176,7 @@ class TestEnsureFileParsing:
         response = integration_client.post(
             f"/api/v1/project/{project_name}/{package_name}/upload",
             files=files,
-            data={"tag": f"v1.0.0-{unique_test_id}"},
+            data={"version": f"v1.0.0-{unique_test_id}"},
         )
         assert response.status_code == 400
         assert "Project" in response.json().get("detail", "")
@@ -208,7 +196,7 @@ class TestEnsureFileParsing:
         response = integration_client.post(
             f"/api/v1/project/{project_name}/{package_name}/upload",
             files=files,
-            data={"tag": f"v1.0.0-nodeps-{unique_test_id}"},
+            data={"version": f"v1.0.0-nodeps-{unique_test_id}"},
         )
         assert response.status_code == 200
 
@@ -226,13 +214,14 @@ class TestEnsureFileParsing:
         assert response.status_code == 200
 
         try:
+            # Test with missing version field (version is now required)
             ensure_content = yaml.dump({
                 "dependencies": [
-                    {"project": dep_project_name, "package": "pkg", "version": "1.0.0", "tag": "stable"}
+                    {"project": dep_project_name, "package": "pkg"}  # Missing version
                 ]
             })
 
-            content = unique_content("test-both", unique_test_id, "constraint")
+            content = unique_content("test-missing-version", unique_test_id, "constraint")
             files = {
                 "file": ("test.tar.gz", BytesIO(content), "application/gzip"),
                 "ensure": ("orchard.ensure", BytesIO(ensure_content.encode()), "application/x-yaml"),
@@ -240,11 +229,10 @@ class TestEnsureFileParsing:
             response = integration_client.post(
                 f"/api/v1/project/{project_name}/{package_name}/upload",
                 files=files,
-                data={"tag": f"v1.0.0-{unique_test_id}"},
+                data={"version": f"v1.0.0-{unique_test_id}"},
             )
             assert response.status_code == 400
-            assert "both" in response.json().get("detail", "").lower() or \
-                   "version" in response.json().get("detail", "").lower()
+            assert "version" in response.json().get("detail", "").lower()
         finally:
             integration_client.delete(f"/api/v1/projects/{dep_project_name}")
 
@@ -271,7 +259,7 @@ class TestDependencyQueryEndpoints:
             ensure_content = yaml.dump({
                 "dependencies": [
                     {"project": dep_project_name, "package": "lib-a", "version": "1.0.0"},
-                    {"project": dep_project_name, "package": "lib-b", "tag": "stable"},
+                    {"project": dep_project_name, "package": "lib-b", "version": "2.0.0"},
                 ]
             })
 
@@ -283,7 +271,7 @@ class TestDependencyQueryEndpoints:
             response = integration_client.post(
                 f"/api/v1/project/{project_name}/{package_name}/upload",
                 files=files,
-                data={"tag": f"v2.0.0-{unique_test_id}"},
+                data={"version": f"v2.0.0-{unique_test_id}"},
             )
             assert response.status_code == 200
             artifact_id = response.json()["artifact_id"]
@@ -299,10 +287,8 @@ class TestDependencyQueryEndpoints:
             deps = {d["package"]: d for d in data["dependencies"]}
             assert "lib-a" in deps
             assert deps["lib-a"]["version"] == "1.0.0"
-            assert deps["lib-a"]["tag"] is None
             assert "lib-b" in deps
-            assert deps["lib-b"]["tag"] == "stable"
-            assert deps["lib-b"]["version"] is None
+            assert deps["lib-b"]["version"] == "2.0.0"
 
         finally:
             integration_client.delete(f"/api/v1/projects/{dep_project_name}")
@@ -336,7 +322,7 @@ class TestDependencyQueryEndpoints:
             response = integration_client.post(
                 f"/api/v1/project/{project_name}/{package_name}/upload",
                 files=files,
-                data={"tag": tag_name},
+                data={"version": tag_name},
             )
             assert response.status_code == 200
 
@@ -381,7 +367,7 @@ class TestDependencyQueryEndpoints:
             response = integration_client.post(
                 f"/api/v1/project/{dep_project_name}/target-lib/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -400,7 +386,7 @@ class TestDependencyQueryEndpoints:
             response = integration_client.post(
                 f"/api/v1/project/{project_name}/{package_name}/upload",
                 files=files,
-                data={"tag": f"v4.0.0-{unique_test_id}"},
+                data={"version": f"v4.0.0-{unique_test_id}"},
             )
             assert response.status_code == 200
 
@@ -419,7 +405,6 @@ class TestDependencyQueryEndpoints:
             for dep in data["dependents"]:
                 if dep["project"] == project_name:
                     found = True
-                    assert dep["constraint_type"] == "version"
                     assert dep["constraint_value"] == "1.0.0"
                     break
             assert found, "Our package should be in the dependents list"
@@ -442,7 +427,7 @@ class TestDependencyQueryEndpoints:
         response = integration_client.post(
             f"/api/v1/project/{project_name}/{package_name}/upload",
             files=files,
-            data={"tag": f"v5.0.0-nodeps-{unique_test_id}"},
+            data={"version": f"v5.0.0-nodeps-{unique_test_id}"},
         )
         assert response.status_code == 200
         artifact_id = response.json()["artifact_id"]
@@ -482,7 +467,7 @@ class TestDependencyResolution:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_c}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -500,7 +485,7 @@ class TestDependencyResolution:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_b}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -518,7 +503,7 @@ class TestDependencyResolution:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_a}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -566,7 +551,7 @@ class TestDependencyResolution:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_d}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -584,7 +569,7 @@ class TestDependencyResolution:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_b}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -602,7 +587,7 @@ class TestDependencyResolution:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_c}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -621,7 +606,7 @@ class TestDependencyResolution:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_a}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -663,7 +648,7 @@ class TestDependencyResolution:
         response = integration_client.post(
             f"/api/v1/project/{project_name}/{package_name}/upload",
             files=files,
-            data={"tag": f"solo-{unique_test_id}"},
+            data={"version": f"solo-{unique_test_id}"},
         )
         assert response.status_code == 200
 
@@ -698,17 +683,21 @@ class TestDependencyResolution:
         response = integration_client.post(
             f"/api/v1/project/{project_name}/{package_name}/upload",
             files=files,
-            data={"tag": f"missing-dep-{unique_test_id}"},
+            data={"version": f"missing-dep-{unique_test_id}"},
         )
         # Should fail at upload time since package doesn't exist
         # OR succeed at upload but fail at resolution
         # Depending on implementation choice
         if response.status_code == 200:
-            # Resolution should fail
+            # Resolution should return missing dependencies
             response = integration_client.get(
                 f"/api/v1/project/{project_name}/{package_name}/+/missing-dep-{unique_test_id}/resolve"
             )
-            assert response.status_code == 404
+            # Expect 200 with missing dependencies listed
+            assert response.status_code == 200
+            data = response.json()
+            # The missing dependency should be in the 'missing' list
+            assert len(data.get("missing", [])) >= 1
 
 
 class TestCircularDependencyDetection:
@@ -736,7 +725,7 @@ class TestCircularDependencyDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_a}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -754,7 +743,7 @@ class TestCircularDependencyDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_b}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -772,7 +761,7 @@ class TestCircularDependencyDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_a}/upload",
                 files=files,
-                data={"tag": "2.0.0"},
+                data={"version": "2.0.0"},
             )
             # Should be rejected with 400 (circular dependency)
             assert response.status_code == 400
@@ -807,7 +796,7 @@ class TestCircularDependencyDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_a}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -825,7 +814,7 @@ class TestCircularDependencyDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_b}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -843,7 +832,7 @@ class TestCircularDependencyDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_c}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -861,7 +850,7 @@ class TestCircularDependencyDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_a}/upload",
                 files=files,
-                data={"tag": "2.0.0"},
+                data={"version": "2.0.0"},
             )
             assert response.status_code == 400
             data = response.json()
@@ -910,7 +899,7 @@ class TestConflictDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_common}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -920,7 +909,7 @@ class TestConflictDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_common}/upload",
                 files=files,
-                data={"tag": "2.0.0"},
+                data={"version": "2.0.0"},
             )
             assert response.status_code == 200
 
@@ -938,7 +927,7 @@ class TestConflictDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_lib_a}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -956,7 +945,7 @@ class TestConflictDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_lib_b}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -975,7 +964,7 @@ class TestConflictDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_app}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -1023,7 +1012,7 @@ class TestConflictDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_common}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 
@@ -1042,7 +1031,7 @@ class TestConflictDetection:
                 response = integration_client.post(
                     f"/api/v1/project/{test_project}/{lib_pkg}/upload",
                     files=files,
-                    data={"tag": "1.0.0"},
+                    data={"version": "1.0.0"},
                 )
                 assert response.status_code == 200
 
@@ -1061,7 +1050,7 @@ class TestConflictDetection:
             response = integration_client.post(
                 f"/api/v1/project/{test_project}/{pkg_app}/upload",
                 files=files,
-                data={"tag": "1.0.0"},
+                data={"version": "1.0.0"},
             )
             assert response.status_code == 200
 

backend/tests/test_download_verification.py

@@ -26,16 +26,16 @@ def upload_test_file(integration_client):
     Factory fixture to upload a test file and return its artifact ID.
 
     Usage:
-        artifact_id = upload_test_file(project, package, content, tag="v1.0")
+        artifact_id = upload_test_file(project, package, content, version="v1.0")
     """
 
-    def _upload(project_name: str, package_name: str, content: bytes, tag: str = None):
+    def _upload(project_name: str, package_name: str, content: bytes, version: str = None):
         files = {
             "file": ("test-file.bin", io.BytesIO(content), "application/octet-stream")
         }
         data = {}
-        if tag:
-            data["tag"] = tag
+        if version:
+            data["version"] = version
 
         response = integration_client.post(
             f"/api/v1/project/{project_name}/{package_name}/upload",
@@ -66,7 +66,7 @@ class TestDownloadChecksumHeaders:
 
         # Upload file
         artifact_id = upload_test_file(
-            project_name, package_name, content, tag="sha256-header-test"
+            project_name, package_name, content, version="sha256-header-test"
         )
 
         # Download with proxy mode
@@ -88,7 +88,7 @@ class TestDownloadChecksumHeaders:
         content = b"Content for ETag header test"
 
         artifact_id = upload_test_file(
-            project_name, package_name, content, tag="etag-test"
+            project_name, package_name, content, version="etag-test"
         )
 
         response = integration_client.get(
@@ -110,7 +110,7 @@ class TestDownloadChecksumHeaders:
         content = b"Content for Digest header test"
         sha256 = hashlib.sha256(content).hexdigest()
 
-        upload_test_file(project_name, package_name, content, tag="digest-test")
+        upload_test_file(project_name, package_name, content, version="digest-test")
 
         response = integration_client.get(
             f"/api/v1/project/{project_name}/{package_name}/+/digest-test",
@@ -137,7 +137,7 @@ class TestDownloadChecksumHeaders:
         project_name, package_name = test_package
         content = b"Content for X-Content-Length test"
 
-        upload_test_file(project_name, package_name, content, tag="content-length-test")
+        upload_test_file(project_name, package_name, content, version="content-length-test")
 
         response = integration_client.get(
             f"/api/v1/project/{project_name}/{package_name}/+/content-length-test",
@@ -156,7 +156,7 @@ class TestDownloadChecksumHeaders:
         project_name, package_name = test_package
         content = b"Content for X-Verified false test"
 
-        upload_test_file(project_name, package_name, content, tag="verified-false-test")
+        upload_test_file(project_name, package_name, content, version="verified-false-test")
 
         response = integration_client.get(
             f"/api/v1/project/{project_name}/{package_name}/+/verified-false-test",
@@ -184,7 +184,7 @@ class TestPreVerificationMode:
         project_name, package_name = test_package
         content = b"Content for pre-verification success test"
 
-        upload_test_file(project_name, package_name, content, tag="pre-verify-success")
+        upload_test_file(project_name, package_name, content, version="pre-verify-success")
 
         response = integration_client.get(
             f"/api/v1/project/{project_name}/{package_name}/+/pre-verify-success",
@@ -205,7 +205,7 @@ class TestPreVerificationMode:
         # Use binary content to verify no corruption
         content = bytes(range(256)) * 10  # 2560 bytes of all byte values
 
-        upload_test_file(project_name, package_name, content, tag="pre-verify-content")
+        upload_test_file(project_name, package_name, content, version="pre-verify-content")
 
         response = integration_client.get(
             f"/api/v1/project/{project_name}/{package_name}/+/pre-verify-content",
@@ -233,7 +233,7 @@ class TestStreamingVerificationMode:
         content = b"Content for streaming verification success test"
 
         upload_test_file(
-            project_name, package_name, content, tag="stream-verify-success"
+            project_name, package_name, content, version="stream-verify-success"
         )
 
         response = integration_client.get(
@@ -255,7 +255,7 @@ class TestStreamingVerificationMode:
         # 100KB of content
         content = b"x" * (100 * 1024)
 
-        upload_test_file(project_name, package_name, content, tag="stream-verify-large")
+        upload_test_file(project_name, package_name, content, version="stream-verify-large")
 
         response = integration_client.get(
             f"/api/v1/project/{project_name}/{package_name}/+/stream-verify-large",
@@ -283,7 +283,7 @@ class TestHeadRequestHeaders:
         content = b"Content for HEAD SHA256 test"
 
         artifact_id = upload_test_file(
-            project_name, package_name, content, tag="head-sha256-test"
+            project_name, package_name, content, version="head-sha256-test"
         )
 
         response = integration_client.head(
@@ -303,7 +303,7 @@ class TestHeadRequestHeaders:
         content = b"Content for HEAD ETag test"
 
         artifact_id = upload_test_file(
-            project_name, package_name, content, tag="head-etag-test"
+            project_name, package_name, content, version="head-etag-test"
         )
 
         response = integration_client.head(
@@ -322,7 +322,7 @@ class TestHeadRequestHeaders:
         project_name, package_name = test_package
         content = b"Content for HEAD Digest test"
 
-        upload_test_file(project_name, package_name, content, tag="head-digest-test")
+        upload_test_file(project_name, package_name, content, version="head-digest-test")
 
         response = integration_client.head(
             f"/api/v1/project/{project_name}/{package_name}/+/head-digest-test"
@@ -340,7 +340,7 @@ class TestHeadRequestHeaders:
         project_name, package_name = test_package
         content = b"Content for HEAD Content-Length test"
 
-        upload_test_file(project_name, package_name, content, tag="head-length-test")
+        upload_test_file(project_name, package_name, content, version="head-length-test")
 
         response = integration_client.head(
             f"/api/v1/project/{project_name}/{package_name}/+/head-length-test"
@@ -356,7 +356,7 @@ class TestHeadRequestHeaders:
         project_name, package_name = test_package
         content = b"Content for HEAD no-body test"
 
-        upload_test_file(project_name, package_name, content, tag="head-no-body-test")
+        upload_test_file(project_name, package_name, content, version="head-no-body-test")
 
         response = integration_client.head(
             f"/api/v1/project/{project_name}/{package_name}/+/head-no-body-test"
@@ -382,7 +382,7 @@ class TestRangeRequestHeaders:
         project_name, package_name = test_package
         content = b"Content for range request checksum header test"
 
-        upload_test_file(project_name, package_name, content, tag="range-checksum-test")
+        upload_test_file(project_name, package_name, content, version="range-checksum-test")
 
         response = integration_client.get(
             f"/api/v1/project/{project_name}/{package_name}/+/range-checksum-test",
@@ -412,7 +412,7 @@ class TestClientSideVerification:
         project_name, package_name = test_package
         content = b"Content for client-side verification test"
 
-        upload_test_file(project_name, package_name, content, tag="client-verify-test")
+        upload_test_file(project_name, package_name, content, version="client-verify-test")
 
         response = integration_client.get(
             f"/api/v1/project/{project_name}/{package_name}/+/client-verify-test",
@@ -438,7 +438,7 @@ class TestClientSideVerification:
         project_name, package_name = test_package
         content = b"Content for Digest header verification"
 
-        upload_test_file(project_name, package_name, content, tag="digest-verify-test")
+        upload_test_file(project_name, package_name, content, version="digest-verify-test")
 
         response = integration_client.get(
             f"/api/v1/project/{project_name}/{package_name}/+/digest-verify-test",

backend/tests/unit/test_auth.py

@@ -10,7 +10,6 @@ class TestCreateDefaultAdmin:
     def test_create_default_admin_with_env_password(self):
         """Test that ORCHARD_ADMIN_PASSWORD env var sets admin password."""
         from app.auth import create_default_admin, verify_password
-        from app.models import User
 
         # Create mock settings with custom password
         mock_settings = MagicMock()
@@ -20,23 +19,20 @@ class TestCreateDefaultAdmin:
         mock_db = MagicMock()
         mock_db.query.return_value.count.return_value = 0  # No existing users
 
-        # Track all objects that get created
-        created_objects = []
+        # Track the user that gets created
+        created_user = None
 
-        def capture_object(obj):
-            created_objects.append(obj)
+        def capture_user(user):
+            nonlocal created_user
+            created_user = user
 
-        mock_db.add.side_effect = capture_object
+        mock_db.add.side_effect = capture_user
 
         with patch("app.auth.get_settings", return_value=mock_settings):
             admin = create_default_admin(mock_db)
 
-        # Verify objects were created (user, team, membership)
+        # Verify the user was created
         assert mock_db.add.called
-        assert len(created_objects) >= 1
-
-        # Find the user object
-        created_user = next((obj for obj in created_objects if isinstance(obj, User)), None)
         assert created_user is not None
         assert created_user.username == "admin"
         assert created_user.is_admin is True
@@ -48,7 +44,6 @@ class TestCreateDefaultAdmin:
     def test_create_default_admin_with_default_password(self):
         """Test that default password 'changeme123' is used when env var not set."""
         from app.auth import create_default_admin, verify_password
-        from app.models import User
 
         # Create mock settings with empty password (default)
         mock_settings = MagicMock()
@@ -58,23 +53,20 @@ class TestCreateDefaultAdmin:
         mock_db = MagicMock()
         mock_db.query.return_value.count.return_value = 0  # No existing users
 
-        # Track all objects that get created
-        created_objects = []
+        # Track the user that gets created
+        created_user = None
 
-        def capture_object(obj):
-            created_objects.append(obj)
+        def capture_user(user):
+            nonlocal created_user
+            created_user = user
 
-        mock_db.add.side_effect = capture_object
+        mock_db.add.side_effect = capture_user
 
         with patch("app.auth.get_settings", return_value=mock_settings):
             admin = create_default_admin(mock_db)
 
-        # Verify objects were created
+        # Verify the user was created
         assert mock_db.add.called
-        assert len(created_objects) >= 1
-
-        # Find the user object
-        created_user = next((obj for obj in created_objects if isinstance(obj, User)), None)
         assert created_user is not None
         assert created_user.username == "admin"
         assert created_user.is_admin is True

backend/tests/unit/test_models.py

@@ -145,54 +145,6 @@ class TestPackageModel:
         assert platform_col.default.arg == "any"
 
 
-class TestTagModel:
-    """Tests for the Tag model."""
-
-    @pytest.mark.unit
-    def test_tag_requires_package_id(self):
-        """Test tag requires package_id."""
-        from app.models import Tag
-
-        tag = Tag(
-            name="v1.0.0",
-            package_id=uuid.uuid4(),
-            artifact_id="f" * 64,
-            created_by="test-user",
-        )
-
-        assert tag.package_id is not None
-        assert tag.artifact_id == "f" * 64
-
-
-class TestTagHistoryModel:
-    """Tests for the TagHistory model."""
-
-    @pytest.mark.unit
-    def test_tag_history_default_change_type(self):
-        """Test tag history change_type column has default value of 'update'."""
-        from app.models import TagHistory
-
-        # Check the column definition has the right default
-        change_type_col = TagHistory.__table__.columns["change_type"]
-        assert change_type_col.default is not None
-        assert change_type_col.default.arg == "update"
-
-    @pytest.mark.unit
-    def test_tag_history_allows_null_old_artifact(self):
-        """Test tag history allows null old_artifact_id (for create events)."""
-        from app.models import TagHistory
-
-        history = TagHistory(
-            tag_id=uuid.uuid4(),
-            old_artifact_id=None,
-            new_artifact_id="h" * 64,
-            change_type="create",
-            changed_by="test-user",
-        )
-
-        assert history.old_artifact_id is None
-
-
 class TestUploadModel:
     """Tests for the Upload model."""
 

docs/epic-upstream-caching.md

@@ -0,0 +1,672 @@
+# Epic: Upstream Artifact Caching for Hermetic Builds
+
+## Overview
+
+Orchard will act as a permanent, content-addressable cache for upstream artifacts (npm, PyPI, Maven, Docker, etc.). Once an artifact is cached, it is stored forever by SHA256 hash - enabling reproducible builds years later regardless of whether the upstream source still exists.
+
+## Problem Statement
+
+Build reproducibility is critical for enterprise environments:
+- Packages get deleted, yanked, or modified upstream
+- Registries go down or change URLs
+- Version constraints resolve differently over time
+- Air-gapped environments cannot access public internet
+
+Teams need to guarantee that a build from 5 years ago produces the exact same output today.
+
+## Solution
+
+Orchard becomes "the cache that never forgets":
+
+1. **Fetch once, store forever** - When a build needs `lodash@4.17.21`, Orchard fetches it from npm, stores it by SHA256 hash, and never deletes it
+2. **Content-addressable** - Same hash = same bytes, guaranteed
+3. **Format-agnostic** - Orchard doesn't need to understand npm/PyPI/Maven protocols; the client provides the URL, Orchard fetches and stores
+4. **Air-gap support** - Disable public internet entirely, only allow configured private upstreams
+
+## User Workflow
+
+```
+1. Build tool resolves dependencies     npm install / pip install / mvn resolve
+                ↓
+2. Generate lockfile with URLs          package-lock.json / requirements.txt
+                ↓
+3. Cache all URLs in Orchard            orchard cache --file urls.txt
+                ↓
+4. Pin by SHA256 hash                   lodash = "sha256:abc123..."
+                ↓
+5. Future builds fetch by hash          Always get exact same bytes
+```
+
+## Key Features
+
+- **Multiple upstream sources** - Configure npm, PyPI, Maven Central, private Artifactory, etc.
+- **Per-source authentication** - Basic auth, bearer tokens, API keys
+- **System cache projects** - `_npm`, `_pypi`, `_maven` organize cached packages by format
+- **Cross-referencing** - Link cached artifacts to user projects for visibility
+- **URL tracking** - Know which URLs map to which hashes, audit provenance
+- **Air-gap mode** - Global kill switch for all public internet access
+- **Environment variable config** - 12-factor friendly for containerized deployments
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Orchard Server                          │
+├─────────────────────────────────────────────────────────────────┤
+│  POST /api/v1/cache                                             │
+│    ├── Check if URL already cached (url_hash lookup)            │
+│    ├── Match URL to upstream source (get auth)                  │
+│    ├── Fetch via UpstreamClient (stream + compute SHA256)       │
+│    ├── Store artifact in S3 (content-addressable)               │
+│    ├── Create tag in system project (_npm/lodash:4.17.21)       │
+│    ├── Optionally create tag in user project                    │
+│    └── Record in cached_urls table (provenance)                 │
+├─────────────────────────────────────────────────────────────────┤
+│  Tables                                                         │
+│    ├── upstream_sources (npm-public, pypi-public, artifactory)  │
+│    ├── cache_settings (allow_public_internet, etc.)             │
+│    ├── cached_urls (url → artifact_id mapping)                  │
+│    └── projects.is_system (for _npm, _pypi, etc.)               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Issues Summary
+
+| Issue | Title | Status | Dependencies |
+|-------|-------|--------|--------------|
+| #68 | Schema: Upstream Sources & Cache Tracking | ✅ Complete | None |
+| #69 | HTTP Client: Generic URL Fetcher | Pending | None |
+| #70 | Cache API Endpoint | Pending | #68, #69 |
+| #71 | System Projects (Cache Namespaces) | Pending | #68, #70 |
+| #72 | Upstream Sources Admin API | Pending | #68 |
+| #73 | Global Cache Settings API | Pending | #68 |
+| #74 | Environment Variable Overrides | Pending | #68, #72, #73 |
+| #75 | Frontend: Upstream Sources Management | Pending | #72, #73 |
+| #105 | Frontend: System Projects Integration | Pending | #71 |
+| #77 | CLI: Cache Command | Pending | #70 |
+
+## Implementation Phases
+
+**Phase 1 - Core (MVP):**
+- #68 Schema ✅
+- #69 HTTP Client
+- #70 Cache API
+- #71 System Projects
+
+**Phase 2 - Admin:**
+- #72 Upstream Sources API
+- #73 Cache Settings API
+- #74 Environment Variables
+
+**Phase 3 - Frontend:**
+- #75 Upstream Sources UI
+- #105 System Projects UI
+
+**Phase 4 - CLI:**
+- #77 Cache Command
+
+---
+
+# Issue #68: Schema - Upstream Sources & Cache Tracking
+
+**Status: ✅ Complete**
+
+## Description
+
+Create database schema for flexible multi-source upstream configuration and URL-to-artifact tracking. This replaces the previous singleton proxy_config design with a more flexible model supporting multiple upstream sources, air-gap mode, and provenance tracking.
+
+## Acceptance Criteria
+
+- [x] `upstream_sources` table:
+  - id (UUID, primary key)
+  - name (VARCHAR(255), unique, e.g., "npm-public", "artifactory-private")
+  - source_type (VARCHAR(50), enum: npm, pypi, maven, docker, helm, nuget, deb, rpm, generic)
+  - url (VARCHAR(2048), base URL of upstream)
+  - enabled (BOOLEAN, default false)
+  - is_public (BOOLEAN, true if this is a public internet source)
+  - auth_type (VARCHAR(20), enum: none, basic, bearer, api_key)
+  - username (VARCHAR(255), nullable)
+  - password_encrypted (BYTEA, nullable, Fernet encrypted)
+  - headers_encrypted (BYTEA, nullable, for custom headers like API keys)
+  - priority (INTEGER, default 100, lower = checked first)
+  - created_at, updated_at timestamps
+- [x] `cache_settings` table (singleton, id always 1):
+  - id (INTEGER, primary key, check id = 1)
+  - allow_public_internet (BOOLEAN, default true, air-gap kill switch)
+  - auto_create_system_projects (BOOLEAN, default true)
+  - created_at, updated_at timestamps
+- [x] `cached_urls` table:
+  - id (UUID, primary key)
+  - url (VARCHAR(4096), original URL fetched)
+  - url_hash (VARCHAR(64), SHA256 of URL for fast lookup, indexed)
+  - artifact_id (VARCHAR(64), FK to artifacts)
+  - source_id (UUID, FK to upstream_sources, nullable for manual imports)
+  - fetched_at (TIMESTAMP WITH TIME ZONE)
+  - response_headers (JSONB, original upstream headers for provenance)
+  - created_at timestamp
+- [x] Add `is_system` BOOLEAN column to projects table (default false)
+- [x] Migration SQL file in migrations/
+- [x] Runtime migration in database.py
+- [x] SQLAlchemy models for all new tables
+- [x] Pydantic schemas for API input/output (passwords write-only)
+- [x] Encryption helpers for password/headers fields
+- [x] Seed default upstream sources (disabled by default):
+  - npm-public: https://registry.npmjs.org
+  - pypi-public: https://pypi.org/simple
+  - maven-central: https://repo1.maven.org/maven2
+  - docker-hub: https://registry-1.docker.io
+- [x] Unit tests for models and schemas
+
+## Files Modified
+
+- `migrations/010_upstream_caching.sql`
+- `backend/app/database.py` (migrations 016-020)
+- `backend/app/models.py` (UpstreamSource, CacheSettings, CachedUrl, Project.is_system)
+- `backend/app/schemas.py` (all caching schemas)
+- `backend/app/encryption.py` (renamed env var)
+- `backend/app/config.py` (renamed setting)
+- `backend/tests/test_upstream_caching.py` (37 tests)
+- `frontend/src/components/Layout.tsx` (footer tagline)
+- `CHANGELOG.md`
+
+---
+
+# Issue #69: HTTP Client - Generic URL Fetcher
+
+**Status: Pending**
+
+## Description
+
+Create a reusable HTTP client for fetching artifacts from upstream sources. Supports multiple auth methods, streaming for large files, and computes SHA256 while downloading.
+
+## Acceptance Criteria
+
+- [ ] `UpstreamClient` class in `backend/app/upstream.py`
+- [ ] `fetch(url)` method that:
+  - Streams response body (doesn't load large files into memory)
+  - Computes SHA256 hash while streaming
+  - Returns file content, hash, size, and response headers
+- [ ] Auth support based on upstream source configuration:
+  - None (anonymous)
+  - Basic auth (username/password)
+  - Bearer token (Authorization: Bearer {token})
+  - API key (custom header name/value)
+- [ ] URL-to-source matching:
+  - Match URL to configured upstream source by URL prefix
+  - Apply auth from matched source
+  - Respect source priority for multiple matches
+- [ ] Configuration options:
+  - Timeout (connect and read, default 30s/300s)
+  - Max retries (default 3)
+  - Follow redirects (default true, max 5)
+  - Max file size (reject if Content-Length exceeds limit)
+- [ ] Respect `allow_public_internet` setting:
+  - If false, reject URLs matching `is_public=true` sources
+  - If false, reject URLs not matching any configured source
+- [ ] Capture response headers for provenance tracking
+- [ ] Proper error handling:
+  - Connection errors (retry with backoff)
+  - HTTP errors (4xx, 5xx)
+  - Timeout errors
+  - SSL/TLS errors
+- [ ] Logging for debugging (URL, source matched, status, timing)
+- [ ] Unit tests with mocked HTTP responses
+- [ ] Integration tests against httpbin.org or similar (optional, marked)
+
+## Technical Notes
+
+- Use `httpx` for async HTTP support (already in requirements)
+- Stream to temp file to avoid memory issues with large artifacts
+- Consider checksum verification if upstream provides it (e.g., npm provides shasum)
+
+---
+
+# Issue #70: Cache API Endpoint
+
+**Status: Pending**
+
+## Description
+
+API endpoint to cache an artifact from an upstream URL. This is the core endpoint that fetches from upstream, stores in Orchard, and creates appropriate tags.
+
+## Acceptance Criteria
+
+- [ ] `POST /api/v1/cache` endpoint
+- [ ] Request body:
+  ```json
+  {
+    "url": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
+    "source_type": "npm",
+    "package_name": "lodash",
+    "tag": "4.17.21",
+    "user_project": "my-app",
+    "user_package": "npm-deps",
+    "user_tag": "lodash-4.17.21",
+    "expected_hash": "sha256:abc123..."
+  }
+  ```
+  - `url` (required): URL to fetch
+  - `source_type` (required): Determines system project (_npm, _pypi, etc.)
+  - `package_name` (optional): Package name in system project, derived from URL if not provided
+  - `tag` (optional): Tag name in system project, derived from URL if not provided
+  - `user_project`, `user_package`, `user_tag` (optional): Cross-reference in user's project
+  - `expected_hash` (optional): Verify downloaded content matches
+- [ ] Response:
+  ```json
+  {
+    "artifact_id": "abc123...",
+    "sha256": "abc123...",
+    "size": 12345,
+    "content_type": "application/gzip",
+    "already_cached": false,
+    "source_url": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
+    "source_name": "npm-public",
+    "system_project": "_npm",
+    "system_package": "lodash",
+    "system_tag": "4.17.21",
+    "user_reference": "my-app/npm-deps:lodash-4.17.21"
+  }
+  ```
+- [ ] Behavior:
+  - Check if URL already cached (by url_hash in cached_urls)
+  - If cached: return existing artifact, optionally create user tag
+  - If not cached: fetch via UpstreamClient, store artifact, create tags
+  - Create/get system project if needed (e.g., `_npm`)
+  - Create package in system project (e.g., `_npm/lodash`)
+  - Create tag in system project (e.g., `_npm/lodash:4.17.21`)
+  - If user reference provided, create tag in user's project
+  - Record in cached_urls table with provenance
+- [ ] Error handling:
+  - 400: Invalid request (bad URL format, missing required fields)
+  - 403: Air-gap mode enabled and URL is from public source
+  - 404: Upstream returned 404
+  - 409: Hash mismatch (if expected_hash provided)
+  - 502: Upstream fetch failed (connection error, timeout)
+  - 503: Upstream source disabled
+- [ ] Authentication required (any authenticated user can cache)
+- [ ] Audit logging for cache operations
+- [ ] Integration tests covering success and error cases
+
+## Technical Notes
+
+- URL parsing for package_name/tag derivation is format-specific:
+  - npm: `/{package}/-/{package}-{version}.tgz` → package=lodash, tag=4.17.21
+  - pypi: `/packages/.../requests-2.28.0.tar.gz` → package=requests, tag=2.28.0
+  - maven: `/{group}/{artifact}/{version}/{artifact}-{version}.jar`
+- Deduplication: if same SHA256 already exists, just create new tag pointing to it
+
+---
+
+# Issue #71: System Projects (Cache Namespaces)
+
+**Status: Pending**
+
+## Description
+
+Implement auto-created system projects for organizing cached artifacts by format type. These are special projects that provide a browsable namespace for all cached upstream packages.
+
+## Acceptance Criteria
+
+- [ ] System project names: `_npm`, `_pypi`, `_maven`, `_docker`, `_helm`, `_nuget`, `_deb`, `_rpm`, `_generic`
+- [ ] Auto-creation:
+  - Created automatically on first cache request for that format
+  - Created by cache endpoint, not at startup
+  - Uses system user as creator (`created_by = "system"`)
+- [ ] System project properties:
+  - `is_system = true`
+  - `is_public = true` (readable by all authenticated users)
+  - `description` = "System cache for {format} packages"
+- [ ] Restrictions:
+  - Cannot be deleted (return 403 with message)
+  - Cannot be renamed
+  - Cannot change `is_public` to false
+  - Only admins can modify description
+- [ ] Helper function: `get_or_create_system_project(source_type)` in routes.py or new cache.py module
+- [ ] Update project deletion endpoint to check `is_system` flag
+- [ ] Update project update endpoint to enforce restrictions
+- [ ] Query helper: list all system projects for UI dropdown
+- [ ] Unit tests for restrictions
+- [ ] Integration tests for auto-creation and restrictions
+
+## Technical Notes
+
+- System projects are identified by `is_system=true`, not just naming convention
+- The `_` prefix is a convention for display purposes
+- Packages within system projects follow upstream naming (e.g., `_npm/lodash`, `_npm/@types/node`)
+
+---
+
+# Issue #72: Upstream Sources Admin API
+
+**Status: Pending**
+
+## Description
+
+CRUD API endpoints for managing upstream sources configuration. Admin-only access.
+
+## Acceptance Criteria
+
+- [ ] `GET /api/v1/admin/upstream-sources` - List all upstream sources
+  - Returns array of sources with id, name, source_type, url, enabled, is_public, auth_type, priority, has_credentials, created_at, updated_at
+  - Supports `?enabled=true/false` filter
+  - Supports `?source_type=npm,pypi` filter
+  - Passwords/tokens never returned
+- [ ] `POST /api/v1/admin/upstream-sources` - Create upstream source
+  - Request: name, source_type, url, enabled, is_public, auth_type, username, password, headers, priority
+  - Validates unique name
+  - Validates URL format
+  - Encrypts password/headers before storage
+  - Returns created source (without secrets)
+- [ ] `GET /api/v1/admin/upstream-sources/{id}` - Get source details
+  - Returns source with `has_credentials` boolean, not actual credentials
+- [ ] `PUT /api/v1/admin/upstream-sources/{id}` - Update source
+  - Partial update supported
+  - If password provided, re-encrypt; if omitted, keep existing
+  - Special value `password: null` clears credentials
+- [ ] `DELETE /api/v1/admin/upstream-sources/{id}` - Delete source
+  - Returns 400 if source has cached_urls referencing it (optional: cascade or reassign)
+- [ ] `POST /api/v1/admin/upstream-sources/{id}/test` - Test connectivity
+  - Attempts HEAD request to source URL
+  - Returns success/failure with status code and timing
+  - Does not cache anything
+- [ ] All endpoints require admin role
+- [ ] Audit logging for all mutations
+- [ ] Pydantic schemas: UpstreamSourceCreate, UpstreamSourceUpdate, UpstreamSourceResponse
+- [ ] Integration tests for all endpoints
+
+## Technical Notes
+
+- Test endpoint should respect auth configuration to verify credentials work
+- Consider adding `last_used_at` and `last_error` fields for observability (future enhancement)
+
+---
+
+# Issue #73: Global Cache Settings API
+
+**Status: Pending**
+
+## Description
+
+API endpoints for managing global cache settings including air-gap mode.
+
+## Acceptance Criteria
+
+- [ ] `GET /api/v1/admin/cache-settings` - Get current settings
+  - Returns: allow_public_internet, auto_create_system_projects, created_at, updated_at
+- [ ] `PUT /api/v1/admin/cache-settings` - Update settings
+  - Partial update supported
+  - Returns updated settings
+- [ ] Settings fields:
+  - `allow_public_internet` (boolean): When false, blocks all requests to sources marked `is_public=true`
+  - `auto_create_system_projects` (boolean): When false, system projects must be created manually
+- [ ] Admin-only access
+- [ ] Audit logging for changes (especially air-gap mode changes)
+- [ ] Pydantic schemas: CacheSettingsResponse, CacheSettingsUpdate
+- [ ] Initialize singleton row on first access if not exists
+- [ ] Integration tests
+
+## Technical Notes
+
+- Air-gap mode change should be logged prominently (security-relevant)
+- Consider requiring confirmation header for disabling air-gap mode (similar to factory reset)
+
+---
+
+# Issue #74: Environment Variable Overrides
+
+**Status: Pending**
+
+## Description
+
+Allow cache and upstream configuration via environment variables for containerized deployments. Environment variables override database settings following 12-factor app principles.
+
+## Acceptance Criteria
+
+- [ ] Global settings overrides:
+  - `ORCHARD_CACHE_ALLOW_PUBLIC_INTERNET=true/false`
+  - `ORCHARD_CACHE_AUTO_CREATE_SYSTEM_PROJECTS=true/false`
+  - `ORCHARD_CACHE_ENCRYPTION_KEY` (Fernet key for credential encryption)
+- [ ] Upstream source definition via env vars:
+  - `ORCHARD_UPSTREAM__{NAME}__URL` (double underscore as separator)
+  - `ORCHARD_UPSTREAM__{NAME}__TYPE` (npm, pypi, maven, etc.)
+  - `ORCHARD_UPSTREAM__{NAME}__ENABLED` (true/false)
+  - `ORCHARD_UPSTREAM__{NAME}__IS_PUBLIC` (true/false)
+  - `ORCHARD_UPSTREAM__{NAME}__AUTH_TYPE` (none, basic, bearer, api_key)
+  - `ORCHARD_UPSTREAM__{NAME}__USERNAME`
+  - `ORCHARD_UPSTREAM__{NAME}__PASSWORD`
+  - `ORCHARD_UPSTREAM__{NAME}__PRIORITY`
+  - Example: `ORCHARD_UPSTREAM__NPM_PRIVATE__URL=https://npm.corp.com`
+- [ ] Env var sources:
+  - Loaded at startup
+  - Merged with database sources
+  - Env var sources have `source = "env"` marker
+  - Cannot be modified via API (return 400)
+  - Cannot be deleted via API (return 400)
+- [ ] Update Settings class in config.py
+- [ ] Update get/list endpoints to include env-defined sources
+- [ ] Document all env vars in CLAUDE.md
+- [ ] Unit tests for env var parsing
+- [ ] Integration tests with env vars set
+
+## Technical Notes
+
+- Double underscore (`__`) separator allows source names with single underscores
+- Env-defined sources should appear in API responses but marked as read-only
+- Consider startup validation that warns about invalid env var combinations
+
+---
+
+# Issue #75: Frontend - Upstream Sources Management
+
+**Status: Pending**
+
+## Description
+
+Admin UI for managing upstream sources and cache settings.
+
+## Acceptance Criteria
+
+- [ ] New admin page: `/admin/cache` or `/admin/upstream-sources`
+- [ ] Upstream sources section:
+  - Table listing all sources with: name, type, URL, enabled toggle, public badge, priority, actions
+  - Visual distinction for env-defined sources (locked icon, no edit/delete)
+  - Create button opens modal/form
+  - Edit button for DB-defined sources
+  - Delete with confirmation modal
+  - Test connection button with status indicator
+- [ ] Create/edit form fields:
+  - Name (text, required)
+  - Source type (dropdown)
+  - URL (text, required)
+  - Priority (number)
+  - Is public (checkbox)
+  - Enabled (checkbox)
+  - Auth type (dropdown: none, basic, bearer, api_key)
+  - Conditional auth fields based on type:
+    - Basic: username, password
+    - Bearer: token
+    - API key: header name, header value
+  - Password fields masked, "unchanged" placeholder on edit
+- [ ] Cache settings section:
+  - Air-gap mode toggle with warning
+  - Auto-create system projects toggle
+  - "Air-gap mode" shows prominent warning banner when enabled
+- [ ] Link from main admin navigation
+- [ ] Loading and error states
+- [ ] Success/error toast notifications
+
+## Technical Notes
+
+- Use existing admin page patterns from user management
+- Air-gap toggle should require confirmation (modal with warning text)
+
+---
+
+# Issue #105: Frontend - System Projects Integration
+
+**Status: Pending**
+
+## Description
+
+Integrate system projects into the frontend UI with appropriate visual treatment and navigation.
+
+## Acceptance Criteria
+
+- [ ] Home page project dropdown:
+  - System projects shown in separate "Cached Packages" section
+  - Visual distinction (icon, different background, or badge)
+  - Format icon for each type (npm, pypi, maven, etc.)
+- [ ] Project list/grid:
+  - System projects can be filtered: "Show system projects" toggle
+  - Or separate tab: "Projects" | "Package Cache"
+- [ ] System project page:
+  - "System Cache" badge in header
+  - Description explains this is auto-managed cache
+  - Settings/delete buttons hidden or disabled
+  - Shows format type prominently
+- [ ] Package page within system project:
+  - Shows "Cached from" with source URL (linked)
+  - Shows "First cached" timestamp
+  - Shows which upstream source provided it
+- [ ] Artifact page:
+  - If artifact came from cache, show provenance:
+    - Original URL
+    - Upstream source name
+    - Fetch timestamp
+- [ ] Search includes system projects (with filter option)
+
+## Technical Notes
+
+- Use React context or query params for system project filtering
+- Consider dedicated route: `/cache/npm/lodash` as alias for `/_npm/lodash`
+
+---
+
+# Issue #77: CLI - Cache Command
+
+**Status: Pending**
+
+## Description
+
+Add a new `orchard cache` command to the existing CLI for caching artifacts from upstream URLs. This integrates with the new cache API endpoint and can optionally update `orchard.ensure` with cached artifacts.
+
+## Acceptance Criteria
+
+- [ ] New command: `orchard cache <url>` in `orchard/commands/cache.py`
+- [ ] Basic usage:
+  ```bash
+  # Cache a URL, print artifact info
+  orchard cache https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz
+
+  # Output:
+  # Caching https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz...
+  #   Source type: npm
+  #   Package: lodash
+  #   Version: 4.17.21
+  #
+  # Successfully cached artifact
+  #   Artifact ID: abc123...
+  #   Size: 1.2 MB
+  #   System project: _npm
+  #   System package: lodash
+  #   System tag: 4.17.21
+  ```
+- [ ] Options:
+  | Option | Description |
+  |--------|-------------|
+  | `--type, -t TYPE` | Source type: npm, pypi, maven, docker, helm, generic (auto-detected from URL if not provided) |
+  | `--package, -p NAME` | Package name in system project (auto-derived from URL if not provided) |
+  | `--tag TAG` | Tag name in system project (auto-derived from URL if not provided) |
+  | `--project PROJECT` | Also create tag in this user project |
+  | `--user-package PKG` | Package name in user project (required if --project specified) |
+  | `--user-tag TAG` | Tag name in user project (default: same as system tag) |
+  | `--expected-hash HASH` | Verify downloaded content matches this SHA256 |
+  | `--add` | Add to orchard.ensure after caching |
+  | `--add-path PATH` | Extraction path for --add (default: `<package>/`) |
+  | `--file, -f FILE` | Path to orchard.ensure file |
+  | `--verbose, -v` | Show detailed output |
+- [ ] URL type auto-detection:
+  - `registry.npmjs.org` → npm
+  - `pypi.org` or `files.pythonhosted.org` → pypi
+  - `repo1.maven.org` or contains `/maven2/` → maven
+  - `registry-1.docker.io` or `docker.io` → docker
+  - Otherwise → generic
+- [ ] Package/version extraction from URL patterns:
+  - npm: `/{package}/-/{package}-{version}.tgz`
+  - pypi: `/packages/.../requests-{version}.tar.gz`
+  - maven: `/{group}/{artifact}/{version}/{artifact}-{version}.jar`
+- [ ] Add `cache_artifact()` function to `orchard/api.py`
+- [ ] Integration with `--add` flag:
+  - Parse existing orchard.ensure
+  - Add new dependency entry pointing to cached artifact
+  - Use artifact_id (SHA256) for hermetic pinning
+- [ ] Batch mode: `orchard cache --file urls.txt`
+  - One URL per line
+  - Lines starting with `#` are comments
+  - Report success/failure for each
+- [ ] Exit codes:
+  - 0: Success (or already cached)
+  - 1: Fetch failed
+  - 2: Hash mismatch
+  - 3: Air-gap mode blocked request
+- [ ] Error handling consistent with existing CLI patterns
+- [ ] Unit tests in `test/test_cache.py`
+- [ ] Update README.md with cache command documentation
+
+## Technical Notes
+
+- Follow existing Click patterns from other commands
+- Use `get_auth_headers()` from `orchard/auth.py`
+- URL parsing can use `urllib.parse`
+- Consider adding URL pattern registry for extensibility
+- The `--add` flag should integrate with existing ensure file parsing in `orchard/ensure.py`
+
+## Example Workflows
+
+```bash
+# Simple: cache a single URL
+orchard cache https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz
+
+# Cache and add to orchard.ensure for current project
+orchard cache https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz \
+  --add --add-path libs/lodash/
+
+# Cache with explicit metadata
+orchard cache https://internal.corp/files/custom-lib.tar.gz \
+  --type generic \
+  --package custom-lib \
+  --tag v1.0.0
+
+# Cache and cross-reference to user project
+orchard cache https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz \
+  --project my-app \
+  --user-package npm-deps \
+  --user-tag lodash-4.17.21
+
+# Batch cache from file
+orchard cache --file deps-urls.txt
+
+# Verify hash while caching
+orchard cache https://example.com/file.tar.gz \
+  --expected-hash sha256:abc123...
+```
+
+---
+
+## Out of Scope (Future Enhancements)
+
+- Automatic transitive dependency resolution (client's responsibility)
+- Lockfile parsing (`package-lock.json`, `requirements.txt`) - stretch goal for CLI
+- Cache eviction policies (we cache forever by design)
+- Mirroring/sync between Orchard instances
+- Format-specific metadata extraction (npm package.json parsing, etc.)
+
+## Success Criteria
+
+- [ ] Can cache any URL and retrieve by SHA256 hash
+- [ ] Cached artifacts persist indefinitely
+- [ ] Air-gap mode blocks all public internet access
+- [ ] Multiple upstream sources with different auth
+- [ ] System projects organize cached packages by format
+- [ ] CLI can cache URLs and update orchard.ensure
+- [ ] Admin UI for upstream source management

docs/plans/2026-02-04-pypi-proxy-performance-design.md

@@ -0,0 +1,228 @@
+# PyPI Proxy Performance & Multi-Protocol Architecture Design
+
+**Date:** 2026-02-04
+**Status:** Approved
+**Branch:** fix/pypi-proxy-timeout
+
+## Overview
+
+Comprehensive infrastructure overhaul to address latency, throughput, and resource consumption issues in the PyPI proxy, while establishing a foundation for npm, Maven, and other package protocols.
+
+## Goals
+
+1. **Reduce latency** - Eliminate per-request connection overhead, cache aggressively
+2. **Increase throughput** - Handle hundreds of concurrent requests without degradation
+3. **Lower resource usage** - Connection pooling, efficient DB queries, proper async I/O
+4. **Enable multi-protocol** - Abstract base class ready for npm/Maven/etc.
+5. **Maintain hermetic builds** - Immutable artifact content and metadata, mutable discovery data
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         FastAPI Application                          │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
+│  │ PyPI Proxy  │  │  npm Proxy  │  │ Maven Proxy │  │   (future)  │ │
+│  │   Router    │  │   Router    │  │   Router    │  │             │ │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └─────────────┘ │
+│         │                │                │                          │
+│         └────────────────┼────────────────┘                          │
+│                          ▼                                           │
+│              ┌───────────────────────┐                               │
+│              │   PackageProxyBase    │  ← Abstract base class        │
+│              │  - check_cache()      │                               │
+│              │  - fetch_upstream()   │                               │
+│              │  - store_artifact()   │                               │
+│              │  - serve_artifact()   │                               │
+│              └───────────┬───────────┘                               │
+│                          │                                           │
+│         ┌────────────────┼────────────────┐                          │
+│         ▼                ▼                ▼                          │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                   │
+│  │ HttpClient  │  │ CacheService│  │ ThreadPool  │                   │
+│  │   Manager   │  │   (Redis)   │  │  Executor   │                   │
+│  └─────────────┘  └─────────────┘  └─────────────┘                   │
+│         │                │                │                          │
+└─────────┼────────────────┼────────────────┼──────────────────────────┘
+          ▼                ▼                ▼
+    ┌──────────┐    ┌──────────┐    ┌──────────────┐
+    │ Upstream │    │  Redis   │    │  S3/MinIO    │
+    │ Sources  │    │          │    │              │
+    └──────────┘    └──────────┘    └──────────────┘
+```
+
+## Components
+
+### 1. HttpClientManager
+
+Manages httpx.AsyncClient pools with FastAPI lifespan integration.
+
+**Features:**
+- Default pool for general requests
+- Per-upstream pools for sources needing specific config/auth
+- Graceful shutdown drains in-flight requests
+- Dedicated thread pool for blocking operations
+
+**Configuration:**
+```bash
+ORCHARD_HTTP_MAX_CONNECTIONS=100      # Default pool size
+ORCHARD_HTTP_KEEPALIVE_CONNECTIONS=20 # Keep-alive connections
+ORCHARD_HTTP_CONNECT_TIMEOUT=30       # Connection timeout (seconds)
+ORCHARD_HTTP_READ_TIMEOUT=60          # Read timeout (seconds)
+ORCHARD_HTTP_WORKER_THREADS=32        # Thread pool size
+```
+
+**File:** `backend/app/http_client.py`
+
+### 2. CacheService (Redis Layer)
+
+Redis-backed caching with category-aware TTL and invalidation.
+
+**Cache Categories:**
+
+| Category | TTL | Invalidation | Purpose |
+|----------|-----|--------------|---------|
+| ARTIFACT_METADATA | Forever | Never (immutable) | Artifact info by SHA256 |
+| ARTIFACT_DEPENDENCIES | Forever | Never (immutable) | Extracted deps by SHA256 |
+| DEPENDENCY_RESOLUTION | Forever | Manual/refresh param | Resolution results |
+| UPSTREAM_SOURCES | 1 hour | On DB change | Upstream config |
+| PACKAGE_INDEX | 5 min | TTL only | PyPI/npm index pages |
+| PACKAGE_VERSIONS | 5 min | TTL only | Version listings |
+
+**Key format:** `orchard:{category}:{protocol}:{identifier}`
+
+**Configuration:**
+```bash
+ORCHARD_REDIS_HOST=redis
+ORCHARD_REDIS_PORT=6379
+ORCHARD_REDIS_DB=0
+ORCHARD_CACHE_TTL_INDEX=300           # Package index: 5 minutes
+ORCHARD_CACHE_TTL_VERSIONS=300        # Version listings: 5 minutes
+ORCHARD_CACHE_TTL_UPSTREAM=3600       # Upstream config: 1 hour
+```
+
+**File:** `backend/app/cache_service.py`
+
+### 3. PackageProxyBase
+
+Abstract base class defining the cache→fetch→store→serve flow.
+
+**Abstract methods (protocol-specific):**
+- `get_protocol_name()` - Return 'pypi', 'npm', 'maven'
+- `get_system_project_name()` - Return '_pypi', '_npm'
+- `rewrite_index_html()` - Rewrite upstream index to Orchard URLs
+- `extract_metadata()` - Extract deps from package file
+- `parse_package_url()` - Parse URL into package/version/filename
+
+**Concrete methods (shared):**
+- `serve_index()` - Serve package index with caching
+- `serve_artifact()` - Full cache→fetch→store→serve flow
+
+**File:** `backend/app/proxy_base.py`
+
+### 4. ArtifactRepository (DB Optimization)
+
+Optimized database operations eliminating N+1 queries.
+
+**Key methods:**
+- `get_or_create_artifact()` - Atomic upsert via ON CONFLICT
+- `batch_upsert_dependencies()` - Single INSERT for all deps
+- `get_cached_url_with_artifact()` - Joined query for cache lookup
+
+**Query reduction:**
+
+| Operation | Before | After |
+|-----------|--------|-------|
+| Cache hit check | 2 queries | 1 query (joined) |
+| Store artifact | 3-4 queries | 1 query (upsert) |
+| Store 50 deps | 50+ queries | 1 query (batch) |
+
+**Configuration:**
+```bash
+ORCHARD_DATABASE_POOL_SIZE=20         # Base connections (up from 5)
+ORCHARD_DATABASE_MAX_OVERFLOW=30      # Burst capacity (up from 10)
+ORCHARD_DATABASE_POOL_TIMEOUT=30      # Wait timeout
+ORCHARD_DATABASE_POOL_PRE_PING=false  # Disable in prod for performance
+```
+
+**File:** `backend/app/db_utils.py`
+
+### 5. Dependency Resolution Caching
+
+Cache resolution results for ensure files and API queries.
+
+**Cache key:** Hash of (artifact_id, max_depth, include_optional)
+
+**Invalidation:** Manual only (immutable artifact deps mean cached resolutions stay valid)
+
+**Refresh:** `?refresh=true` parameter forces fresh resolution
+
+**File:** Updates to `backend/app/dependencies.py`
+
+### 6. FastAPI Integration
+
+Lifespan-managed infrastructure with dependency injection.
+
+**Startup:**
+1. Initialize HttpClientManager (connection pools)
+2. Initialize CacheService (Redis connection)
+3. Load upstream source configs
+
+**Shutdown:**
+1. Drain in-flight HTTP requests
+2. Close Redis connections
+3. Shutdown thread pool
+
+**Health endpoint additions:**
+- Database connection status
+- Redis ping
+- HTTP pool active/max connections
+- Thread pool active/max workers
+
+**File:** Updates to `backend/app/main.py`
+
+## Files Summary
+
+**New files:**
+- `backend/app/http_client.py` - HttpClientManager
+- `backend/app/cache_service.py` - CacheService
+- `backend/app/proxy_base.py` - PackageProxyBase
+- `backend/app/db_utils.py` - ArtifactRepository
+
+**Modified files:**
+- `backend/app/config.py` - New settings
+- `backend/app/main.py` - Lifespan integration
+- `backend/app/pypi_proxy.py` - Refactor to use base class
+- `backend/app/dependencies.py` - Resolution caching
+- `backend/app/routes.py` - Health endpoint, DI
+
+## Hermetic Build Guarantees
+
+**Immutable (cached forever):**
+- Artifact content (by SHA256)
+- Extracted dependencies for a specific artifact
+- Dependency resolution results
+
+**Mutable (TTL + event invalidation):**
+- Package index listings
+- Version discovery
+- Upstream source configuration
+
+Once an artifact is cached with SHA256 `abc123` and dependencies extracted, that data never changes.
+
+## Performance Expectations
+
+| Metric | Before | After |
+|--------|--------|-------|
+| HTTP connection setup | Per request (~100-500ms) | Pooled (~5ms) |
+| Cache hit (index page) | N/A | ~5ms (Redis) |
+| Store 50 dependencies | ~500ms (50 queries) | ~10ms (1 query) |
+| Dependency resolution (cached) | N/A | ~5ms |
+| Concurrent request capacity | ~15 (DB pool) | ~50 (configurable) |
+
+## Testing Requirements
+
+- Unit tests for each new component
+- Integration tests for full proxy flow
+- Load tests to verify pool sizing
+- Cache hit/miss verification tests

frontend/package.json

@@ -12,9 +12,12 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
+    "@types/dagre": "^0.7.53",
+    "dagre": "^0.8.5",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "react-router-dom": "6.28.0"
+    "react-router-dom": "6.28.0",
+    "reactflow": "^11.11.4"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.4.2",
@@ -34,6 +37,15 @@
     "ufo": "1.5.4",
     "rollup": "4.52.4",
     "caniuse-lite": "1.0.30001692",
-    "baseline-browser-mapping": "2.9.5"
+    "baseline-browser-mapping": "2.9.5",
+    "lodash": "4.17.21",
+    "electron-to-chromium": "1.5.72",
+    "@babel/core": "7.26.0",
+    "@babel/traverse": "7.26.4",
+    "@babel/types": "7.26.3",
+    "@babel/compat-data": "7.26.3",
+    "@babel/parser": "7.26.3",
+    "@babel/generator": "7.26.3",
+    "@babel/code-frame": "7.26.2"
   }
 }

frontend/src/App.tsx

@@ -11,6 +11,7 @@ import ChangePasswordPage from './pages/ChangePasswordPage';
 import APIKeysPage from './pages/APIKeysPage';
 import AdminUsersPage from './pages/AdminUsersPage';
 import AdminOIDCPage from './pages/AdminOIDCPage';
+import AdminCachePage from './pages/AdminCachePage';
 import ProjectSettingsPage from './pages/ProjectSettingsPage';
 import TeamsPage from './pages/TeamsPage';
 import TeamDashboardPage from './pages/TeamDashboardPage';
@@ -50,6 +51,7 @@ function AppRoutes() {
                 <Route path="/settings/api-keys" element={<APIKeysPage />} />
                 <Route path="/admin/users" element={<AdminUsersPage />} />
                 <Route path="/admin/oidc" element={<AdminOIDCPage />} />
+                <Route path="/admin/cache" element={<AdminCachePage />} />
                 <Route path="/teams" element={<TeamsPage />} />
                 <Route path="/teams/:slug" element={<TeamDashboardPage />} />
                 <Route path="/teams/:slug/settings" element={<TeamSettingsPage />} />

frontend/src/api.ts

@@ -1,14 +1,11 @@
 import {
   Project,
   Package,
-  Tag,
-  TagDetail,
-  Artifact,
   ArtifactDetail,
+  PackageArtifact,
   UploadResponse,
   PaginatedResponse,
   ListParams,
-  TagListParams,
   PackageListParams,
   ArtifactListParams,
   ProjectListParams,
@@ -42,6 +39,10 @@ import {
   TeamUpdate,
   TeamMemberCreate,
   TeamMemberUpdate,
+  UpstreamSource,
+  UpstreamSourceCreate,
+  UpstreamSourceUpdate,
+  UpstreamSourceTestResult,
 } from './types';
 
 const API_BASE = '/api/v1';
@@ -74,7 +75,13 @@ export class ForbiddenError extends ApiError {
 async function handleResponse<T>(response: Response): Promise<T> {
   if (!response.ok) {
     const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
-    const message = error.detail || `HTTP ${response.status}`;
+    // Handle detail as string or object (backend may return structured errors)
+    let message: string;
+    if (typeof error.detail === 'object') {
+      message = JSON.stringify(error.detail);
+    } else {
+      message = error.detail || `HTTP ${response.status}`;
+    }
 
     if (response.status === 401) {
       throw new UnauthorizedError(message);
@@ -230,32 +237,6 @@ export async function createPackage(projectName: string, data: { name: string; d
   return handleResponse<Package>(response);
 }
 
-// Tag API
-export async function listTags(projectName: string, packageName: string, params: TagListParams = {}): Promise<PaginatedResponse<TagDetail>> {
-  const query = buildQueryString(params as Record<string, unknown>);
-  const response = await fetch(`${API_BASE}/project/${projectName}/${packageName}/tags${query}`);
-  return handleResponse<PaginatedResponse<TagDetail>>(response);
-}
-
-export async function listTagsSimple(projectName: string, packageName: string, params: TagListParams = {}): Promise<TagDetail[]> {
-  const data = await listTags(projectName, packageName, params);
-  return data.items;
-}
-
-export async function getTag(projectName: string, packageName: string, tagName: string): Promise<TagDetail> {
-  const response = await fetch(`${API_BASE}/project/${projectName}/${packageName}/tags/${tagName}`);
-  return handleResponse<TagDetail>(response);
-}
-
-export async function createTag(projectName: string, packageName: string, data: { name: string; artifact_id: string }): Promise<Tag> {
-  const response = await fetch(`${API_BASE}/project/${projectName}/${packageName}/tags`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(data),
-  });
-  return handleResponse<Tag>(response);
-}
-
 // Artifact API
 export async function getArtifact(artifactId: string): Promise<ArtifactDetail> {
   const response = await fetch(`${API_BASE}/artifact/${artifactId}`);
@@ -266,10 +247,10 @@ export async function listPackageArtifacts(
   projectName: string,
   packageName: string,
   params: ArtifactListParams = {}
-): Promise<PaginatedResponse<Artifact & { tags: string[] }>> {
+): Promise<PaginatedResponse<PackageArtifact>> {
   const query = buildQueryString(params as Record<string, unknown>);
   const response = await fetch(`${API_BASE}/project/${projectName}/${packageName}/artifacts${query}`);
-  return handleResponse<PaginatedResponse<Artifact & { tags: string[] }>>(response);
+  return handleResponse<PaginatedResponse<PackageArtifact>>(response);
 }
 
 // Upload
@@ -277,14 +258,10 @@ export async function uploadArtifact(
   projectName: string,
   packageName: string,
   file: File,
-  tag?: string,
   version?: string
 ): Promise<UploadResponse> {
   const formData = new FormData();
   formData.append('file', file);
-  if (tag) {
-    formData.append('tag', tag);
-  }
   if (version) {
     formData.append('version', version);
   }
@@ -682,3 +659,64 @@ export async function searchUsers(query: string, limit: number = 10): Promise<Us
   });
   return handleResponse<UserSearchResult[]>(response);
 }
+
+// Upstream Sources Admin API
+export interface UpstreamSourceListParams {
+  enabled?: boolean;
+  source_type?: string;
+}
+
+export async function listUpstreamSources(params: UpstreamSourceListParams = {}): Promise<UpstreamSource[]> {
+  const query = buildQueryString(params as Record<string, unknown>);
+  const response = await fetch(`${API_BASE}/admin/upstream-sources${query}`, {
+    credentials: 'include',
+  });
+  return handleResponse<UpstreamSource[]>(response);
+}
+
+export async function createUpstreamSource(data: UpstreamSourceCreate): Promise<UpstreamSource> {
+  const response = await fetch(`${API_BASE}/admin/upstream-sources`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(data),
+    credentials: 'include',
+  });
+  return handleResponse<UpstreamSource>(response);
+}
+
+export async function getUpstreamSource(id: string): Promise<UpstreamSource> {
+  const response = await fetch(`${API_BASE}/admin/upstream-sources/${id}`, {
+    credentials: 'include',
+  });
+  return handleResponse<UpstreamSource>(response);
+}
+
+export async function updateUpstreamSource(id: string, data: UpstreamSourceUpdate): Promise<UpstreamSource> {
+  const response = await fetch(`${API_BASE}/admin/upstream-sources/${id}`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(data),
+    credentials: 'include',
+  });
+  return handleResponse<UpstreamSource>(response);
+}
+
+export async function deleteUpstreamSource(id: string): Promise<void> {
+  const response = await fetch(`${API_BASE}/admin/upstream-sources/${id}`, {
+    method: 'DELETE',
+    credentials: 'include',
+  });
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+    throw new ApiError(error.detail || `HTTP ${response.status}`, response.status);
+  }
+}
+
+export async function testUpstreamSource(id: string): Promise<UpstreamSourceTestResult> {
+  const response = await fetch(`${API_BASE}/admin/upstream-sources/${id}/test`, {
+    method: 'POST',
+    credentials: 'include',
+  });
+  return handleResponse<UpstreamSourceTestResult>(response);
+}
+

frontend/src/components/DependencyGraph.css

@@ -55,6 +55,10 @@
   font-size: 0.8125rem;
 }
 
+.missing-count {
+  color: #f59e0b;
+}
+
 .close-btn {
   background: transparent;
   border: none;
@@ -72,171 +76,115 @@
   color: var(--text-primary);
 }
 
-.dependency-graph-toolbar {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 12px 20px;
-  border-bottom: 1px solid var(--border-primary);
-  background: var(--bg-secondary);
-}
-
-.zoom-level {
-  margin-left: auto;
-  font-size: 0.8125rem;
-  color: var(--text-muted);
-  font-family: 'JetBrains Mono', monospace;
-}
-
 .dependency-graph-container {
   flex: 1;
   overflow: hidden;
   position: relative;
-  background:
-    linear-gradient(90deg, var(--border-primary) 1px, transparent 1px),
-    linear-gradient(var(--border-primary) 1px, transparent 1px);
-  background-size: 20px 20px;
-  background-position: center center;
+  background: var(--bg-primary);
 }
 
-.graph-canvas {
-  padding: 40px;
-  min-width: 100%;
-  min-height: 100%;
-  transform-origin: center center;
-  transition: transform 0.1s ease-out;
+/* React Flow Customization */
+.react-flow__background {
+  background-color: var(--bg-primary) !important;
 }
 
-/* Graph Nodes */
-.graph-node-container {
-  display: flex;
-  flex-direction: column;
-  align-items: flex-start;
+.react-flow__controls {
+  background: var(--bg-tertiary);
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-md);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
 }
 
-.graph-node {
+.react-flow__controls-button {
+  background: var(--bg-tertiary);
+  border: none;
+  border-bottom: 1px solid var(--border-primary);
+  color: var(--text-secondary);
+  width: 28px;
+  height: 28px;
+}
+
+.react-flow__controls-button:hover {
+  background: var(--bg-hover);
+  color: var(--text-primary);
+}
+
+.react-flow__controls-button:last-child {
+  border-bottom: none;
+}
+
+.react-flow__controls-button svg {
+  fill: currentColor;
+}
+
+.react-flow__attribution {
+  background: transparent !important;
+}
+
+.react-flow__attribution a {
+  color: var(--text-muted) !important;
+  font-size: 10px;
+}
+
+/* Custom Flow Nodes */
+.flow-node {
   background: var(--bg-tertiary);
   border: 2px solid var(--border-primary);
   border-radius: var(--radius-md);
   padding: 12px 16px;
-  min-width: 200px;
+  min-width: 160px;
   cursor: pointer;
   transition: all var(--transition-fast);
-  position: relative;
+  text-align: center;
 }
 
-.graph-node:hover {
+.flow-node:hover {
   border-color: var(--accent-primary);
   box-shadow: 0 4px 12px rgba(16, 185, 129, 0.2);
 }
 
-.graph-node--root {
+.flow-node--root {
   background: linear-gradient(135deg, rgba(16, 185, 129, 0.15) 0%, rgba(5, 150, 105, 0.15) 100%);
   border-color: var(--accent-primary);
 }
 
-.graph-node--hovered {
-  transform: scale(1.02);
-}
-
-.graph-node__header {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  margin-bottom: 4px;
-}
-
-.graph-node__name {
+.flow-node__name {
   font-weight: 600;
   color: var(--accent-primary);
   font-family: 'JetBrains Mono', monospace;
-  font-size: 0.875rem;
+  font-size: 0.8125rem;
+  margin-bottom: 4px;
+  word-break: break-word;
 }
 
-.graph-node__toggle {
-  background: var(--bg-hover);
-  border: 1px solid var(--border-primary);
-  border-radius: 4px;
-  width: 20px;
-  height: 20px;
+.flow-node__details {
   display: flex;
   align-items: center;
   justify-content: center;
-  cursor: pointer;
-  font-size: 0.875rem;
-  color: var(--text-secondary);
-  font-weight: 600;
-  margin-left: auto;
-}
-
-.graph-node__toggle:hover {
-  background: var(--bg-tertiary);
-  color: var(--text-primary);
-}
-
-.graph-node__details {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  font-size: 0.75rem;
+  gap: 8px;
+  font-size: 0.6875rem;
   color: var(--text-muted);
 }
 
-.graph-node__version {
+.flow-node__version {
   font-family: 'JetBrains Mono', monospace;
   color: var(--text-secondary);
 }
 
-.graph-node__size {
+.flow-node__size {
   color: var(--text-muted);
 }
 
-/* Graph Children / Tree Structure */
-.graph-children {
-  display: flex;
-  padding-left: 24px;
-  margin-top: 8px;
-  position: relative;
+/* Flow Handles (connection points) */
+.flow-handle {
+  width: 8px !important;
+  height: 8px !important;
+  background: var(--border-primary) !important;
+  border: 2px solid var(--bg-tertiary) !important;
 }
 
-.graph-connector {
-  position: absolute;
-  left: 12px;
-  top: 0;
-  bottom: 50%;
-  width: 12px;
-  border-left: 2px solid var(--border-primary);
-  border-bottom: 2px solid var(--border-primary);
-  border-bottom-left-radius: 8px;
-}
-
-.graph-children-list {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  position: relative;
-}
-
-.graph-children-list::before {
-  content: '';
-  position: absolute;
-  left: -12px;
-  top: 20px;
-  bottom: 20px;
-  border-left: 2px solid var(--border-primary);
-}
-
-.graph-children-list > .graph-node-container {
-  position: relative;
-}
-
-.graph-children-list > .graph-node-container::before {
-  content: '';
-  position: absolute;
-  left: -12px;
-  top: 20px;
-  width: 12px;
-  border-top: 2px solid var(--border-primary);
+.flow-node:hover .flow-handle {
+  background: var(--accent-primary) !important;
 }
 
 /* Loading, Error, Empty States */
@@ -279,39 +227,61 @@
   line-height: 1.5;
 }
 
-/* Tooltip */
-.graph-tooltip {
-  position: fixed;
-  bottom: 24px;
-  left: 50%;
-  transform: translateX(-50%);
-  background: var(--bg-tertiary);
-  border: 1px solid var(--border-primary);
-  border-radius: var(--radius-md);
-  padding: 12px 16px;
-  font-size: 0.8125rem;
-  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
-  z-index: 1001;
-}
-
-.graph-tooltip strong {
-  display: block;
-  color: var(--accent-primary);
-  font-family: 'JetBrains Mono', monospace;
-  margin-bottom: 4px;
-}
-
-.graph-tooltip div {
-  color: var(--text-secondary);
-  margin-top: 2px;
-}
-
-.tooltip-hint {
-  margin-top: 8px;
-  padding-top: 8px;
+/* Missing Dependencies */
+.missing-dependencies {
   border-top: 1px solid var(--border-primary);
-  color: var(--text-muted);
+  padding: 16px 20px;
+  background: rgba(245, 158, 11, 0.05);
+  max-height: 200px;
+  overflow-y: auto;
+}
+
+.missing-dependencies h3 {
+  margin: 0 0 8px 0;
+  font-size: 0.875rem;
+  font-weight: 600;
+  color: #f59e0b;
+}
+
+.missing-hint {
+  margin: 0 0 12px 0;
   font-size: 0.75rem;
+  color: var(--text-muted);
+}
+
+.missing-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.missing-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  background: var(--bg-tertiary);
+  border: 1px solid rgba(245, 158, 11, 0.3);
+  border-radius: var(--radius-sm);
+  padding: 4px 8px;
+  font-size: 0.75rem;
+}
+
+.missing-name {
+  font-family: 'JetBrains Mono', monospace;
+  color: var(--text-secondary);
+}
+
+.missing-constraint {
+  color: var(--text-muted);
+  font-family: 'JetBrains Mono', monospace;
+}
+
+.missing-required-by {
+  color: var(--text-muted);
+  font-size: 0.6875rem;
 }
 
 /* Responsive */

frontend/src/components/DependencyGraph.tsx

@@ -1,5 +1,19 @@
-import { useState, useEffect, useCallback, useRef } from 'react';
+import { useState, useEffect, useCallback, useMemo } from 'react';
 import { useNavigate } from 'react-router-dom';
+import ReactFlow, {
+  Node,
+  Edge,
+  Controls,
+  Background,
+  useNodesState,
+  useEdgesState,
+  MarkerType,
+  NodeProps,
+  Handle,
+  Position,
+} from 'reactflow';
+import dagre from 'dagre';
+import 'reactflow/dist/style.css';
 import { ResolvedArtifact, DependencyResolutionResponse, Dependency } from '../types';
 import { resolveDependencies, getArtifactDependencies } from '../api';
 import './DependencyGraph.css';
@@ -11,15 +25,14 @@ interface DependencyGraphProps {
   onClose: () => void;
 }
 
-interface GraphNode {
-  id: string;
+interface NodeData {
+  label: string;
   project: string;
   package: string;
   version: string | null;
   size: number;
-  depth: number;
-  children: GraphNode[];
-  isRoot?: boolean;
+  isRoot: boolean;
+  onNavigate: (project: string, pkg: string) => void;
 }
 
 function formatBytes(bytes: number): string {
@@ -30,29 +43,89 @@ function formatBytes(bytes: number): string {
   return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
 }
 
+// Custom node component
+function DependencyNode({ data }: NodeProps<NodeData>) {
+  return (
+    <div
+      className={`flow-node ${data.isRoot ? 'flow-node--root' : ''}`}
+      onClick={() => data.onNavigate(data.project, data.package)}
+    >
+      <Handle type="target" position={Position.Top} className="flow-handle" />
+      <div className="flow-node__name">{data.package}</div>
+      <div className="flow-node__details">
+        {data.version && <span className="flow-node__version">{data.version}</span>}
+        <span className="flow-node__size">{formatBytes(data.size)}</span>
+      </div>
+      <Handle type="source" position={Position.Bottom} className="flow-handle" />
+    </div>
+  );
+}
+
+const nodeTypes = { dependency: DependencyNode };
+
+// Dagre layout function
+function getLayoutedElements(
+  nodes: Node<NodeData>[],
+  edges: Edge[],
+  direction: 'TB' | 'LR' = 'TB'
+) {
+  const dagreGraph = new dagre.graphlib.Graph();
+  dagreGraph.setDefaultEdgeLabel(() => ({}));
+
+  const nodeWidth = 180;
+  const nodeHeight = 60;
+
+  dagreGraph.setGraph({ rankdir: direction, nodesep: 50, ranksep: 80 });
+
+  nodes.forEach((node) => {
+    dagreGraph.setNode(node.id, { width: nodeWidth, height: nodeHeight });
+  });
+
+  edges.forEach((edge) => {
+    dagreGraph.setEdge(edge.source, edge.target);
+  });
+
+  dagre.layout(dagreGraph);
+
+  const layoutedNodes = nodes.map((node) => {
+    const nodeWithPosition = dagreGraph.node(node.id);
+    return {
+      ...node,
+      position: {
+        x: nodeWithPosition.x - nodeWidth / 2,
+        y: nodeWithPosition.y - nodeHeight / 2,
+      },
+    };
+  });
+
+  return { nodes: layoutedNodes, edges };
+}
+
 function DependencyGraph({ projectName, packageName, tagName, onClose }: DependencyGraphProps) {
   const navigate = useNavigate();
-  const containerRef = useRef<HTMLDivElement>(null);
 
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [resolution, setResolution] = useState<DependencyResolutionResponse | null>(null);
-  const [graphRoot, setGraphRoot] = useState<GraphNode | null>(null);
-  const [hoveredNode, setHoveredNode] = useState<GraphNode | null>(null);
-  const [zoom, setZoom] = useState(1);
-  const [pan, setPan] = useState({ x: 0, y: 0 });
-  const [isDragging, setIsDragging] = useState(false);
-  const [dragStart, setDragStart] = useState({ x: 0, y: 0 });
-  const [collapsedNodes, setCollapsedNodes] = useState<Set<string>>(new Set());
+  const [nodes, setNodes, onNodesChange] = useNodesState<NodeData>([]);
+  const [edges, setEdges, onEdgesChange] = useEdgesState([]);
+
+  const handleNavigate = useCallback((project: string, pkg: string) => {
+    navigate(`/project/${project}/${pkg}`);
+    onClose();
+  }, [navigate, onClose]);
 
   // Build graph structure from resolution data
-  const buildGraph = useCallback(async (resolutionData: DependencyResolutionResponse) => {
+  const buildFlowGraph = useCallback(async (
+    resolutionData: DependencyResolutionResponse,
+    onNavigate: (project: string, pkg: string) => void
+  ) => {
     const artifactMap = new Map<string, ResolvedArtifact>();
     resolutionData.resolved.forEach(artifact => {
       artifactMap.set(artifact.artifact_id, artifact);
     });
 
-    // Fetch dependencies for each artifact to build the tree
+    // Fetch dependencies for each artifact
     const depsMap = new Map<string, Dependency[]>();
 
     for (const artifact of resolutionData.resolved) {
@@ -64,50 +137,82 @@ function DependencyGraph({ projectName, packageName, tagName, onClose }: Depende
       }
     }
 
-    // Find the root artifact (the requested one)
+    // Find the root artifact
     const rootArtifact = resolutionData.resolved.find(
       a => a.project === resolutionData.requested.project &&
            a.package === resolutionData.requested.package
     );
 
     if (!rootArtifact) {
-      return null;
+      return { nodes: [], edges: [] };
     }
 
-    // Build tree recursively
+    const flowNodes: Node<NodeData>[] = [];
+    const flowEdges: Edge[] = [];
     const visited = new Set<string>();
+    const nodeIdMap = new Map<string, string>(); // artifact_id -> node id
+
+    // Build nodes and edges recursively
+    const processNode = (artifact: ResolvedArtifact, isRoot: boolean) => {
+      if (visited.has(artifact.artifact_id)) {
+        return nodeIdMap.get(artifact.artifact_id);
+      }
 
-    const buildNode = (artifact: ResolvedArtifact, depth: number): GraphNode => {
-      const nodeId = `${artifact.project}/${artifact.package}`;
       visited.add(artifact.artifact_id);
+      const nodeId = `node-${flowNodes.length}`;
+      nodeIdMap.set(artifact.artifact_id, nodeId);
+
+      flowNodes.push({
+        id: nodeId,
+        type: 'dependency',
+        position: { x: 0, y: 0 }, // Will be set by dagre
+        data: {
+          label: `${artifact.project}/${artifact.package}`,
+          project: artifact.project,
+          package: artifact.package,
+          version: artifact.version,
+          size: artifact.size,
+          isRoot,
+          onNavigate,
+        },
+      });
 
       const deps = depsMap.get(artifact.artifact_id) || [];
-      const children: GraphNode[] = [];
 
       for (const dep of deps) {
-        // Find the resolved artifact for this dependency
         const childArtifact = resolutionData.resolved.find(
           a => a.project === dep.project && a.package === dep.package
         );
 
-        if (childArtifact && !visited.has(childArtifact.artifact_id)) {
-          children.push(buildNode(childArtifact, depth + 1));
+        if (childArtifact) {
+          const childNodeId = processNode(childArtifact, false);
+          if (childNodeId) {
+            flowEdges.push({
+              id: `edge-${nodeId}-${childNodeId}`,
+              source: nodeId,
+              target: childNodeId,
+              markerEnd: {
+                type: MarkerType.ArrowClosed,
+                width: 15,
+                height: 15,
+                color: 'var(--accent-primary)',
+              },
+              style: {
+                stroke: 'var(--border-primary)',
+                strokeWidth: 2,
+              },
+            });
+          }
         }
       }
 
-      return {
-        id: nodeId,
-        project: artifact.project,
-        package: artifact.package,
-        version: artifact.version || artifact.tag,
-        size: artifact.size,
-        depth,
-        children,
-        isRoot: depth === 0,
-      };
+      return nodeId;
     };
 
-    return buildNode(rootArtifact, 0);
+    processNode(rootArtifact, true);
+
+    // Apply dagre layout
+    return getLayoutedElements(flowNodes, flowEdges);
   }, []);
 
   useEffect(() => {
@@ -117,13 +222,21 @@ function DependencyGraph({ projectName, packageName, tagName, onClose }: Depende
 
       try {
         const result = await resolveDependencies(projectName, packageName, tagName);
+
+        // If only the root package (no dependencies) and no missing deps, close the modal
+        const hasDeps = result.artifact_count > 1 || (result.missing && result.missing.length > 0);
+        if (!hasDeps) {
+          onClose();
+          return;
+        }
+
         setResolution(result);
 
-        const graph = await buildGraph(result);
-        setGraphRoot(graph);
+        const { nodes: layoutedNodes, edges: layoutedEdges } = await buildFlowGraph(result, handleNavigate);
+        setNodes(layoutedNodes);
+        setEdges(layoutedEdges);
       } catch (err) {
         if (err instanceof Error) {
-          // Check if it's a resolution error
           try {
             const errorData = JSON.parse(err.message);
             if (errorData.error === 'circular_dependency') {
@@ -145,95 +258,9 @@ function DependencyGraph({ projectName, packageName, tagName, onClose }: Depende
     }
 
     loadData();
-  }, [projectName, packageName, tagName, buildGraph]);
+  }, [projectName, packageName, tagName, buildFlowGraph, handleNavigate, onClose, setNodes, setEdges]);
 
-  const handleNodeClick = (node: GraphNode) => {
-    navigate(`/project/${node.project}/${node.package}`);
-    onClose();
-  };
-
-  const handleNodeToggle = (node: GraphNode, e: React.MouseEvent) => {
-    e.stopPropagation();
-    setCollapsedNodes(prev => {
-      const next = new Set(prev);
-      if (next.has(node.id)) {
-        next.delete(node.id);
-      } else {
-        next.add(node.id);
-      }
-      return next;
-    });
-  };
-
-  const handleWheel = (e: React.WheelEvent) => {
-    e.preventDefault();
-    const delta = e.deltaY > 0 ? -0.1 : 0.1;
-    setZoom(z => Math.max(0.25, Math.min(2, z + delta)));
-  };
-
-  const handleMouseDown = (e: React.MouseEvent) => {
-    if (e.target === containerRef.current || (e.target as HTMLElement).classList.contains('graph-canvas')) {
-      setIsDragging(true);
-      setDragStart({ x: e.clientX - pan.x, y: e.clientY - pan.y });
-    }
-  };
-
-  const handleMouseMove = (e: React.MouseEvent) => {
-    if (isDragging) {
-      setPan({ x: e.clientX - dragStart.x, y: e.clientY - dragStart.y });
-    }
-  };
-
-  const handleMouseUp = () => {
-    setIsDragging(false);
-  };
-
-  const resetView = () => {
-    setZoom(1);
-    setPan({ x: 0, y: 0 });
-  };
-
-  const renderNode = (node: GraphNode, index: number = 0): JSX.Element => {
-    const isCollapsed = collapsedNodes.has(node.id);
-    const hasChildren = node.children.length > 0;
-
-    return (
-      <div key={`${node.id}-${index}`} className="graph-node-container">
-        <div
-          className={`graph-node ${node.isRoot ? 'graph-node--root' : ''} ${hoveredNode?.id === node.id ? 'graph-node--hovered' : ''}`}
-          onClick={() => handleNodeClick(node)}
-          onMouseEnter={() => setHoveredNode(node)}
-          onMouseLeave={() => setHoveredNode(null)}
-        >
-          <div className="graph-node__header">
-            <span className="graph-node__name">{node.project}/{node.package}</span>
-            {hasChildren && (
-              <button
-                className="graph-node__toggle"
-                onClick={(e) => handleNodeToggle(node, e)}
-                title={isCollapsed ? 'Expand' : 'Collapse'}
-              >
-                {isCollapsed ? '+' : '-'}
-              </button>
-            )}
-          </div>
-          <div className="graph-node__details">
-            {node.version && <span className="graph-node__version">@ {node.version}</span>}
-            <span className="graph-node__size">{formatBytes(node.size)}</span>
-          </div>
-        </div>
-
-        {hasChildren && !isCollapsed && (
-          <div className="graph-children">
-            <div className="graph-connector"></div>
-            <div className="graph-children-list">
-              {node.children.map((child, i) => renderNode(child, i))}
-            </div>
-          </div>
-        )}
-      </div>
-    );
-  };
+  const defaultViewport = useMemo(() => ({ x: 50, y: 50, zoom: 0.8 }), []);
 
   return (
     <div className="dependency-graph-modal" onClick={onClose}>
@@ -244,7 +271,11 @@ function DependencyGraph({ projectName, packageName, tagName, onClose }: Depende
             <span>{projectName}/{packageName} @ {tagName}</span>
             {resolution && (
               <span className="graph-stats">
-                {resolution.artifact_count} packages • {formatBytes(resolution.total_size)} total
+                {resolution.artifact_count} cached
+                {resolution.missing && resolution.missing.length > 0 && (
+                  <span className="missing-count"> • {resolution.missing.length} not cached</span>
+                )}
+                 • {formatBytes(resolution.total_size)} total
               </span>
             )}
           </div>
@@ -256,28 +287,7 @@ function DependencyGraph({ projectName, packageName, tagName, onClose }: Depende
           </button>
         </div>
 
-        <div className="dependency-graph-toolbar">
-          <button className="btn btn-secondary btn-small" onClick={() => setZoom(z => Math.min(2, z + 0.25))}>
-            Zoom In
-          </button>
-          <button className="btn btn-secondary btn-small" onClick={() => setZoom(z => Math.max(0.25, z - 0.25))}>
-            Zoom Out
-          </button>
-          <button className="btn btn-secondary btn-small" onClick={resetView}>
-            Reset View
-          </button>
-          <span className="zoom-level">{Math.round(zoom * 100)}%</span>
-        </div>
-
-        <div
-          ref={containerRef}
-          className="dependency-graph-container"
-          onWheel={handleWheel}
-          onMouseDown={handleMouseDown}
-          onMouseMove={handleMouseMove}
-          onMouseUp={handleMouseUp}
-          onMouseLeave={handleMouseUp}
-        >
+        <div className="dependency-graph-container">
           {loading ? (
             <div className="graph-loading">
               <div className="spinner"></div>
@@ -292,27 +302,41 @@ function DependencyGraph({ projectName, packageName, tagName, onClose }: Depende
               </svg>
               <p>{error}</p>
             </div>
-          ) : graphRoot ? (
-            <div
-              className="graph-canvas"
-              style={{
-                transform: `translate(${pan.x}px, ${pan.y}px) scale(${zoom})`,
-                cursor: isDragging ? 'grabbing' : 'grab',
-              }}
+          ) : nodes.length > 0 ? (
+            <ReactFlow
+              nodes={nodes}
+              edges={edges}
+              onNodesChange={onNodesChange}
+              onEdgesChange={onEdgesChange}
+              nodeTypes={nodeTypes}
+              defaultViewport={defaultViewport}
+              fitView
+              fitViewOptions={{ padding: 0.2 }}
+              minZoom={0.1}
+              maxZoom={2}
+              attributionPosition="bottom-left"
             >
-              {renderNode(graphRoot)}
-            </div>
+              <Controls />
+              <Background color="var(--border-primary)" gap={20} />
+            </ReactFlow>
           ) : (
             <div className="graph-empty">No dependencies to display</div>
           )}
         </div>
 
-        {hoveredNode && (
-          <div className="graph-tooltip">
-            <strong>{hoveredNode.project}/{hoveredNode.package}</strong>
-            {hoveredNode.version && <div>Version: {hoveredNode.version}</div>}
-            <div>Size: {formatBytes(hoveredNode.size)}</div>
-            <div className="tooltip-hint">Click to navigate</div>
+        {resolution && resolution.missing && resolution.missing.length > 0 && (
+          <div className="missing-dependencies">
+            <h3>Not Cached ({resolution.missing.length})</h3>
+            <p className="missing-hint">These dependencies are referenced but not yet cached on the server.</p>
+            <ul className="missing-list">
+              {resolution.missing.map((dep, i) => (
+                <li key={i} className="missing-item">
+                  <span className="missing-name">{dep.project}/{dep.package}</span>
+                  {dep.constraint && <span className="missing-constraint">@{dep.constraint}</span>}
+                  {dep.required_by && <span className="missing-required-by">← {dep.required_by}</span>}
+                </li>
+              ))}
+            </ul>
           </div>
         )}
       </div>

frontend/src/components/DragDropUpload.css

@@ -290,20 +290,25 @@
   color: var(--error-color, #dc3545);
 }
 
-/* Progress Bar */
-.progress-bar {
+/* Progress Bar - scoped to upload component */
+.drag-drop-upload .progress-bar,
+.upload-queue .progress-bar {
   height: 8px;
   background: var(--border-color, #ddd);
   border-radius: 4px;
   overflow: hidden;
+  width: 100%;
+  max-width: 100%;
 }
 
-.progress-bar--small {
+.drag-drop-upload .progress-bar--small,
+.upload-queue .progress-bar--small {
   height: 4px;
   margin-top: 0.25rem;
 }
 
-.progress-bar__fill {
+.drag-drop-upload .progress-bar__fill,
+.upload-queue .progress-bar__fill {
   height: 100%;
   background: var(--accent-color, #007bff);
   border-radius: 4px;

frontend/src/components/DragDropUpload.test.tsx

@@ -504,42 +504,4 @@ describe('DragDropUpload', () => {
       });
     });
   });
-
-  describe('Tag Support', () => {
-    it('includes tag in upload request', async () => {
-      let capturedFormData: FormData | null = null;
-      
-      class MockXHR {
-        status = 200;
-        responseText = JSON.stringify({ artifact_id: 'abc123', size: 100 });
-        timeout = 0;
-        upload = { addEventListener: vi.fn() };
-        addEventListener = vi.fn((event: string, handler: () => void) => {
-          if (event === 'load') setTimeout(handler, 10);
-        });
-        open = vi.fn();
-        send = vi.fn((data: FormData) => {
-          capturedFormData = data;
-        });
-      }
-      vi.stubGlobal('XMLHttpRequest', MockXHR);
-      
-      render(<DragDropUpload {...defaultProps} tag="v1.0.0" />);
-      
-      const input = document.querySelector('input[type="file"]') as HTMLInputElement;
-      const file = createMockFile('test.txt', 100, 'text/plain');
-      
-      Object.defineProperty(input, 'files', {
-        value: Object.assign([file], { item: (i: number) => [file][i] }),
-      });
-      
-      fireEvent.change(input);
-      
-      await vi.advanceTimersByTimeAsync(100);
-      
-      await waitFor(() => {
-        expect(capturedFormData?.get('tag')).toBe('v1.0.0');
-      });
-    });
-  });
 });

frontend/src/components/DragDropUpload.tsx

@@ -13,7 +13,6 @@ interface StoredUploadState {
   completedParts: number[];
   project: string;
   package: string;
-  tag?: string;
   createdAt: number;
 }
 
@@ -87,7 +86,6 @@ export interface DragDropUploadProps {
   maxFileSize?: number; // in bytes
   maxConcurrentUploads?: number;
   maxRetries?: number;
-  tag?: string;
   className?: string;
   disabled?: boolean;
   disabledReason?: string;
@@ -230,7 +228,6 @@ export function DragDropUpload({
   maxFileSize,
   maxConcurrentUploads = 3,
   maxRetries = 3,
-  tag,
   className = '',
   disabled = false,
   disabledReason,
@@ -368,7 +365,6 @@ export function DragDropUpload({
             expected_hash: fileHash,
             filename: item.file.name,
             size: item.file.size,
-            tag: tag || undefined,
           }),
         }
       );
@@ -392,7 +388,6 @@ export function DragDropUpload({
         completedParts: [],
         project: projectName,
         package: packageName,
-        tag: tag || undefined,
         createdAt: Date.now(),
       });
 
@@ -438,7 +433,6 @@ export function DragDropUpload({
         completedParts,
         project: projectName,
         package: packageName,
-        tag: tag || undefined,
         createdAt: Date.now(),
       });
 
@@ -459,7 +453,7 @@ export function DragDropUpload({
       {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ tag: tag || undefined }),
+        body: JSON.stringify({}),
       }
     );
 
@@ -475,7 +469,7 @@ export function DragDropUpload({
       size: completeData.size,
       deduplicated: false,
     };
-  }, [projectName, packageName, tag, isOnline]);
+  }, [projectName, packageName, isOnline]);
 
   const uploadFileSimple = useCallback((item: UploadItem): Promise<UploadResult> => {
     return new Promise((resolve, reject) => {
@@ -484,9 +478,6 @@ export function DragDropUpload({
 
       const formData = new FormData();
       formData.append('file', item.file);
-      if (tag) {
-        formData.append('tag', tag);
-      }
 
       let lastLoaded = 0;
       let lastTime = Date.now();
@@ -555,7 +546,7 @@ export function DragDropUpload({
           : u
       ));
     });
-  }, [projectName, packageName, tag]);
+  }, [projectName, packageName]);
 
   const uploadFile = useCallback((item: UploadItem): Promise<UploadResult> => {
     if (item.file.size >= CHUNKED_UPLOAD_THRESHOLD) {

frontend/src/components/GlobalSearch.tsx

@@ -233,7 +233,7 @@ export function GlobalSearch() {
                     const flatIndex = results.projects.length + results.packages.length + index;
                     return (
                       <button
-                        key={artifact.tag_id}
+                        key={artifact.artifact_id}
                         className={`global-search__result ${selectedIndex === flatIndex ? 'selected' : ''}`}
                         onClick={() => navigateToResult({ type: 'artifact', item: artifact })}
                         onMouseEnter={() => setSelectedIndex(flatIndex)}
@@ -243,7 +243,7 @@ export function GlobalSearch() {
                           <line x1="7" y1="7" x2="7.01" y2="7" />
                         </svg>
                         <div className="global-search__result-content">
-                          <span className="global-search__result-name">{artifact.tag_name}</span>
+                          <span className="global-search__result-name">{artifact.version}</span>
                           <span className="global-search__result-path">
                             {artifact.project_name} / {artifact.package_name}
                           </span>

frontend/src/components/Layout.css

@@ -272,7 +272,7 @@
 .footer {
   background: var(--bg-secondary);
   border-top: 1px solid var(--border-primary);
-  padding: 24px 0;
+  padding: 12px 0;
 }
 
 .footer-content {

frontend/src/components/Layout.tsx

@@ -84,29 +84,6 @@ function Layout({ children }: LayoutProps) {
               </svg>
               Projects
             </Link>
-            <Link to="/dashboard" className={location.pathname === '/dashboard' ? 'active' : ''}>
-              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
-                <rect x="3" y="3" width="7" height="7" rx="1"/>
-                <rect x="14" y="3" width="7" height="7" rx="1"/>
-                <rect x="3" y="14" width="7" height="7" rx="1"/>
-                <rect x="14" y="14" width="7" height="7" rx="1"/>
-              </svg>
-              Dashboard
-            </Link>
-            {user && userTeams.length > 0 && (
-              <Link
-                to={userTeams.length === 1 ? `/teams/${userTeams[0].slug}` : '/teams'}
-                className={location.pathname.startsWith('/teams') ? 'active' : ''}
-              >
-                <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
-                  <path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"/>
-                  <circle cx="9" cy="7" r="4"/>
-                  <path d="M23 21v-2a4 4 0 0 0-3-3.87"/>
-                  <path d="M16 3.13a4 4 0 0 1 0 7.75"/>
-                </svg>
-                {userTeams.length === 1 ? 'Team' : 'Teams'}
-              </Link>
-            )}
             <a href="/docs" className="nav-link-muted">
               <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
                 <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/>
@@ -148,6 +125,35 @@ function Layout({ children }: LayoutProps) {
                       )}
                     </div>
                     <div className="user-menu-divider"></div>
+                    <NavLink
+                      to="/dashboard"
+                      className="user-menu-item"
+                      onClick={() => setShowUserMenu(false)}
+                    >
+                      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                        <rect x="3" y="3" width="7" height="7" rx="1"/>
+                        <rect x="14" y="3" width="7" height="7" rx="1"/>
+                        <rect x="3" y="14" width="7" height="7" rx="1"/>
+                        <rect x="14" y="14" width="7" height="7" rx="1"/>
+                      </svg>
+                      Dashboard
+                    </NavLink>
+                    {userTeams.length > 0 && (
+                      <NavLink
+                        to={userTeams.length === 1 ? `/teams/${userTeams[0].slug}` : '/teams'}
+                        className="user-menu-item"
+                        onClick={() => setShowUserMenu(false)}
+                      >
+                        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                          <path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"/>
+                          <circle cx="9" cy="7" r="4"/>
+                          <path d="M23 21v-2a4 4 0 0 0-3-3.87"/>
+                          <path d="M16 3.13a4 4 0 0 1 0 7.75"/>
+                        </svg>
+                        {userTeams.length === 1 ? 'Team' : 'Teams'}
+                      </NavLink>
+                    )}
+                    <div className="user-menu-divider"></div>
                     <NavLink
                       to="/settings/api-keys"
                       className="user-menu-item"
@@ -183,6 +189,18 @@ function Layout({ children }: LayoutProps) {
                           </svg>
                           SSO Configuration
                         </NavLink>
+                        <NavLink
+                          to="/admin/cache"
+                          className="user-menu-item"
+                          onClick={() => setShowUserMenu(false)}
+                        >
+                          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                            <path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z"/>
+                            <polyline points="3.27 6.96 12 12.01 20.73 6.96"/>
+                            <line x1="12" y1="22.08" x2="12" y2="12"/>
+                          </svg>
+                          Cache Management
+                        </NavLink>
                       </>
                     )}
                     <div className="user-menu-divider"></div>
@@ -229,7 +247,7 @@ function Layout({ children }: LayoutProps) {
             </svg>
             <span className="footer-logo">Orchard</span>
             <span className="footer-separator">·</span>
-            <span className="footer-tagline">Content-Addressable Storage</span>
+            <span className="footer-tagline">The cache that never forgets</span>
           </div>
           <div className="footer-links">
             <a href="/docs">Documentation</a>

frontend/src/pages/AdminCachePage.css

@@ -0,0 +1,377 @@
+.admin-cache-page {
+  padding: 2rem;
+  max-width: 1400px;
+  margin: 0 auto;
+}
+
+.admin-cache-page h1 {
+  margin-bottom: 2rem;
+  color: var(--text-primary);
+}
+
+.admin-cache-page h2 {
+  margin-bottom: 1rem;
+  color: var(--text-primary);
+  font-size: 1.25rem;
+}
+
+/* Success/Error Messages */
+.success-message {
+  padding: 0.75rem 1rem;
+  background-color: #d4edda;
+  border: 1px solid #c3e6cb;
+  border-radius: 4px;
+  color: #155724;
+  margin-bottom: 1rem;
+}
+
+.error-message {
+  padding: 0.75rem 1rem;
+  background-color: #f8d7da;
+  border: 1px solid #f5c6cb;
+  border-radius: 4px;
+  color: #721c24;
+  margin-bottom: 1rem;
+}
+
+/* Sources Section */
+.sources-section {
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-color);
+  border-radius: 8px;
+  padding: 1.5rem;
+}
+
+.section-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 1rem;
+}
+
+.section-header h2 {
+  margin: 0;
+}
+
+/* Sources Table */
+.sources-table {
+  width: 100%;
+  border-collapse: collapse;
+  background: var(--bg-primary);
+  border-radius: 4px;
+  overflow: hidden;
+}
+
+.sources-table th,
+.sources-table td {
+  padding: 0.75rem 1rem;
+  text-align: center;
+  border-bottom: 1px solid var(--border-color);
+}
+
+.sources-table th {
+  background: var(--bg-tertiary);
+  font-weight: 600;
+  color: var(--text-secondary);
+  font-size: 0.85rem;
+  text-transform: uppercase;
+}
+
+.sources-table tr:last-child td {
+  border-bottom: none;
+}
+
+.sources-table tr.disabled-row {
+  opacity: 0.6;
+}
+
+.source-name {
+  font-weight: 500;
+  color: var(--text-primary);
+  white-space: nowrap;
+}
+
+/* Name column should be left-aligned */
+.sources-table td:first-child {
+  text-align: left;
+}
+
+.url-cell {
+  font-family: monospace;
+  font-size: 0.9rem;
+  max-width: 300px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  text-align: left;
+}
+
+/* Badges */
+.env-badge,
+.status-badge {
+  display: inline-block;
+  padding: 0.2rem 0.5rem;
+  border-radius: 4px;
+  font-size: 0.75rem;
+  font-weight: 500;
+  margin-left: 0.5rem;
+}
+
+.env-badge {
+  background-color: #fff3e0;
+  color: #e65100;
+}
+
+.status-badge.enabled {
+  background-color: #e8f5e9;
+  color: #2e7d32;
+}
+
+.status-badge.disabled {
+  background-color: #ffebee;
+  color: #c62828;
+}
+
+.coming-soon-badge {
+  color: #9e9e9e;
+  font-style: italic;
+  font-size: 0.85em;
+}
+
+/* Actions */
+.actions-cell {
+  white-space: nowrap;
+}
+
+.actions-cell .btn {
+  margin-right: 0.5rem;
+}
+
+.actions-cell .btn:last-child {
+  margin-right: 0;
+}
+
+.test-cell {
+  text-align: center;
+  width: 2rem;
+}
+
+.test-dot {
+  font-size: 1rem;
+  cursor: default;
+}
+
+.test-dot.success {
+  color: #2e7d32;
+}
+
+.test-dot.failure {
+  color: #c62828;
+  cursor: pointer;
+}
+
+.test-dot.failure:hover {
+  color: #b71c1c;
+}
+
+.test-dot.testing {
+  color: #1976d2;
+  animation: pulse 1s infinite;
+}
+
+@keyframes pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.4; }
+}
+
+/* Error Modal */
+.error-modal-content {
+  background: var(--bg-primary);
+  border-radius: 8px;
+  padding: 2rem;
+  width: 100%;
+  max-width: 500px;
+}
+
+.error-modal-content h3 {
+  margin-top: 0;
+  color: #c62828;
+}
+
+.error-modal-content .error-details {
+  background: var(--bg-tertiary);
+  padding: 1rem;
+  border-radius: 4px;
+  font-family: monospace;
+  font-size: 0.9rem;
+  word-break: break-word;
+  white-space: pre-wrap;
+}
+
+.error-modal-content .modal-actions {
+  display: flex;
+  justify-content: flex-end;
+  margin-top: 1.5rem;
+}
+
+/* Buttons */
+.btn {
+  padding: 0.5rem 1rem;
+  border: 1px solid var(--border-color);
+  border-radius: 4px;
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  cursor: pointer;
+  font-size: 0.875rem;
+}
+
+.btn:hover {
+  background: var(--bg-tertiary);
+}
+
+.btn:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.btn-primary {
+  background-color: var(--color-primary);
+  border-color: var(--color-primary);
+  color: white;
+}
+
+.btn-primary:hover {
+  background-color: var(--color-primary-hover);
+}
+
+.btn-danger {
+  background-color: #dc3545;
+  border-color: #dc3545;
+  color: white;
+}
+
+.btn-danger:hover {
+  background-color: #c82333;
+}
+
+.btn-sm {
+  padding: 0.25rem 0.75rem;
+  font-size: 0.8rem;
+}
+
+.btn-secondary {
+  background-color: var(--bg-tertiary);
+  border-color: var(--border-color);
+  color: var(--text-primary);
+  font-weight: 500;
+}
+
+.btn-secondary:hover {
+  background-color: var(--bg-secondary);
+  border-color: var(--text-secondary);
+}
+
+.empty-message {
+  color: var(--text-secondary);
+  font-style: italic;
+  padding: 2rem;
+  text-align: center;
+}
+
+/* Modal */
+.modal-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: rgba(0, 0, 0, 0.5);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+}
+
+.modal-content {
+  background: var(--bg-primary);
+  border-radius: 8px;
+  padding: 2rem;
+  width: 100%;
+  max-width: 600px;
+  max-height: 90vh;
+  overflow-y: auto;
+}
+
+.modal-content h2 {
+  margin-top: 0;
+}
+
+/* Form */
+.form-group {
+  margin-bottom: 1rem;
+}
+
+.form-group label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: var(--text-primary);
+}
+
+.form-group input,
+.form-group select {
+  width: 100%;
+  padding: 0.5rem;
+  border: 1px solid var(--border-color);
+  border-radius: 4px;
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  font-size: 1rem;
+}
+
+.form-group input:focus,
+.form-group select:focus {
+  outline: none;
+  border-color: var(--color-primary);
+}
+
+.form-row {
+  display: flex;
+  gap: 1rem;
+}
+
+.form-row .form-group {
+  flex: 1;
+}
+
+.checkbox-group label {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  cursor: pointer;
+}
+
+.checkbox-group input[type="checkbox"] {
+  width: auto;
+}
+
+.help-text {
+  display: block;
+  font-size: 0.8rem;
+  color: var(--text-secondary);
+  margin-top: 0.25rem;
+}
+
+.form-actions {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-top: 1.5rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--border-color);
+}
+
+.form-actions-right {
+  display: flex;
+  gap: 0.5rem;
+}

frontend/src/pages/AdminCachePage.tsx

@@ -0,0 +1,509 @@
+import { useState, useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { useAuth } from '../contexts/AuthContext';
+import {
+  listUpstreamSources,
+  createUpstreamSource,
+  updateUpstreamSource,
+  deleteUpstreamSource,
+  testUpstreamSource,
+} from '../api';
+import { UpstreamSource, SourceType, AuthType } from '../types';
+import './AdminCachePage.css';
+
+const SOURCE_TYPES: SourceType[] = ['npm', 'pypi', 'maven', 'docker', 'helm', 'nuget', 'deb', 'rpm', 'generic'];
+const SUPPORTED_SOURCE_TYPES: Set<SourceType> = new Set(['pypi', 'generic']);
+const AUTH_TYPES: AuthType[] = ['none', 'basic', 'bearer', 'api_key'];
+
+function AdminCachePage() {
+  const { user, loading: authLoading } = useAuth();
+  const navigate = useNavigate();
+
+  // Upstream sources state
+  const [sources, setSources] = useState<UpstreamSource[]>([]);
+  const [loadingSources, setLoadingSources] = useState(true);
+  const [sourcesError, setSourcesError] = useState<string | null>(null);
+
+  // Create/Edit form state
+  const [showForm, setShowForm] = useState(false);
+  const [editingSource, setEditingSource] = useState<UpstreamSource | null>(null);
+  const [formData, setFormData] = useState({
+    name: '',
+    source_type: 'generic' as SourceType,
+    url: '',
+    enabled: true,
+    auth_type: 'none' as AuthType,
+    username: '',
+    password: '',
+    priority: 100,
+  });
+  const [formError, setFormError] = useState<string | null>(null);
+  const [isSaving, setIsSaving] = useState(false);
+
+  // Test result state
+  const [testingId, setTestingId] = useState<string | null>(null);
+  const [testResults, setTestResults] = useState<Record<string, { success: boolean; message: string }>>({});
+
+  // Delete confirmation state
+  const [deletingId, setDeletingId] = useState<string | null>(null);
+
+  // Success message
+  const [successMessage, setSuccessMessage] = useState<string | null>(null);
+
+  // Error modal state
+  const [showErrorModal, setShowErrorModal] = useState(false);
+  const [selectedError, setSelectedError] = useState<{ sourceName: string; error: string } | null>(null);
+
+  useEffect(() => {
+    if (!authLoading && !user) {
+      navigate('/login', { state: { from: '/admin/cache' } });
+    }
+  }, [user, authLoading, navigate]);
+
+  useEffect(() => {
+    if (user && user.is_admin) {
+      loadSources();
+    }
+  }, [user]);
+
+  useEffect(() => {
+    if (successMessage) {
+      const timer = setTimeout(() => setSuccessMessage(null), 3000);
+      return () => clearTimeout(timer);
+    }
+  }, [successMessage]);
+
+  async function loadSources() {
+    setLoadingSources(true);
+    setSourcesError(null);
+    try {
+      const data = await listUpstreamSources();
+      setSources(data);
+    } catch (err) {
+      setSourcesError(err instanceof Error ? err.message : 'Failed to load sources');
+    } finally {
+      setLoadingSources(false);
+    }
+  }
+
+  function openCreateForm() {
+    setEditingSource(null);
+    setFormData({
+      name: '',
+      source_type: 'generic',
+      url: '',
+      enabled: true,
+      auth_type: 'none',
+      username: '',
+      password: '',
+      priority: 100,
+    });
+    setFormError(null);
+    setShowForm(true);
+  }
+
+  function openEditForm(source: UpstreamSource) {
+    setEditingSource(source);
+    setFormData({
+      name: source.name,
+      source_type: source.source_type,
+      url: source.url,
+      enabled: source.enabled,
+      auth_type: source.auth_type,
+      username: source.username || '',
+      password: '',
+      priority: source.priority,
+    });
+    setFormError(null);
+    setShowForm(true);
+  }
+
+  async function handleFormSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    if (!formData.name.trim()) {
+      setFormError('Name is required');
+      return;
+    }
+    if (!formData.url.trim()) {
+      setFormError('URL is required');
+      return;
+    }
+
+    setIsSaving(true);
+    setFormError(null);
+
+    try {
+      let savedSourceId: string | null = null;
+
+      if (editingSource) {
+        // Update existing source
+        await updateUpstreamSource(editingSource.id, {
+          name: formData.name.trim(),
+          source_type: formData.source_type,
+          url: formData.url.trim(),
+          enabled: formData.enabled,
+          auth_type: formData.auth_type,
+          username: formData.username.trim() || undefined,
+          password: formData.password || undefined,
+          priority: formData.priority,
+        });
+        savedSourceId = editingSource.id;
+        setSuccessMessage('Source updated successfully');
+      } else {
+        // Create new source
+        const newSource = await createUpstreamSource({
+          name: formData.name.trim(),
+          source_type: formData.source_type,
+          url: formData.url.trim(),
+          enabled: formData.enabled,
+          auth_type: formData.auth_type,
+          username: formData.username.trim() || undefined,
+          password: formData.password || undefined,
+          priority: formData.priority,
+        });
+        savedSourceId = newSource.id;
+        setSuccessMessage('Source created successfully');
+      }
+      setShowForm(false);
+      await loadSources();
+
+      // Auto-test the source after save
+      if (savedSourceId) {
+        testSourceById(savedSourceId);
+      }
+    } catch (err) {
+      setFormError(err instanceof Error ? err.message : 'Failed to save source');
+    } finally {
+      setIsSaving(false);
+    }
+  }
+
+  async function handleDelete(source: UpstreamSource) {
+    if (!window.confirm(`Delete upstream source "${source.name}"? This cannot be undone.`)) {
+      return;
+    }
+
+    setDeletingId(source.id);
+    try {
+      await deleteUpstreamSource(source.id);
+      setSuccessMessage(`Source "${source.name}" deleted`);
+      await loadSources();
+    } catch (err) {
+      setSourcesError(err instanceof Error ? err.message : 'Failed to delete source');
+    } finally {
+      setDeletingId(null);
+    }
+  }
+
+  async function handleTest(source: UpstreamSource) {
+    testSourceById(source.id);
+  }
+
+  async function testSourceById(sourceId: string) {
+    setTestingId(sourceId);
+    setTestResults((prev) => ({ ...prev, [sourceId]: { success: true, message: 'Testing...' } }));
+
+    try {
+      const result = await testUpstreamSource(sourceId);
+      setTestResults((prev) => ({
+        ...prev,
+        [sourceId]: {
+          success: result.success,
+          message: result.success
+            ? `OK (${result.elapsed_ms}ms)`
+            : result.error || `HTTP ${result.status_code}`,
+        },
+      }));
+    } catch (err) {
+      setTestResults((prev) => ({
+        ...prev,
+        [sourceId]: {
+          success: false,
+          message: err instanceof Error ? err.message : 'Test failed',
+        },
+      }));
+    } finally {
+      setTestingId(null);
+    }
+  }
+
+  function showError(sourceName: string, error: string) {
+    setSelectedError({ sourceName, error });
+    setShowErrorModal(true);
+  }
+
+  if (authLoading) {
+    return <div className="admin-cache-page">Loading...</div>;
+  }
+
+  if (!user?.is_admin) {
+    return (
+      <div className="admin-cache-page">
+        <div className="error-message">Access denied. Admin privileges required.</div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="admin-cache-page">
+      <h1>Upstream Sources</h1>
+
+      {successMessage && <div className="success-message">{successMessage}</div>}
+
+      {/* Upstream Sources Section */}
+      <section className="sources-section">
+        <div className="section-header">
+          <button className="btn btn-primary" onClick={openCreateForm}>
+            Add Source
+          </button>
+        </div>
+
+        {loadingSources ? (
+          <p>Loading sources...</p>
+        ) : sourcesError ? (
+          <div className="error-message">{sourcesError}</div>
+        ) : sources.length === 0 ? (
+          <p className="empty-message">No upstream sources configured.</p>
+        ) : (
+          <table className="sources-table">
+            <thead>
+              <tr>
+                <th>Name</th>
+                <th>Type</th>
+                <th>URL</th>
+                <th>Priority</th>
+                <th>Status</th>
+                <th>Test</th>
+                <th>Actions</th>
+              </tr>
+            </thead>
+            <tbody>
+              {sources.map((source) => (
+                <tr key={source.id} className={source.enabled ? '' : 'disabled-row'}>
+                  <td>
+                    <span className="source-name">{source.name}</span>
+                    {source.source === 'env' && (
+                      <span className="env-badge" title="Defined via environment variable">ENV</span>
+                    )}
+                  </td>
+                  <td>
+                    {source.source_type}
+                    {!SUPPORTED_SOURCE_TYPES.has(source.source_type) && (
+                      <span className="coming-soon-badge"> (coming soon)</span>
+                    )}
+                  </td>
+                  <td className="url-cell" title={source.url}>{source.url}</td>
+                  <td>{source.priority}</td>
+                  <td>
+                    <span className={`status-badge ${source.enabled ? 'enabled' : 'disabled'}`}>
+                      {source.enabled ? 'Enabled' : 'Disabled'}
+                    </span>
+                  </td>
+                  <td className="test-cell">
+                    {testingId === source.id ? (
+                      <span className="test-dot testing" title="Testing...">●</span>
+                    ) : testResults[source.id] ? (
+                      testResults[source.id].success ? (
+                        <span className="test-dot success" title={testResults[source.id].message}>●</span>
+                      ) : (
+                        <span
+                          className="test-dot failure"
+                          title="Click to see error"
+                          onClick={() => showError(source.name, testResults[source.id].message)}
+                        >●</span>
+                      )
+                    ) : null}
+                  </td>
+                  <td className="actions-cell">
+                    <button
+                      className="btn btn-sm btn-secondary"
+                      onClick={() => handleTest(source)}
+                      disabled={testingId === source.id}
+                    >
+                      Test
+                    </button>
+                    {source.source !== 'env' && (
+                      <button className="btn btn-sm btn-secondary" onClick={() => openEditForm(source)}>
+                        Edit
+                      </button>
+                    )}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        )}
+      </section>
+
+      {/* Create/Edit Modal */}
+      {showForm && (
+        <div className="modal-overlay" onClick={() => setShowForm(false)}>
+          <div className="modal-content" onClick={(e) => e.stopPropagation()}>
+            <h2>{editingSource ? 'Edit Upstream Source' : 'Add Upstream Source'}</h2>
+            <form onSubmit={handleFormSubmit}>
+              {formError && <div className="error-message">{formError}</div>}
+
+              <div className="form-group">
+                <label htmlFor="name">Name</label>
+                <input
+                  type="text"
+                  id="name"
+                  value={formData.name}
+                  onChange={(e) => setFormData({ ...formData, name: e.target.value })}
+                  placeholder="e.g., npm-private"
+                  required
+                />
+              </div>
+
+              <div className="form-row">
+                <div className="form-group">
+                  <label htmlFor="source_type">Type</label>
+                  <select
+                    id="source_type"
+                    value={formData.source_type}
+                    onChange={(e) => setFormData({ ...formData, source_type: e.target.value as SourceType })}
+                  >
+                    {SOURCE_TYPES.map((type) => (
+                      <option key={type} value={type}>
+                        {type}{!SUPPORTED_SOURCE_TYPES.has(type) ? ' (coming soon)' : ''}
+                      </option>
+                    ))}
+                  </select>
+                </div>
+
+                <div className="form-group">
+                  <label htmlFor="priority">Priority</label>
+                  <input
+                    type="number"
+                    id="priority"
+                    value={formData.priority}
+                    onChange={(e) => setFormData({ ...formData, priority: parseInt(e.target.value) || 100 })}
+                    min="1"
+                  />
+                  <span className="help-text">Lower = higher priority</span>
+                </div>
+              </div>
+
+              <div className="form-group">
+                <label htmlFor="url">URL</label>
+                <input
+                  type="url"
+                  id="url"
+                  value={formData.url}
+                  onChange={(e) => setFormData({ ...formData, url: e.target.value })}
+                  placeholder="https://registry.example.com"
+                  required
+                />
+              </div>
+
+              <div className="form-row">
+                <div className="form-group checkbox-group">
+                  <label>
+                    <input
+                      type="checkbox"
+                      checked={formData.enabled}
+                      onChange={(e) => setFormData({ ...formData, enabled: e.target.checked })}
+                    />
+                    Enabled
+                  </label>
+                </div>
+              </div>
+
+              <div className="form-group">
+                <label htmlFor="auth_type">Authentication</label>
+                <select
+                  id="auth_type"
+                  value={formData.auth_type}
+                  onChange={(e) => setFormData({ ...formData, auth_type: e.target.value as AuthType })}
+                >
+                  {AUTH_TYPES.map((type) => (
+                    <option key={type} value={type}>
+                      {type === 'none' ? 'None' : type === 'api_key' ? 'API Key' : type.charAt(0).toUpperCase() + type.slice(1)}
+                    </option>
+                  ))}
+                </select>
+              </div>
+
+              {formData.auth_type !== 'none' && (
+                <div className="form-row">
+                  {(formData.auth_type === 'basic' || formData.auth_type === 'api_key') && (
+                    <div className="form-group">
+                      <label htmlFor="username">{formData.auth_type === 'api_key' ? 'Header Name' : 'Username'}</label>
+                      <input
+                        type="text"
+                        id="username"
+                        value={formData.username}
+                        onChange={(e) => setFormData({ ...formData, username: e.target.value })}
+                        placeholder={formData.auth_type === 'api_key' ? 'X-API-Key' : 'username'}
+                      />
+                    </div>
+                  )}
+                  <div className="form-group">
+                    <label htmlFor="password">
+                      {formData.auth_type === 'bearer'
+                        ? 'Token'
+                        : formData.auth_type === 'api_key'
+                        ? 'API Key Value'
+                        : 'Password'}
+                    </label>
+                    <input
+                      type="password"
+                      id="password"
+                      value={formData.password}
+                      onChange={(e) => setFormData({ ...formData, password: e.target.value })}
+                      placeholder={editingSource ? '(unchanged)' : ''}
+                    />
+                    {editingSource && (
+                      <span className="help-text">Leave empty to keep existing {formData.auth_type === 'bearer' ? 'token' : 'credentials'}</span>
+                    )}
+                  </div>
+                </div>
+              )}
+
+              <div className="form-actions">
+                {editingSource && (
+                  <button
+                    type="button"
+                    className="btn btn-danger"
+                    onClick={() => {
+                      handleDelete(editingSource);
+                      setShowForm(false);
+                    }}
+                    disabled={deletingId === editingSource.id}
+                  >
+                    {deletingId === editingSource.id ? 'Deleting...' : 'Delete'}
+                  </button>
+                )}
+                <div className="form-actions-right">
+                  <button type="button" className="btn" onClick={() => setShowForm(false)}>
+                    Cancel
+                  </button>
+                  <button type="submit" className="btn btn-primary" disabled={isSaving}>
+                    {isSaving ? 'Saving...' : editingSource ? 'Update' : 'Create'}
+                  </button>
+                </div>
+              </div>
+            </form>
+          </div>
+        </div>
+      )}
+
+      {/* Error Details Modal */}
+      {showErrorModal && selectedError && (
+        <div className="modal-overlay" onClick={() => setShowErrorModal(false)}>
+          <div className="error-modal-content" onClick={(e) => e.stopPropagation()}>
+            <h3>Connection Error: {selectedError.sourceName}</h3>
+            <div className="error-details">{selectedError.error}</div>
+            <div className="modal-actions">
+              <button className="btn" onClick={() => setShowErrorModal(false)}>
+                Close
+              </button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default AdminCachePage;

frontend/src/pages/Home.css

@@ -493,3 +493,16 @@
   gap: 6px;
   flex-wrap: wrap;
 }
+
+/* Cell name styles */
+.cell-name {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+/* System project badge */
+.system-badge {
+  font-size: 0.7rem;
+  padding: 2px 6px;
+}

frontend/src/pages/Home.tsx

@@ -224,6 +224,9 @@ function Home() {
                 <span className="cell-name">
                   {!project.is_public && <LockIcon />}
                   {project.name}
+                  {project.is_system && (
+                    <Badge variant="warning" className="system-badge">Cache</Badge>
+                  )}
                 </span>
               ),
             },
@@ -246,7 +249,7 @@ function Home() {
               key: 'created_by',
               header: 'Owner',
               className: 'cell-owner',
-              render: (project) => project.created_by,
+              render: (project) => project.team_name || project.created_by,
             },
             ...(user
               ? [

frontend/src/pages/PackagePage.css

@@ -642,6 +642,11 @@ tr:hover .copy-btn {
   padding: 20px;
 }
 
+/* Ensure file modal needs higher z-index when opened from deps modal */
+.modal-overlay:has(.ensure-file-modal) {
+  z-index: 1100;
+}
+
 .ensure-file-modal {
   background: var(--bg-secondary);
   border: 1px solid var(--border-primary);
@@ -793,4 +798,194 @@ tr:hover .copy-btn {
   .ensure-file-modal {
     max-height: 90vh;
   }
+
+  .action-menu-dropdown {
+    right: 0;
+    left: auto;
+  }
+}
+
+/* Header upload button */
+.header-upload-btn {
+  margin-left: auto;
+}
+
+/* Tag/Version cell */
+.tag-version-cell {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.tag-version-cell .version-badge {
+  font-size: 0.75rem;
+  color: var(--text-muted);
+}
+
+/* Icon buttons */
+.btn-icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: var(--radius-sm);
+  color: var(--text-secondary);
+  cursor: pointer;
+  transition: all var(--transition-fast);
+}
+
+.btn-icon:hover {
+  background: var(--bg-hover);
+  color: var(--text-primary);
+}
+
+/* Action menu */
+.action-buttons {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.action-menu {
+  position: relative;
+}
+
+/* Action menu backdrop for click-outside */
+.action-menu-backdrop {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 999;
+}
+
+.action-menu-dropdown {
+  position: fixed;
+  z-index: 1000;
+  min-width: 180px;
+  padding: 4px 0;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-md);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+}
+
+.action-menu-dropdown button {
+  display: block;
+  width: 100%;
+  padding: 8px 12px;
+  background: none;
+  border: none;
+  text-align: left;
+  font-size: 0.875rem;
+  color: var(--text-primary);
+  cursor: pointer;
+  transition: background var(--transition-fast);
+}
+
+.action-menu-dropdown button:hover {
+  background: var(--bg-hover);
+}
+
+/* Upload Modal */
+.upload-modal,
+.create-tag-modal {
+  background: var(--bg-secondary);
+  border-radius: var(--radius-lg);
+  width: 90%;
+  max-width: 500px;
+  max-height: 90vh;
+  overflow: hidden;
+}
+
+.modal-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px 20px;
+  border-bottom: 1px solid var(--border-primary);
+}
+
+.modal-header h3 {
+  margin: 0;
+  font-size: 1.125rem;
+  font-weight: 600;
+}
+
+.modal-body {
+  padding: 20px;
+}
+
+.modal-description {
+  margin-bottom: 16px;
+  color: var(--text-secondary);
+  font-size: 0.875rem;
+}
+
+.modal-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 12px;
+  margin-top: 20px;
+  padding-top: 16px;
+  border-top: 1px solid var(--border-primary);
+}
+
+/* Dependencies Modal */
+.deps-modal {
+  background: var(--bg-secondary);
+  border-radius: var(--radius-lg);
+  width: 90%;
+  max-width: 600px;
+  max-height: 80vh;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+
+.deps-modal .modal-body {
+  overflow-y: auto;
+  flex: 1;
+}
+
+.deps-modal-controls {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 16px;
+}
+
+/* Artifact ID Modal */
+.artifact-id-modal {
+  background: var(--bg-secondary);
+  border-radius: var(--radius-lg);
+  width: 90%;
+  max-width: 500px;
+}
+
+.artifact-id-display {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 16px;
+  background: var(--bg-tertiary);
+  border-radius: var(--radius-md);
+  border: 1px solid var(--border-primary);
+}
+
+.artifact-id-display code {
+  font-family: 'JetBrains Mono', 'Fira Code', 'Consolas', monospace;
+  font-size: 0.8125rem;
+  color: var(--text-primary);
+  word-break: break-all;
+  flex: 1;
+}
+
+.artifact-id-display .copy-btn {
+  opacity: 1;
+  flex-shrink: 0;
 }

frontend/src/pages/PackagePage.tsx

@@ -1,7 +1,7 @@
 import { useState, useEffect, useCallback } from 'react';
 import { useParams, useSearchParams, useNavigate, useLocation, Link } from 'react-router-dom';
-import { TagDetail, Package, PaginatedResponse, AccessLevel, Dependency, DependentInfo } from '../types';
-import { listTags, getDownloadUrl, getPackage, getMyProjectAccess, createTag, getArtifactDependencies, getReverseDependencies, getEnsureFile, UnauthorizedError, ForbiddenError } from '../api';
+import { PackageArtifact, Package, PaginatedResponse, AccessLevel, Dependency, DependentInfo } from '../types';
+import { listPackageArtifacts, getDownloadUrl, getPackage, getMyProjectAccess, getArtifactDependencies, getReverseDependencies, getEnsureFile, UnauthorizedError, ForbiddenError } from '../api';
 import { Breadcrumb } from '../components/Breadcrumb';
 import { Badge } from '../components/Badge';
 import { SearchInput } from '../components/SearchInput';
@@ -57,20 +57,20 @@ function PackagePage() {
   const { user } = useAuth();
 
   const [pkg, setPkg] = useState<Package | null>(null);
-  const [tagsData, setTagsData] = useState<PaginatedResponse<TagDetail> | null>(null);
+  const [artifactsData, setArtifactsData] = useState<PaginatedResponse<PackageArtifact> | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [accessDenied, setAccessDenied] = useState(false);
-  const [uploadTag, setUploadTag] = useState('');
   const [uploadSuccess, setUploadSuccess] = useState<string | null>(null);
-  const [artifactIdInput, setArtifactIdInput] = useState('');
   const [accessLevel, setAccessLevel] = useState<AccessLevel | null>(null);
-  const [createTagName, setCreateTagName] = useState('');
-  const [createTagArtifactId, setCreateTagArtifactId] = useState('');
-  const [createTagLoading, setCreateTagLoading] = useState(false);
+
+  // UI state
+  const [showUploadModal, setShowUploadModal] = useState(false);
+  const [openMenuId, setOpenMenuId] = useState<string | null>(null);
+  const [menuPosition, setMenuPosition] = useState<{ top: number; left: number } | null>(null);
 
   // Dependencies state
-  const [selectedTag, setSelectedTag] = useState<TagDetail | null>(null);
+  const [selectedArtifact, setSelectedArtifact] = useState<PackageArtifact | null>(null);
   const [dependencies, setDependencies] = useState<Dependency[]>([]);
   const [depsLoading, setDepsLoading] = useState(false);
   const [depsError, setDepsError] = useState<string | null>(null);
@@ -78,7 +78,7 @@ function PackagePage() {
   // Reverse dependencies state
   const [reverseDeps, setReverseDeps] = useState<DependentInfo[]>([]);
   const [reverseDepsLoading, setReverseDepsLoading] = useState(false);
-  const [reverseDepsError, setReverseDepsError] = useState<string | null>(null);
+  const [_reverseDepsError, setReverseDepsError] = useState<string | null>(null);
   const [reverseDepsPage, setReverseDepsPage] = useState(1);
   const [reverseDepsTotal, setReverseDepsTotal] = useState(0);
   const [reverseDepsHasMore, setReverseDepsHasMore] = useState(false);
@@ -86,6 +86,13 @@ function PackagePage() {
   // Dependency graph modal state
   const [showGraph, setShowGraph] = useState(false);
 
+  // Dependencies modal state
+  const [showDepsModal, setShowDepsModal] = useState(false);
+
+  // Artifact ID modal state
+  const [showArtifactIdModal, setShowArtifactIdModal] = useState(false);
+  const [viewArtifactId, setViewArtifactId] = useState<string | null>(null);
+
   // Ensure file modal state
   const [showEnsureFile, setShowEnsureFile] = useState(false);
   const [ensureFileContent, setEnsureFileContent] = useState<string | null>(null);
@@ -96,11 +103,15 @@ function PackagePage() {
   // Derived permissions
   const canWrite = accessLevel === 'write' || accessLevel === 'admin';
 
+  // Detect system projects (convention: name starts with "_")
+  const isSystemProject = projectName?.startsWith('_') ?? false;
+
   // Get params from URL
+  // Valid sort fields for artifacts: created_at, size, original_name
   const page = parseInt(searchParams.get('page') || '1', 10);
   const search = searchParams.get('search') || '';
-  const sort = searchParams.get('sort') || 'name';
-  const order = (searchParams.get('order') || 'asc') as 'asc' | 'desc';
+  const sort = searchParams.get('sort') || 'created_at';
+  const order = (searchParams.get('order') || 'desc') as 'asc' | 'desc';
 
   const updateParams = useCallback(
     (updates: Record<string, string | undefined>) => {
@@ -123,13 +134,13 @@ function PackagePage() {
     try {
       setLoading(true);
       setAccessDenied(false);
-      const [pkgData, tagsResult, accessResult] = await Promise.all([
+      const [pkgData, artifactsResult, accessResult] = await Promise.all([
         getPackage(projectName, packageName),
-        listTags(projectName, packageName, { page, search, sort, order }),
+        listPackageArtifacts(projectName, packageName, { page, search, sort, order }),
         getMyProjectAccess(projectName),
       ]);
       setPkg(pkgData);
-      setTagsData(tagsResult);
+      setArtifactsData(artifactsResult);
       setAccessLevel(accessResult.access_level);
       setError(null);
     } catch (err) {
@@ -153,25 +164,15 @@ function PackagePage() {
     loadData();
   }, [loadData]);
 
-  // Auto-select tag when tags are loaded (prefer version from URL, then first tag)
-  // Re-run when package changes to pick up new tags
+  // Auto-select artifact when artifacts are loaded (prefer first artifact)
+  // Re-run when package changes to pick up new artifacts
   useEffect(() => {
-    if (tagsData?.items && tagsData.items.length > 0) {
-      const versionParam = searchParams.get('version');
-      if (versionParam) {
-        // Find tag matching the version parameter
-        const matchingTag = tagsData.items.find(t => t.version === versionParam);
-        if (matchingTag) {
-          setSelectedTag(matchingTag);
-          setDependencies([]);
-          return;
-        }
-      }
-      // Fall back to first tag
-      setSelectedTag(tagsData.items[0]);
+    if (artifactsData?.items && artifactsData.items.length > 0) {
+      // Fall back to first artifact
+      setSelectedArtifact(artifactsData.items[0]);
       setDependencies([]);
     }
-  }, [tagsData, searchParams, projectName, packageName]);
+  }, [artifactsData, projectName, packageName]);
 
   // Fetch dependencies when selected tag changes
   const fetchDependencies = useCallback(async (artifactId: string) => {
@@ -189,10 +190,10 @@ function PackagePage() {
   }, []);
 
   useEffect(() => {
-    if (selectedTag) {
-      fetchDependencies(selectedTag.artifact_id);
+    if (selectedArtifact) {
+      fetchDependencies(selectedArtifact.id);
     }
-  }, [selectedTag, fetchDependencies]);
+  }, [selectedArtifact, fetchDependencies]);
 
   // Fetch reverse dependencies
   const fetchReverseDeps = useCallback(async (pageNum: number = 1) => {
@@ -220,15 +221,15 @@ function PackagePage() {
     }
   }, [projectName, packageName, loading, fetchReverseDeps]);
 
-  // Fetch ensure file for a specific tag
-  const fetchEnsureFileForTag = useCallback(async (tagName: string) => {
+  // Fetch ensure file for a specific version or artifact
+  const fetchEnsureFileForRef = useCallback(async (ref: string) => {
     if (!projectName || !packageName) return;
 
-    setEnsureFileTagName(tagName);
+    setEnsureFileTagName(ref);
     setEnsureFileLoading(true);
     setEnsureFileError(null);
     try {
-      const content = await getEnsureFile(projectName, packageName, tagName);
+      const content = await getEnsureFile(projectName, packageName, ref);
       setEnsureFileContent(content);
       setShowEnsureFile(true);
     } catch (err) {
@@ -239,11 +240,13 @@ function PackagePage() {
     }
   }, [projectName, packageName]);
 
-  // Fetch ensure file for selected tag
+  // Fetch ensure file for selected artifact
   const fetchEnsureFile = useCallback(async () => {
-    if (!selectedTag) return;
-    fetchEnsureFileForTag(selectedTag.name);
-  }, [selectedTag, fetchEnsureFileForTag]);
+    if (!selectedArtifact) return;
+    const version = getArtifactVersion(selectedArtifact);
+    const ref = version || `artifact:${selectedArtifact.id}`;
+    fetchEnsureFileForRef(ref);
+  }, [selectedArtifact, fetchEnsureFileForRef]);
 
   // Keyboard navigation - go back with backspace
   useEffect(() => {
@@ -263,7 +266,6 @@ function PackagePage() {
       ? `Uploaded successfully! Artifact ID: ${results[0].artifact_id}`
       : `${count} files uploaded successfully!`;
     setUploadSuccess(message);
-    setUploadTag('');
     loadData();
     
     // Auto-dismiss success message after 5 seconds
@@ -274,30 +276,6 @@ function PackagePage() {
     setError(errorMsg);
   }, []);
 
-  const handleCreateTag = async (e: React.FormEvent) => {
-    e.preventDefault();
-    if (!createTagName.trim() || createTagArtifactId.length !== 64) return;
-
-    setCreateTagLoading(true);
-    setError(null);
-
-    try {
-      await createTag(projectName!, packageName!, {
-        name: createTagName.trim(),
-        artifact_id: createTagArtifactId,
-      });
-      setUploadSuccess(`Tag "${createTagName}" created successfully!`);
-      setCreateTagName('');
-      setCreateTagArtifactId('');
-      loadData();
-      setTimeout(() => setUploadSuccess(null), 5000);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : 'Failed to create tag');
-    } finally {
-      setCreateTagLoading(false);
-    }
-  };
-
   const handleSearchChange = (value: string) => {
     updateParams({ search: value, page: '1' });
   };
@@ -316,101 +294,225 @@ function PackagePage() {
   };
 
   const hasActiveFilters = search !== '';
-  const tags = tagsData?.items || [];
-  const pagination = tagsData?.pagination;
+  const artifacts = artifactsData?.items || [];
+  const pagination = artifactsData?.pagination;
 
-  const handleTagSelect = (tag: TagDetail) => {
-    setSelectedTag(tag);
+  const handleArtifactSelect = (artifact: PackageArtifact) => {
+    setSelectedArtifact(artifact);
   };
 
-  const columns = [
+  const handleMenuOpen = (e: React.MouseEvent, artifactId: string) => {
+    e.stopPropagation();
+    if (openMenuId === artifactId) {
+      setOpenMenuId(null);
+      setMenuPosition(null);
+    } else {
+      const rect = e.currentTarget.getBoundingClientRect();
+      setMenuPosition({ top: rect.bottom + 4, left: rect.right - 180 });
+      setOpenMenuId(artifactId);
+    }
+  };
+
+  // Helper to get version from artifact - prefer direct version field, fallback to metadata
+  const getArtifactVersion = (a: PackageArtifact): string | null => {
+    return a.version || (a.format_metadata?.version as string) || null;
+  };
+
+  // Helper to get download ref - prefer version, fallback to artifact ID
+  const getDownloadRef = (a: PackageArtifact): string => {
+    const version = getArtifactVersion(a);
+    return version || `artifact:${a.id}`;
+  };
+
+  // System projects show Version first, regular projects show Tag first
+  const columns = isSystemProject
+    ? [
+        // System project columns: Version first, then Filename
         {
-      key: 'name',
-      header: 'Tag',
-      sortable: true,
-      render: (t: TagDetail) => (
+          key: 'version',
+          header: 'Version',
+          // version is from format_metadata, not a sortable DB field
+          render: (a: PackageArtifact) => (
             <strong
-          className={`tag-name-link ${selectedTag?.id === t.id ? 'selected' : ''}`}
-          onClick={() => handleTagSelect(t)}
+              className={`tag-name-link ${selectedArtifact?.id === a.id ? 'selected' : ''}`}
+              onClick={() => handleArtifactSelect(a)}
               style={{ cursor: 'pointer' }}
             >
-          {t.name}
+              <span className="version-badge">{getArtifactVersion(a) || a.id.slice(0, 12)}</span>
             </strong>
           ),
         },
         {
-      key: 'version',
-      header: 'Version',
-      render: (t: TagDetail) => (
-        <span className="version-badge">{t.version || '-'}</span>
+          key: 'original_name',
+          header: 'Filename',
+          sortable: true,
+          className: 'cell-truncate',
+          render: (a: PackageArtifact) => (
+            <span title={a.original_name || a.id}>{a.original_name || a.id.slice(0, 12)}</span>
           ),
         },
         {
-      key: 'artifact_id',
-      header: 'Artifact ID',
-      render: (t: TagDetail) => (
-        <div className="artifact-id-cell">
-          <code className="artifact-id">{t.artifact_id.substring(0, 12)}...</code>
-          <CopyButton text={t.artifact_id} />
+          key: 'size',
+          header: 'Size',
+          sortable: true,
+          render: (a: PackageArtifact) => <span>{formatBytes(a.size)}</span>,
+        },
+        {
+          key: 'created_at',
+          header: 'Cached',
+          sortable: true,
+          render: (a: PackageArtifact) => (
+            <span>{new Date(a.created_at).toLocaleDateString()}</span>
+          ),
+        },
+        {
+          key: 'actions',
+          header: '',
+          render: (a: PackageArtifact) => (
+            <div className="action-buttons">
+              <a
+                href={getDownloadUrl(projectName!, packageName!, getDownloadRef(a))}
+                className="btn btn-icon"
+                download
+                title="Download"
+              >
+                <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                  <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+                  <polyline points="7 10 12 15 17 10" />
+                  <line x1="12" y1="15" x2="12" y2="3" />
+                </svg>
+              </a>
+              <button
+                className="btn btn-icon"
+                onClick={(e) => handleMenuOpen(e, a.id)}
+                title="More actions"
+              >
+                <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                  <circle cx="12" cy="12" r="1" />
+                  <circle cx="12" cy="5" r="1" />
+                  <circle cx="12" cy="19" r="1" />
+                </svg>
+              </button>
             </div>
           ),
         },
+      ]
+    : [
+        // Regular project columns: Version, Filename, Size, Created
+        // Valid sort fields: created_at, size, original_name
         {
-      key: 'artifact_size',
-      header: 'Size',
-      render: (t: TagDetail) => <span>{formatBytes(t.artifact_size)}</span>,
-    },
-    {
-      key: 'artifact_content_type',
-      header: 'Type',
-      render: (t: TagDetail) => (
-        <span className="content-type">{t.artifact_content_type || '-'}</span>
+          key: 'version',
+          header: 'Version',
+          // version is from format_metadata, not a sortable DB field
+          render: (a: PackageArtifact) => (
+            <strong
+              className={`tag-name-link ${selectedArtifact?.id === a.id ? 'selected' : ''}`}
+              onClick={() => handleArtifactSelect(a)}
+              style={{ cursor: 'pointer' }}
+            >
+              <span className="version-badge">{getArtifactVersion(a) || a.id.slice(0, 12)}</span>
+            </strong>
           ),
         },
         {
-      key: 'artifact_original_name',
+          key: 'original_name',
           header: 'Filename',
+          sortable: true,
           className: 'cell-truncate',
-      render: (t: TagDetail) => (
-        <span title={t.artifact_original_name || undefined}>{t.artifact_original_name || '-'}</span>
+          render: (a: PackageArtifact) => (
+            <span title={a.original_name || undefined}>{a.original_name || '—'}</span>
           ),
         },
+        {
+          key: 'size',
+          header: 'Size',
+          sortable: true,
+          render: (a: PackageArtifact) => <span>{formatBytes(a.size)}</span>,
+        },
         {
           key: 'created_at',
           header: 'Created',
           sortable: true,
-      render: (t: TagDetail) => (
-        <div className="created-cell">
-          <span>{new Date(t.created_at).toLocaleString()}</span>
-          <span className="created-by">by {t.created_by}</span>
-        </div>
+          render: (a: PackageArtifact) => (
+            <span title={`by ${a.created_by}`}>{new Date(a.created_at).toLocaleDateString()}</span>
           ),
         },
         {
           key: 'actions',
-      header: 'Actions',
-      render: (t: TagDetail) => (
+          header: '',
+          render: (a: PackageArtifact) => (
             <div className="action-buttons">
-          <button
-            className="btn btn-secondary btn-small"
-            onClick={() => fetchEnsureFileForTag(t.name)}
-            title="View orchard.ensure file"
-          >
-            Ensure
-          </button>
               <a
-            href={getDownloadUrl(projectName!, packageName!, t.name)}
-            className="btn btn-secondary btn-small"
+                href={getDownloadUrl(projectName!, packageName!, getDownloadRef(a))}
+                className="btn btn-icon"
                 download
+                title="Download"
               >
-            Download
+                <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                  <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+                  <polyline points="7 10 12 15 17 10" />
+                  <line x1="12" y1="15" x2="12" y2="3" />
+                </svg>
               </a>
+              <button
+                className="btn btn-icon"
+                onClick={(e) => handleMenuOpen(e, a.id)}
+                title="More actions"
+              >
+                <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                  <circle cx="12" cy="12" r="1" />
+                  <circle cx="12" cy="5" r="1" />
+                  <circle cx="12" cy="19" r="1" />
+                </svg>
+              </button>
             </div>
           ),
         },
       ];
 
-  if (loading && !tagsData) {
+  // Find the artifact for the open menu
+  const openMenuArtifact = artifacts.find(a => a.id === openMenuId);
+
+  // Close menu when clicking outside
+  const handleClickOutside = () => {
+    if (openMenuId) {
+      setOpenMenuId(null);
+      setMenuPosition(null);
+    }
+  };
+
+  // Render dropdown menu as a portal-like element
+  const renderActionMenu = () => {
+    if (!openMenuId || !menuPosition || !openMenuArtifact) return null;
+    const a = openMenuArtifact;
+    return (
+      <div
+        className="action-menu-backdrop"
+        onClick={handleClickOutside}
+      >
+        <div
+          className="action-menu-dropdown"
+          style={{ top: menuPosition.top, left: menuPosition.left }}
+          onClick={(e) => e.stopPropagation()}
+        >
+          <button onClick={() => { setViewArtifactId(a.id); setShowArtifactIdModal(true); setOpenMenuId(null); setMenuPosition(null); }}>
+            View Artifact ID
+          </button>
+          <button onClick={() => { navigator.clipboard.writeText(a.id); setOpenMenuId(null); setMenuPosition(null); }}>
+            Copy Artifact ID
+          </button>
+          <button onClick={() => { const version = getArtifactVersion(a); const ref = version || `artifact:${a.id}`; fetchEnsureFileForRef(ref); setOpenMenuId(null); setMenuPosition(null); }}>
+            View Ensure File
+          </button>
+          <button onClick={() => { handleArtifactSelect(a); setShowDepsModal(true); setOpenMenuId(null); setMenuPosition(null); }}>
+            View Dependencies
+          </button>
+        </div>
+      </div>
+    );
+  };
+
+  if (loading && !artifactsData) {
     return <div className="loading">Loading...</div>;
   }
 
@@ -451,6 +553,19 @@ function PackagePage() {
           <div className="page-header__title-row">
             <h1>{packageName}</h1>
             {pkg && <Badge variant="default">{pkg.format}</Badge>}
+            {user && canWrite && !isSystemProject && (
+              <button
+                className="btn btn-primary btn-small header-upload-btn"
+                onClick={() => setShowUploadModal(true)}
+              >
+                <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" style={{ marginRight: '6px' }}>
+                  <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+                  <polyline points="17 8 12 3 7 8" />
+                  <line x1="12" y1="3" x2="12" y2="15" />
+                </svg>
+                Upload
+              </button>
+            )}
           </div>
           {pkg?.description && <p className="description">{pkg.description}</p>}
           <div className="page-header__meta">
@@ -466,16 +581,11 @@ function PackagePage() {
               </>
             )}
           </div>
-          {pkg && (pkg.tag_count !== undefined || pkg.artifact_count !== undefined) && (
+          {pkg && pkg.artifact_count !== undefined && (
             <div className="package-header-stats">
-              {pkg.tag_count !== undefined && (
-                <span className="stat-item">
-                  <strong>{pkg.tag_count}</strong> tags
-                </span>
-              )}
               {pkg.artifact_count !== undefined && (
                 <span className="stat-item">
-                  <strong>{pkg.artifact_count}</strong> artifacts
+                  <strong>{pkg.artifact_count}</strong> {isSystemProject ? 'versions' : 'artifacts'}
                 </span>
               )}
               {pkg.total_size !== undefined && pkg.total_size > 0 && (
@@ -483,11 +593,6 @@ function PackagePage() {
                   <strong>{formatBytes(pkg.total_size)}</strong> total
                 </span>
               )}
-              {pkg.latest_tag && (
-                <span className="stat-item">
-                  Latest: <strong className="accent">{pkg.latest_tag}</strong>
-                </span>
-              )}
             </div>
           )}
         </div>
@@ -496,51 +601,16 @@ function PackagePage() {
       {error && <div className="error-message">{error}</div>}
       {uploadSuccess && <div className="success-message">{uploadSuccess}</div>}
 
-      {user && (
-        <div className="upload-section card">
-          <h3>Upload Artifact</h3>
-          {canWrite ? (
-            <div className="upload-form">
-              <div className="form-group">
-                <label htmlFor="upload-tag">Tag (optional)</label>
-                <input
-                  id="upload-tag"
-                  type="text"
-                  value={uploadTag}
-                  onChange={(e) => setUploadTag(e.target.value)}
-                  placeholder="v1.0.0, latest, stable..."
-                />
-              </div>
-              <DragDropUpload
-                projectName={projectName!}
-                packageName={packageName!}
-                tag={uploadTag || undefined}
-                onUploadComplete={handleUploadComplete}
-                onUploadError={handleUploadError}
-              />
-            </div>
-          ) : (
-            <DragDropUpload
-              projectName={projectName!}
-              packageName={packageName!}
-              disabled={true}
-              disabledReason="You have read-only access to this project and cannot upload artifacts."
-              onUploadComplete={handleUploadComplete}
-              onUploadError={handleUploadError}
-            />
-          )}
-        </div>
-      )}
 
       <div className="section-header">
-        <h2>Tags / Versions</h2>
+        <h2>{isSystemProject ? 'Versions' : 'Artifacts'}</h2>
       </div>
 
       <div className="list-controls">
         <SearchInput
           value={search}
           onChange={handleSearchChange}
-          placeholder="Filter tags..."
+          placeholder="Filter artifacts..."
           className="list-controls__search"
         />
       </div>
@@ -553,13 +623,13 @@ function PackagePage() {
 
       <div className="data-table--responsive">
         <DataTable
-          data={tags}
+          data={artifacts}
           columns={columns}
-          keyExtractor={(t) => t.id}
+          keyExtractor={(a) => a.id}
           emptyMessage={
             hasActiveFilters
-              ? 'No tags match your filters. Try adjusting your search.'
-              : 'No tags yet. Upload an artifact with a tag to create one!'
+              ? 'No artifacts match your filters. Try adjusting your search.'
+              : 'No artifacts yet. Upload a file to get started!'
           }
           onSort={handleSortChange}
           sortKey={sort}
@@ -577,121 +647,10 @@ function PackagePage() {
         />
       )}
 
-      {/* Dependencies Section */}
-      {tags.length > 0 && (
-        <div className="dependencies-section card">
-          <div className="dependencies-header">
-            <h3>Dependencies</h3>
-            <div className="dependencies-controls">
-              {selectedTag && (
-                <>
-                  <button
-                    className="btn btn-secondary btn-small"
-                    onClick={fetchEnsureFile}
-                    disabled={ensureFileLoading}
-                    title="View orchard.ensure file"
-                  >
-                    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" style={{ marginRight: '6px' }}>
-                      <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"></path>
-                      <polyline points="14 2 14 8 20 8"></polyline>
-                      <line x1="16" y1="13" x2="8" y2="13"></line>
-                      <line x1="16" y1="17" x2="8" y2="17"></line>
-                      <polyline points="10 9 9 9 8 9"></polyline>
-                    </svg>
-                    {ensureFileLoading ? 'Loading...' : 'View Ensure File'}
-                  </button>
-                  <button
-                    className="btn btn-secondary btn-small"
-                    onClick={() => setShowGraph(true)}
-                    title="View full dependency tree"
-                  >
-                    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" style={{ marginRight: '6px' }}>
-                      <circle cx="12" cy="12" r="3"></circle>
-                      <circle cx="4" cy="4" r="2"></circle>
-                      <circle cx="20" cy="4" r="2"></circle>
-                      <circle cx="4" cy="20" r="2"></circle>
-                      <circle cx="20" cy="20" r="2"></circle>
-                      <line x1="9.5" y1="9.5" x2="5.5" y2="5.5"></line>
-                      <line x1="14.5" y1="9.5" x2="18.5" y2="5.5"></line>
-                      <line x1="9.5" y1="14.5" x2="5.5" y2="18.5"></line>
-                      <line x1="14.5" y1="14.5" x2="18.5" y2="18.5"></line>
-                    </svg>
-                    View Graph
-                  </button>
-                </>
-              )}
-            </div>
-          </div>
-          <div className="dependencies-tag-select">
-            {selectedTag && (
-              <select
-                className="tag-selector"
-                value={selectedTag.id}
-                onChange={(e) => {
-                  const tag = tags.find(t => t.id === e.target.value);
-                  if (tag) setSelectedTag(tag);
-                }}
-              >
-                {tags.map(t => (
-                  <option key={t.id} value={t.id}>
-                    {t.name}{t.version ? ` (${t.version})` : ''}
-                  </option>
-                ))}
-              </select>
-            )}
-          </div>
-
-          {depsLoading ? (
-            <div className="deps-loading">Loading dependencies...</div>
-          ) : depsError ? (
-            <div className="deps-error">{depsError}</div>
-          ) : dependencies.length === 0 ? (
-            <div className="deps-empty">
-              {selectedTag ? (
-                <span><strong>{selectedTag.name}</strong> has no dependencies</span>
-              ) : (
-                <span>No dependencies</span>
-              )}
-            </div>
-          ) : (
-            <div className="deps-list">
-              <div className="deps-summary">
-                <strong>{selectedTag?.name}</strong> has {dependencies.length} {dependencies.length === 1 ? 'dependency' : 'dependencies'}:
-              </div>
-              <ul className="deps-items">
-                {dependencies.map((dep) => (
-                  <li key={dep.id} className="dep-item">
-                    <Link
-                      to={`/project/${dep.project}/${dep.package}`}
-                      className="dep-link"
-                    >
-                      {dep.project}/{dep.package}
-                    </Link>
-                    <span className="dep-constraint">
-                      @ {dep.version || dep.tag}
-                    </span>
-                    <span className="dep-status dep-status--ok" title="Package exists">
-                      &#10003;
-                    </span>
-                  </li>
-                ))}
-              </ul>
-            </div>
-          )}
-        </div>
-      )}
-
-      {/* Used By (Reverse Dependencies) Section */}
+      {/* Used By (Reverse Dependencies) Section - only show if there are reverse deps */}
+      {reverseDeps.length > 0 && (
         <div className="used-by-section card">
           <h3>Used By</h3>
-
-        {reverseDepsLoading ? (
-          <div className="deps-loading">Loading reverse dependencies...</div>
-        ) : reverseDepsError ? (
-          <div className="deps-error">{reverseDepsError}</div>
-        ) : reverseDeps.length === 0 ? (
-          <div className="deps-empty">No packages depend on this package</div>
-        ) : (
           <div className="reverse-deps-list">
             <div className="deps-summary">
               {reverseDepsTotal} {reverseDepsTotal === 1 ? 'package depends' : 'packages depend'} on this:
@@ -734,78 +693,6 @@ function PackagePage() {
               </div>
             )}
           </div>
-        )}
-      </div>
-
-      <div className="download-by-id-section card">
-        <h3>Download by Artifact ID</h3>
-        <div className="download-by-id-form">
-          <input
-            type="text"
-            value={artifactIdInput}
-            onChange={(e) => setArtifactIdInput(e.target.value.toLowerCase().replace(/[^a-f0-9]/g, '').slice(0, 64))}
-            placeholder="Enter SHA256 artifact ID (64 hex characters)"
-            className="artifact-id-input"
-          />
-          <a
-            href={artifactIdInput.length === 64 ? getDownloadUrl(projectName!, packageName!, `artifact:${artifactIdInput}`) : '#'}
-            className={`btn btn-primary ${artifactIdInput.length !== 64 ? 'btn-disabled' : ''}`}
-            download
-            onClick={(e) => {
-              if (artifactIdInput.length !== 64) {
-                e.preventDefault();
-              }
-            }}
-          >
-            Download
-          </a>
-        </div>
-        {artifactIdInput.length > 0 && artifactIdInput.length !== 64 && (
-          <p className="validation-hint">Artifact ID must be exactly 64 hex characters ({artifactIdInput.length}/64)</p>
-        )}
-      </div>
-
-      {user && canWrite && (
-        <div className="create-tag-section card">
-          <h3>Create / Update Tag</h3>
-          <p className="section-description">Point a tag at any existing artifact by its ID</p>
-          <form onSubmit={handleCreateTag} className="create-tag-form">
-            <div className="form-row">
-              <div className="form-group">
-                <label htmlFor="create-tag-name">Tag Name</label>
-                <input
-                  id="create-tag-name"
-                  type="text"
-                  value={createTagName}
-                  onChange={(e) => setCreateTagName(e.target.value)}
-                  placeholder="latest, stable, v1.0.0..."
-                  disabled={createTagLoading}
-                />
-              </div>
-              <div className="form-group form-group--wide">
-                <label htmlFor="create-tag-artifact">Artifact ID</label>
-                <input
-                  id="create-tag-artifact"
-                  type="text"
-                  value={createTagArtifactId}
-                  onChange={(e) => setCreateTagArtifactId(e.target.value.toLowerCase().replace(/[^a-f0-9]/g, '').slice(0, 64))}
-                  placeholder="SHA256 hash (64 hex characters)"
-                  className="artifact-id-input"
-                  disabled={createTagLoading}
-                />
-              </div>
-              <button
-                type="submit"
-                className="btn btn-primary"
-                disabled={createTagLoading || !createTagName.trim() || createTagArtifactId.length !== 64}
-              >
-                {createTagLoading ? 'Creating...' : 'Create Tag'}
-              </button>
-            </div>
-            {createTagArtifactId.length > 0 && createTagArtifactId.length !== 64 && (
-              <p className="validation-hint">Artifact ID must be exactly 64 hex characters ({createTagArtifactId.length}/64)</p>
-            )}
-          </form>
         </div>
       )}
 
@@ -815,22 +702,54 @@ function PackagePage() {
         <pre>
           <code>curl -O {window.location.origin}/api/v1/project/{projectName}/{packageName}/+/latest</code>
         </pre>
-        <p>Or with a specific tag:</p>
+        <p>Or with a specific version:</p>
         <pre>
-          <code>curl -O {window.location.origin}/api/v1/project/{projectName}/{packageName}/+/v1.0.0</code>
+          <code>curl -O {window.location.origin}/api/v1/project/{projectName}/{packageName}/+/1.0.0</code>
         </pre>
       </div>
 
       {/* Dependency Graph Modal */}
-      {showGraph && selectedTag && (
+      {showGraph && selectedArtifact && (
         <DependencyGraph
           projectName={projectName!}
           packageName={packageName!}
-          tagName={selectedTag.name}
+          tagName={getArtifactVersion(selectedArtifact) || `artifact:${selectedArtifact.id}`}
           onClose={() => setShowGraph(false)}
         />
       )}
 
+      {/* Upload Modal */}
+      {showUploadModal && (
+        <div className="modal-overlay" onClick={() => setShowUploadModal(false)}>
+          <div className="upload-modal" onClick={(e) => e.stopPropagation()}>
+            <div className="modal-header">
+              <h3>Upload Artifact</h3>
+              <button
+                className="modal-close"
+                onClick={() => setShowUploadModal(false)}
+                title="Close"
+              >
+                <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                  <line x1="18" y1="6" x2="6" y2="18"></line>
+                  <line x1="6" y1="6" x2="18" y2="18"></line>
+                </svg>
+              </button>
+            </div>
+            <div className="modal-body">
+              <DragDropUpload
+                projectName={projectName!}
+                packageName={packageName!}
+                onUploadComplete={(result) => {
+                  handleUploadComplete(result);
+                  setShowUploadModal(false);
+                }}
+                onUploadError={handleUploadError}
+              />
+            </div>
+          </div>
+        </div>
+      )}
+
       {/* Ensure File Modal */}
       {showEnsureFile && (
         <div className="modal-overlay" onClick={() => setShowEnsureFile(false)}>
@@ -872,6 +791,107 @@ function PackagePage() {
           </div>
         </div>
       )}
+
+      {/* Dependencies Modal */}
+      {showDepsModal && selectedArtifact && (
+        <div className="modal-overlay" onClick={() => setShowDepsModal(false)}>
+          <div className="deps-modal" onClick={(e) => e.stopPropagation()}>
+            <div className="modal-header">
+              <h3>Dependencies for {selectedArtifact.original_name || selectedArtifact.id.slice(0, 12)}</h3>
+              <button
+                className="modal-close"
+                onClick={() => setShowDepsModal(false)}
+                title="Close"
+              >
+                <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                  <line x1="18" y1="6" x2="6" y2="18"></line>
+                  <line x1="6" y1="6" x2="18" y2="18"></line>
+                </svg>
+              </button>
+            </div>
+            <div className="modal-body">
+              <div className="deps-modal-controls">
+                <button
+                  className="btn btn-secondary btn-small"
+                  onClick={fetchEnsureFile}
+                  disabled={ensureFileLoading}
+                >
+                  View Ensure File
+                </button>
+                <button
+                  className="btn btn-secondary btn-small"
+                  onClick={() => { setShowDepsModal(false); setShowGraph(true); }}
+                >
+                  View Graph
+                </button>
+              </div>
+              {depsLoading ? (
+                <div className="deps-loading">Loading dependencies...</div>
+              ) : depsError ? (
+                <div className="deps-error">{depsError}</div>
+              ) : dependencies.length === 0 ? (
+                <div className="deps-empty">No dependencies</div>
+              ) : (
+                <div className="deps-list">
+                  <div className="deps-summary">
+                    {dependencies.length} {dependencies.length === 1 ? 'dependency' : 'dependencies'}:
+                  </div>
+                  <ul className="deps-items">
+                    {dependencies.map((dep) => (
+                      <li key={dep.id} className="dep-item">
+                        <Link
+                          to={`/project/${dep.project}/${dep.package}`}
+                          className="dep-link"
+                          onClick={() => setShowDepsModal(false)}
+                        >
+                          {dep.project}/{dep.package}
+                        </Link>
+                        <span className="dep-constraint">
+                          @ {dep.version}
+                        </span>
+                        <span className="dep-status dep-status--ok" title="Package exists">
+                          &#10003;
+                        </span>
+                      </li>
+                    ))}
+                  </ul>
+                </div>
+              )}
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Artifact ID Modal */}
+      {showArtifactIdModal && viewArtifactId && (
+        <div className="modal-overlay" onClick={() => setShowArtifactIdModal(false)}>
+          <div className="artifact-id-modal" onClick={(e) => e.stopPropagation()}>
+            <div className="modal-header">
+              <h3>Artifact ID</h3>
+              <button
+                className="modal-close"
+                onClick={() => setShowArtifactIdModal(false)}
+                title="Close"
+              >
+                <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                  <line x1="18" y1="6" x2="6" y2="18"></line>
+                  <line x1="6" y1="6" x2="18" y2="18"></line>
+                </svg>
+              </button>
+            </div>
+            <div className="modal-body">
+              <p className="modal-description">SHA256 hash identifying this artifact:</p>
+              <div className="artifact-id-display">
+                <code>{viewArtifactId}</code>
+                <CopyButton text={viewArtifactId} />
+              </div>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Action Menu Dropdown */}
+      {renderActionMenu()}
     </div>
   );
 }

frontend/src/pages/ProjectPage.tsx

@@ -195,6 +195,9 @@ function ProjectPage() {
             <Badge variant={project.is_public ? 'public' : 'private'}>
               {project.is_public ? 'Public' : 'Private'}
             </Badge>
+            {project.is_system && (
+              <Badge variant="warning">System Cache</Badge>
+            )}
             {accessLevel && (
               <Badge variant={accessLevel === 'admin' ? 'success' : accessLevel === 'write' ? 'info' : 'default'}>
                 {isOwner ? 'Owner' : accessLevel.charAt(0).toUpperCase() + accessLevel.slice(1)}
@@ -211,7 +214,7 @@ function ProjectPage() {
           </div>
         </div>
         <div className="page-header__actions">
-          {canAdmin && !project.team_id && (
+          {canAdmin && !project.team_id && !project.is_system && (
             <button
               className="btn btn-secondary"
               onClick={() => navigate(`/project/${projectName}/settings`)}
@@ -224,11 +227,11 @@ function ProjectPage() {
               Settings
             </button>
           )}
-          {canWrite ? (
+          {canWrite && !project.is_system ? (
             <button className="btn btn-primary" onClick={() => setShowForm(!showForm)}>
               {showForm ? 'Cancel' : '+ New Package'}
             </button>
-          ) : user ? (
+          ) : user && !project.is_system ? (
             <span className="text-muted" title="You have read-only access to this project">
               Read-only access
             </span>
@@ -291,6 +294,7 @@ function ProjectPage() {
           placeholder="Filter packages..."
           className="list-controls__search"
         />
+        {!project?.is_system && (
           <select
             className="list-controls__select"
             value={format}
@@ -303,6 +307,7 @@ function ProjectPage() {
               </option>
             ))}
           </select>
+        )}
       </div>
 
       {hasActiveFilters && (
@@ -338,19 +343,19 @@ function ProjectPage() {
               className: 'cell-description',
               render: (pkg) => pkg.description || '—',
             },
-            {
+            ...(!project?.is_system ? [{
               key: 'format',
               header: 'Format',
-              render: (pkg) => <Badge variant="default">{pkg.format}</Badge>,
-            },
-            {
-              key: 'tag_count',
-              header: 'Tags',
-              render: (pkg) => pkg.tag_count ?? '—',
-            },
+              render: (pkg: Package) => <Badge variant="default">{pkg.format}</Badge>,
+            }] : []),
+            ...(!project?.is_system ? [{
+              key: 'version_count',
+              header: 'Versions',
+              render: (pkg: Package) => pkg.version_count ?? '—',
+            }] : []),
             {
               key: 'artifact_count',
-              header: 'Artifacts',
+              header: project?.is_system ? 'Versions' : 'Artifacts',
               render: (pkg) => pkg.artifact_count ?? '—',
             },
             {
@@ -359,12 +364,12 @@ function ProjectPage() {
               render: (pkg) =>
                 pkg.total_size !== undefined && pkg.total_size > 0 ? formatBytes(pkg.total_size) : '—',
             },
-            {
-              key: 'latest_tag',
+            ...(!project?.is_system ? [{
+              key: 'latest_version',
               header: 'Latest',
-              render: (pkg) =>
-                pkg.latest_tag ? <strong style={{ color: 'var(--accent-primary)' }}>{pkg.latest_tag}</strong> : '—',
-            },
+              render: (pkg: Package) =>
+                pkg.latest_version ? <strong style={{ color: 'var(--accent-primary)' }}>{pkg.latest_version}</strong> : '—',
+            }] : []),
             {
               key: 'created_at',
               header: 'Created',

frontend/src/types.ts

@@ -6,6 +6,7 @@ export interface Project {
   name: string;
   description: string | null;
   is_public: boolean;
+  is_system?: boolean;  // True for system cache projects (_npm, _pypi, etc.)
   created_at: string;
   updated_at: string;
   created_by: string;
@@ -18,12 +19,6 @@ export interface Project {
   team_name?: string | null;
 }
 
-export interface TagSummary {
-  name: string;
-  artifact_id: string;
-  created_at: string;
-}
-
 export interface Package {
   id: string;
   project_id: string;
@@ -34,12 +29,11 @@ export interface Package {
   created_at: string;
   updated_at: string;
   // Aggregated fields (from PackageDetailResponse)
-  tag_count?: number;
   artifact_count?: number;
+  version_count?: number;
   total_size?: number;
-  latest_tag?: string | null;
   latest_upload_at?: string | null;
-  recent_tags?: TagSummary[];
+  latest_version?: string | null;
 }
 
 export interface Artifact {
@@ -52,22 +46,19 @@ export interface Artifact {
   ref_count: number;
 }
 
-export interface Tag {
+export interface PackageArtifact {
   id: string;
-  package_id: string;
-  name: string;
-  artifact_id: string;
+  sha256: string;
+  size: number;
+  content_type: string | null;
+  original_name: string | null;
+  checksum_md5?: string | null;
+  checksum_sha1?: string | null;
+  s3_etag?: string | null;
   created_at: string;
   created_by: string;
-}
-
-export interface TagDetail extends Tag {
-  artifact_size: number;
-  artifact_content_type: string | null;
-  artifact_original_name: string | null;
-  artifact_created_at: string;
-  artifact_format_metadata: Record<string, unknown> | null;
-  version: string | null;
+  format_metadata?: Record<string, unknown> | null;
+  version?: string | null;  // Version from PackageVersion if exists
 }
 
 export interface PackageVersion {
@@ -82,20 +73,9 @@ export interface PackageVersion {
   size?: number;
   content_type?: string | null;
   original_name?: string | null;
-  tags?: string[];
 }
 
-export interface ArtifactTagInfo {
-  id: string;
-  name: string;
-  package_id: string;
-  package_name: string;
-  project_name: string;
-}
-
-export interface ArtifactDetail extends Artifact {
-  tags: ArtifactTagInfo[];
-}
+export interface ArtifactDetail extends Artifact {}
 
 export interface PaginatedResponse<T> {
   items: T[];
@@ -115,8 +95,6 @@ export interface ListParams {
   order?: 'asc' | 'desc';
 }
 
-export interface TagListParams extends ListParams {}
-
 export interface PackageListParams extends ListParams {
   format?: string;
   platform?: string;
@@ -141,7 +119,6 @@ export interface UploadResponse {
   size: number;
   project: string;
   package: string;
-  tag: string | null;
   version: string | null;
   version_source: string | null;
 }
@@ -164,9 +141,8 @@ export interface SearchResultPackage {
 }
 
 export interface SearchResultArtifact {
-  tag_id: string;
-  tag_name: string;
   artifact_id: string;
+  version: string | null;
   package_id: string;
   package_name: string;
   project_name: string;
@@ -389,8 +365,7 @@ export interface Dependency {
   artifact_id: string;
   project: string;
   package: string;
-  version: string | null;
-  tag: string | null;
+  version: string;
   created_at: string;
 }
 
@@ -404,7 +379,6 @@ export interface DependentInfo {
   project: string;
   package: string;
   version: string | null;
-  constraint_type: 'version' | 'tag';
   constraint_value: string;
 }
 
@@ -427,11 +401,17 @@ export interface ResolvedArtifact {
   project: string;
   package: string;
   version: string | null;
-  tag: string | null;
   size: number;
   download_url: string;
 }
 
+export interface MissingDependency {
+  project: string;
+  package: string;
+  constraint: string | null;
+  required_by: string | null;
+}
+
 export interface DependencyResolutionResponse {
   requested: {
     project: string;
@@ -439,6 +419,7 @@ export interface DependencyResolutionResponse {
     ref: string;
   };
   resolved: ResolvedArtifact[];
+  missing: MissingDependency[];
   total_size: number;
   artifact_count: number;
 }
@@ -503,3 +484,56 @@ export interface TeamMemberCreate {
 export interface TeamMemberUpdate {
   role: TeamRole;
 }
+
+// Upstream Source types
+export type SourceType = 'npm' | 'pypi' | 'maven' | 'docker' | 'helm' | 'nuget' | 'deb' | 'rpm' | 'generic';
+export type AuthType = 'none' | 'basic' | 'bearer' | 'api_key';
+
+export interface UpstreamSource {
+  id: string;
+  name: string;
+  source_type: SourceType;
+  url: string;
+  enabled: boolean;
+  auth_type: AuthType;
+  username: string | null;
+  has_password: boolean;
+  has_headers: boolean;
+  priority: number;
+  source: 'database' | 'env';
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface UpstreamSourceCreate {
+  name: string;
+  source_type: SourceType;
+  url: string;
+  enabled?: boolean;
+  auth_type?: AuthType;
+  username?: string;
+  password?: string;
+  headers?: Record<string, string>;
+  priority?: number;
+}
+
+export interface UpstreamSourceUpdate {
+  name?: string;
+  source_type?: SourceType;
+  url?: string;
+  enabled?: boolean;
+  auth_type?: AuthType;
+  username?: string;
+  password?: string;
+  headers?: Record<string, string> | null;
+  priority?: number;
+}
+
+export interface UpstreamSourceTestResult {
+  success: boolean;
+  status_code: number | null;
+  elapsed_ms: number;
+  error: string | null;
+  source_id: string;
+  source_name: string;
+}

helm/orchard/templates/deployment.yaml

@@ -128,6 +128,10 @@ spec:
               value: {{ .Values.orchard.rateLimit.login | quote }}
             {{- end }}
             {{- end }}
+            {{- if .Values.orchard.purgeSeedData }}
+            - name: ORCHARD_PURGE_SEED_DATA
+              value: "true"
+            {{- end }}
             {{- if .Values.orchard.database.poolSize }}
             - name: ORCHARD_DATABASE_POOL_SIZE
               value: {{ .Values.orchard.database.poolSize | quote }}
@@ -140,6 +144,20 @@ spec:
             - name: ORCHARD_DATABASE_POOL_TIMEOUT
               value: {{ .Values.orchard.database.poolTimeout | quote }}
             {{- end }}
+            {{- if .Values.orchard.pypiCache }}
+            {{- if .Values.orchard.pypiCache.workers }}
+            - name: ORCHARD_PYPI_CACHE_WORKERS
+              value: {{ .Values.orchard.pypiCache.workers | quote }}
+            {{- end }}
+            {{- if .Values.orchard.pypiCache.maxDepth }}
+            - name: ORCHARD_PYPI_CACHE_MAX_DEPTH
+              value: {{ .Values.orchard.pypiCache.maxDepth | quote }}
+            {{- end }}
+            {{- if .Values.orchard.pypiCache.maxAttempts }}
+            - name: ORCHARD_PYPI_CACHE_MAX_ATTEMPTS
+              value: {{ .Values.orchard.pypiCache.maxAttempts | quote }}
+            {{- end }}
+            {{- end }}
             {{- if .Values.orchard.auth }}
             {{- if or .Values.orchard.auth.secretsManager .Values.orchard.auth.existingSecret .Values.orchard.auth.adminPassword }}
             - name: ORCHARD_ADMIN_PASSWORD

helm/orchard/values-dev.yaml

@@ -59,10 +59,10 @@ ingress:
 resources:
   limits:
     cpu: 500m
-    memory: 512Mi
+    memory: 1Gi
   requests:
     cpu: 200m
-    memory: 512Mi
+    memory: 1Gi
 
 livenessProbe:
   httpGet:
@@ -124,6 +124,12 @@ orchard:
     mode: "presigned"
     presignedUrlExpiry: 3600
 
+  # PyPI Cache Worker settings (reduced workers to limit memory usage)
+  pypiCache:
+    workers: 1
+    maxDepth: 10
+    maxAttempts: 3
+
   # Relaxed rate limits for dev/feature environments (allows integration tests to run)
   rateLimit:
     login: "1000/minute"  # Default is 5/minute, relaxed for CI integration tests

helm/orchard/values-prod.yaml

@@ -57,10 +57,10 @@ ingress:
 resources:
   limits:
     cpu: 500m
-    memory: 512Mi
+    memory: 768Mi
   requests:
     cpu: 500m
-    memory: 512Mi
+    memory: 768Mi
 
 livenessProbe:
   httpGet:
@@ -121,6 +121,12 @@ orchard:
     mode: "presigned"
     presignedUrlExpiry: 3600
 
+  # PyPI Cache Worker settings (reduced workers to limit memory usage)
+  pypiCache:
+    workers: 2
+    maxDepth: 10
+    maxAttempts: 3
+
 # PostgreSQL subchart - disabled in prod, using RDS
 postgresql:
   enabled: false

helm/orchard/values-stage.yaml

@@ -56,10 +56,10 @@ ingress:
 resources:
   limits:
     cpu: 500m
-    memory: 512Mi
+    memory: 768Mi
   requests:
     cpu: 500m
-    memory: 512Mi
+    memory: 768Mi
 
 livenessProbe:
   httpGet:
@@ -91,6 +91,7 @@ affinity: {}
 # Orchard server configuration
 orchard:
   env: "development"  # Allows seed data for testing
+  purgeSeedData: true  # Remove public seed data (npm-public, pypi-public, etc.)
   server:
     host: "0.0.0.0"
     port: 8080
@@ -121,6 +122,12 @@ orchard:
     mode: "presigned"  # presigned, redirect, or proxy
     presignedUrlExpiry: 3600  # Presigned URL expiry in seconds
 
+  # PyPI Cache Worker settings (reduced workers to limit memory usage)
+  pypiCache:
+    workers: 2
+    maxDepth: 10
+    maxAttempts: 3
+
   # Relaxed rate limits for stage (allows CI integration tests to run)
   rateLimit:
     login: "1000/minute"  # Default is 5/minute, relaxed for CI integration tests

helm/orchard/values.yaml

@@ -54,10 +54,10 @@ ingress:
 resources:
   limits:
     cpu: 500m
-    memory: 512Mi
+    memory: 768Mi
   requests:
     cpu: 500m
-    memory: 512Mi
+    memory: 768Mi
 
 livenessProbe:
   httpGet:
@@ -120,6 +120,12 @@ orchard:
     mode: "presigned"  # presigned, redirect, or proxy
     presignedUrlExpiry: 3600  # Presigned URL expiry in seconds
 
+  # PyPI Cache Worker settings
+  pypiCache:
+    workers: 2  # Number of concurrent cache workers (reduced to limit memory usage)
+    maxDepth: 10  # Maximum recursion depth for dependency caching
+    maxAttempts: 3  # Maximum retry attempts for failed cache tasks
+
   # Authentication settings
   auth:
     # Option 1: Plain admin password (creates K8s secret)

migrations/010_upstream_caching.sql

@@ -0,0 +1,137 @@
+-- Migration 010: Upstream Artifact Caching
+-- Adds support for caching artifacts from upstream registries (npm, PyPI, Maven, etc.)
+-- Part of "The cache that never forgets" epic for hermetic builds
+
+-- =============================================================================
+-- upstream_sources: Configure upstream registries for artifact caching
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS upstream_sources (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name VARCHAR(255) NOT NULL UNIQUE,
+    source_type VARCHAR(50) NOT NULL DEFAULT 'generic',
+    url VARCHAR(2048) NOT NULL,
+    enabled BOOLEAN NOT NULL DEFAULT FALSE,
+    is_public BOOLEAN NOT NULL DEFAULT TRUE,
+    auth_type VARCHAR(20) NOT NULL DEFAULT 'none',
+    username VARCHAR(255),
+    password_encrypted BYTEA,
+    headers_encrypted BYTEA,
+    priority INTEGER NOT NULL DEFAULT 100,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+
+    -- Source type must be one of the supported types
+    CONSTRAINT check_source_type CHECK (
+        source_type IN ('npm', 'pypi', 'maven', 'docker', 'helm', 'nuget', 'deb', 'rpm', 'generic')
+    ),
+
+    -- Auth type must be valid
+    CONSTRAINT check_auth_type CHECK (
+        auth_type IN ('none', 'basic', 'bearer', 'api_key')
+    ),
+
+    -- Priority must be positive
+    CONSTRAINT check_priority_positive CHECK (priority > 0)
+);
+
+-- Indexes for upstream_sources
+CREATE INDEX IF NOT EXISTS idx_upstream_sources_enabled ON upstream_sources(enabled);
+CREATE INDEX IF NOT EXISTS idx_upstream_sources_source_type ON upstream_sources(source_type);
+CREATE INDEX IF NOT EXISTS idx_upstream_sources_is_public ON upstream_sources(is_public);
+CREATE INDEX IF NOT EXISTS idx_upstream_sources_priority ON upstream_sources(priority);
+
+-- Comments for upstream_sources
+COMMENT ON TABLE upstream_sources IS 'Configuration for upstream artifact registries (npm, PyPI, Maven, etc.)';
+COMMENT ON COLUMN upstream_sources.name IS 'Unique human-readable name (e.g., npm-public, artifactory-private)';
+COMMENT ON COLUMN upstream_sources.source_type IS 'Type of registry: npm, pypi, maven, docker, helm, nuget, deb, rpm, generic';
+COMMENT ON COLUMN upstream_sources.url IS 'Base URL of the upstream registry';
+COMMENT ON COLUMN upstream_sources.enabled IS 'Whether this source is active for caching';
+COMMENT ON COLUMN upstream_sources.is_public IS 'True if this is a public internet source (for air-gap mode)';
+COMMENT ON COLUMN upstream_sources.auth_type IS 'Authentication type: none, basic, bearer, api_key';
+COMMENT ON COLUMN upstream_sources.username IS 'Username for basic auth';
+COMMENT ON COLUMN upstream_sources.password_encrypted IS 'Fernet-encrypted password/token';
+COMMENT ON COLUMN upstream_sources.headers_encrypted IS 'Fernet-encrypted custom headers (JSON)';
+COMMENT ON COLUMN upstream_sources.priority IS 'Priority for source selection (lower = higher priority)';
+
+-- =============================================================================
+-- cache_settings: Global cache configuration (singleton table)
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cache_settings (
+    id INTEGER PRIMARY KEY DEFAULT 1,
+    allow_public_internet BOOLEAN NOT NULL DEFAULT TRUE,
+    auto_create_system_projects BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+
+    -- Singleton constraint
+    CONSTRAINT check_cache_settings_singleton CHECK (id = 1)
+);
+
+-- Insert default row
+INSERT INTO cache_settings (id, allow_public_internet, auto_create_system_projects)
+VALUES (1, TRUE, TRUE)
+ON CONFLICT (id) DO NOTHING;
+
+-- Comments for cache_settings
+COMMENT ON TABLE cache_settings IS 'Global cache settings (singleton table)';
+COMMENT ON COLUMN cache_settings.allow_public_internet IS 'Air-gap mode: when false, blocks all public internet sources';
+COMMENT ON COLUMN cache_settings.auto_create_system_projects IS 'Auto-create system projects (_npm, _pypi, etc.) on first cache';
+
+-- =============================================================================
+-- cached_urls: Track URL to artifact mappings for provenance
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cached_urls (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    url VARCHAR(4096) NOT NULL,
+    url_hash VARCHAR(64) NOT NULL,
+    artifact_id VARCHAR(64) NOT NULL REFERENCES artifacts(id),
+    source_id UUID REFERENCES upstream_sources(id) ON DELETE SET NULL,
+    fetched_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    response_headers JSONB DEFAULT '{}',
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+
+    -- URL hash must be unique (same URL = same cached artifact)
+    CONSTRAINT unique_url_hash UNIQUE (url_hash)
+);
+
+-- Indexes for cached_urls
+CREATE INDEX IF NOT EXISTS idx_cached_urls_url_hash ON cached_urls(url_hash);
+CREATE INDEX IF NOT EXISTS idx_cached_urls_artifact_id ON cached_urls(artifact_id);
+CREATE INDEX IF NOT EXISTS idx_cached_urls_source_id ON cached_urls(source_id);
+CREATE INDEX IF NOT EXISTS idx_cached_urls_fetched_at ON cached_urls(fetched_at);
+
+-- Comments for cached_urls
+COMMENT ON TABLE cached_urls IS 'Tracks which URLs have been cached and maps to artifacts';
+COMMENT ON COLUMN cached_urls.url IS 'Original URL that was fetched';
+COMMENT ON COLUMN cached_urls.url_hash IS 'SHA256 hash of URL for fast lookup';
+COMMENT ON COLUMN cached_urls.artifact_id IS 'The cached artifact (by SHA256 content hash)';
+COMMENT ON COLUMN cached_urls.source_id IS 'Which upstream source provided this (null if manual)';
+COMMENT ON COLUMN cached_urls.fetched_at IS 'When the URL was fetched from upstream';
+COMMENT ON COLUMN cached_urls.response_headers IS 'Original response headers from upstream (for debugging)';
+
+-- =============================================================================
+-- Add is_system column to projects table for system cache projects
+-- =============================================================================
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM information_schema.columns
+        WHERE table_name = 'projects' AND column_name = 'is_system'
+    ) THEN
+        ALTER TABLE projects ADD COLUMN is_system BOOLEAN NOT NULL DEFAULT FALSE;
+        CREATE INDEX IF NOT EXISTS idx_projects_is_system ON projects(is_system);
+    END IF;
+END $$;
+
+COMMENT ON COLUMN projects.is_system IS 'True for system cache projects (_npm, _pypi, etc.)';
+
+-- =============================================================================
+-- Seed default upstream sources (disabled by default for safety)
+-- =============================================================================
+INSERT INTO upstream_sources (id, name, source_type, url, enabled, is_public, auth_type, priority)
+VALUES
+    (gen_random_uuid(), 'npm-public', 'npm', 'https://registry.npmjs.org', FALSE, TRUE, 'none', 100),
+    (gen_random_uuid(), 'pypi-public', 'pypi', 'https://pypi.org/simple', FALSE, TRUE, 'none', 100),
+    (gen_random_uuid(), 'maven-central', 'maven', 'https://repo1.maven.org/maven2', FALSE, TRUE, 'none', 100),
+    (gen_random_uuid(), 'docker-hub', 'docker', 'https://registry-1.docker.io', FALSE, TRUE, 'none', 100)
+ON CONFLICT (name) DO NOTHING;

migrations/011_pypi_cache_tasks.sql

@@ -0,0 +1,55 @@
+-- Migration: 011_pypi_cache_tasks
+-- Description: Add table for tracking PyPI dependency caching tasks
+-- Date: 2026-02-02
+
+-- Table for tracking PyPI cache tasks with retry support
+CREATE TABLE pypi_cache_tasks (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+
+    -- What to cache
+    package_name VARCHAR(255) NOT NULL,
+    version_constraint VARCHAR(255),
+
+    -- Origin tracking
+    parent_task_id UUID REFERENCES pypi_cache_tasks(id) ON DELETE SET NULL,
+    depth INTEGER NOT NULL DEFAULT 0,
+    triggered_by_artifact VARCHAR(64) REFERENCES artifacts(id) ON DELETE SET NULL,
+
+    -- Status
+    status VARCHAR(20) NOT NULL DEFAULT 'pending',
+    attempts INTEGER NOT NULL DEFAULT 0,
+    max_attempts INTEGER NOT NULL DEFAULT 3,
+
+    -- Results
+    cached_artifact_id VARCHAR(64) REFERENCES artifacts(id) ON DELETE SET NULL,
+    error_message TEXT,
+
+    -- Timing
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    started_at TIMESTAMP WITH TIME ZONE,
+    completed_at TIMESTAMP WITH TIME ZONE,
+    next_retry_at TIMESTAMP WITH TIME ZONE,
+
+    -- Constraints
+    CONSTRAINT check_task_status CHECK (status IN ('pending', 'in_progress', 'completed', 'failed')),
+    CONSTRAINT check_depth_non_negative CHECK (depth >= 0),
+    CONSTRAINT check_attempts_non_negative CHECK (attempts >= 0)
+);
+
+-- Index for finding tasks ready to process (pending with retry time passed)
+CREATE INDEX idx_pypi_cache_tasks_status_retry ON pypi_cache_tasks(status, next_retry_at);
+
+-- Index for deduplication check (is this package already queued?)
+CREATE INDEX idx_pypi_cache_tasks_package_status ON pypi_cache_tasks(package_name, status);
+
+-- Index for tracing dependency chains
+CREATE INDEX idx_pypi_cache_tasks_parent ON pypi_cache_tasks(parent_task_id);
+
+-- Index for finding tasks by artifact that triggered them
+CREATE INDEX idx_pypi_cache_tasks_triggered_by ON pypi_cache_tasks(triggered_by_artifact);
+
+-- Index for finding tasks by cached artifact
+CREATE INDEX idx_pypi_cache_tasks_cached_artifact ON pypi_cache_tasks(cached_artifact_id);
+
+-- Index for sorting by depth and creation time (processing order)
+CREATE INDEX idx_pypi_cache_tasks_depth_created ON pypi_cache_tasks(depth, created_at);

migrations/012_remove_tags.sql

@@ -0,0 +1,33 @@
+-- Migration: Remove tag system
+-- Date: 2026-02-03
+-- Description: Remove tags table and related objects, keeping only versions for artifact references
+
+-- Drop triggers on tags table
+DROP TRIGGER IF EXISTS tags_ref_count_insert_trigger ON tags;
+DROP TRIGGER IF EXISTS tags_ref_count_delete_trigger ON tags;
+DROP TRIGGER IF EXISTS tags_ref_count_update_trigger ON tags;
+DROP TRIGGER IF EXISTS tags_updated_at_trigger ON tags;
+DROP TRIGGER IF EXISTS tag_changes_trigger ON tags;
+
+-- Drop the tag change tracking function
+DROP FUNCTION IF EXISTS track_tag_changes();
+
+-- Remove tag_constraint from artifact_dependencies
+-- First drop the constraint that requires either version or tag
+ALTER TABLE artifact_dependencies DROP CONSTRAINT IF EXISTS check_constraint_type;
+
+-- Remove the tag_constraint column
+ALTER TABLE artifact_dependencies DROP COLUMN IF EXISTS tag_constraint;
+
+-- Make version_constraint NOT NULL (now the only option)
+UPDATE artifact_dependencies SET version_constraint = '*' WHERE version_constraint IS NULL;
+ALTER TABLE artifact_dependencies ALTER COLUMN version_constraint SET NOT NULL;
+
+-- Drop tag_history table first (depends on tags)
+DROP TABLE IF EXISTS tag_history;
+
+-- Drop tags table
+DROP TABLE IF EXISTS tags;
+
+-- Rename uploads.tag_name to uploads.version (historical data field)
+ALTER TABLE uploads RENAME COLUMN tag_name TO version;