feat(snapshot): namespace spec, persistent sources and scoped read foundations

.github/workflows/base.yml

@@ -261,6 +261,7 @@ jobs:
           sccache --start-server || true
           cargo test --manifest-path common/Cargo.toml --all-features --no-fail-fast -- --nocapture
           cargo test --manifest-path jupiter/Cargo.toml --all-features --no-fail-fast -- --nocapture
+          cargo test --manifest-path jupiter-migrate/Cargo.toml --all-features --no-fail-fast -- --nocapture
           cargo test --manifest-path ceres/Cargo.toml --all-features --no-fail-fast -- --nocapture
           cargo test --manifest-path vault/Cargo.toml --all-features --no-fail-fast -- --nocapture
           cargo test --manifest-path saturn/Cargo.toml --all-features --no-fail-fast -- --nocapture
@@ -269,3 +270,47 @@ jobs:
 
   # Note: The fuse/scorpio job has been removed as scorpio has been moved
   # to its own repository: https://github.com/gitmono-dev/scorpiofs
+
+  snapshot-contract:
+    name: Snapshot PostgreSQL and index gates
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: snapshot_fixture
+          POSTGRES_PASSWORD: fixture-local-only
+          POSTGRES_DB: snapshot_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U snapshot_fixture -d snapshot_test"
+          --health-interval 5s --health-timeout 5s --health-retries 20
+    env:
+      CARGO_TERM_COLOR: always
+      RUSTUP_TOOLCHAIN: stable
+      MEGA_SNAPSHOT_TEST_DATABASE_URL: postgres://snapshot_fixture:fixture-local-only@127.0.0.1:5432/snapshot_test
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install focused Rust build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake build-essential pkg-config libssl-dev nettle-dev protobuf-compiler
+          rustup toolchain install stable --profile minimal
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: base-${{ runner.os }}-${{ hashFiles('**/Cargo.lock') }}
+          cache-on-failure: true
+      - name: Snapshot migration and UTC upgrade tests
+        run: cargo test -p jupiter-migrate --lib snapshot --locked -j 2 -- --include-ignored --nocapture
+      - name: Source identity and immutable node storage tests
+        run: |
+          cargo test -p jupiter --lib snapshot_storage --locked -j 2
+          cargo test -p jupiter --lib namespace_storage --locked -j 2
+      - name: Snapshot contracts, PostgreSQL transactions and million-binding gate
+        run: cargo test -p ceres --lib snapshot --locked -j 2 -- --include-ignored --nocapture
+      - name: Publication receipts, ref CAS, rollback and concurrency on both databases
+        run: cargo test -p jupiter --lib publication_storage --locked -j 2 -- --include-ignored --nocapture

ceres/Cargo.toml

@@ -29,7 +29,7 @@ rand = { workspace = true, features = ["thread_rng"] }
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
 sha1 = { workspace = true }
-sha2 = { workspace = true, optional = true }
+sha2 = { workspace = true }
 tempfile = { workspace = true, optional = true }
 thiserror = { workspace = true, optional = true }
 tracing = { workspace = true }
@@ -46,7 +46,7 @@ tokio-util = { workspace = true }
 rkyv = { workspace = true }
 
 [features]
-fastcdc = ["dep:sha2", "dep:tempfile", "dep:thiserror"]
+fastcdc = ["dep:tempfile", "dep:thiserror"]
 migrate = ["jupiter/migrate"]
 
 [dev-dependencies]

ceres/src/application/api_service/import_api_service.rs

@@ -112,32 +112,26 @@ impl ApiHandler for ImportApiService {
 
     async fn get_root_commit(&self) -> Result<Commit, MegaError> {
         let storage = self.storage.git_db_storage();
-        let refs = storage.get_default_ref(self.repo.repo_id).await?.unwrap();
-        self.get_commit_by_hash(&refs.ref_git_id).await
+        let source = crate::application::snapshot::source::resolve_import_commit(
+            &storage,
+            self.repo.repo_id,
+            None,
+        )
+        .await?;
+        self.get_commit_by_hash(&source.commit_oid).await
     }
 
-    /// Note: The `refs` parameter is intentionally ignored for import repositories,
-    /// as they do not support selecting refs. The default ref is always used.
-    async fn get_root_tree(&self, _: Option<&str>) -> Result<Tree, MegaError> {
+    /// Resolve once, then read that immutable root. An explicit revision must
+    /// never silently fall back to the repository's current default branch.
+    async fn get_root_tree(&self, refs: Option<&str>) -> Result<Tree, MegaError> {
         let storage = self.storage.git_db_storage();
-        let refs = storage
-            .get_default_ref(self.repo.repo_id)
-            .await
-            .unwrap()
-            .unwrap();
-
-        let root_commit = storage
-            .get_commit_by_hash(self.repo.repo_id, &refs.ref_git_id)
-            .await
-            .unwrap()
-            .unwrap();
-        Ok(Tree::from_git_model(
-            storage
-                .get_tree_by_hash(self.repo.repo_id, &root_commit.tree)
-                .await
-                .unwrap()
-                .unwrap(),
-        ))
+        let source = crate::application::snapshot::source::resolve_import_commit(
+            &storage,
+            self.repo.repo_id,
+            refs,
+        )
+        .await?;
+        crate::application::snapshot::source::read_import_root(&storage, &source).await
     }
 
     async fn get_tree_by_hash(&self, hash: &str) -> Result<Tree, MegaError> {
@@ -146,7 +140,7 @@ impl ApiHandler for ImportApiService {
             .git_db_storage()
             .get_tree_by_hash(self.repo.repo_id, hash)
             .await?
-            .unwrap();
+            .ok_or_else(|| MegaError::NotFound(format!("import tree not found: {hash}")))?;
         Ok(Tree::from_git_model(model))
     }
 
@@ -155,7 +149,7 @@ impl ApiHandler for ImportApiService {
         let commit = storage
             .get_commit_by_hash(self.repo.repo_id, hash)
             .await?
-            .unwrap();
+            .ok_or_else(|| MegaError::NotFound(format!("import commit not found: {hash}")))?;
         Ok(Commit::from_git_model(commit))
     }
 

ceres/src/application/mod.rs

@@ -5,4 +5,5 @@ pub mod build_trigger;
 pub mod code_edit;
 pub mod member_identity;
 pub mod notification;
+pub mod snapshot;
 pub mod webhook;