feat(protocol): publish Git and Xet state through capsules

.github/workflows/architecture.yml

@@ -175,6 +175,9 @@ jobs:
       CRAB_HTTP_CELL_TEST_BUCKET: crab-cell-runtime
       CRAB_HTTP_CELL_TEST_ENDPOINT: http://127.0.0.1:9000
       CRAB_HTTP_CELL_TEST_PREFIX: server-${{ github.run_id }}-${{ github.run_attempt }}
+      CRAB_CELL_TEST_BUCKET: crab-cell-runtime
+      CRAB_CELL_TEST_ENDPOINT: http://127.0.0.1:9000
+      CRAB_CELL_TEST_PREFIX: public-${{ github.run_id }}-${{ github.run_attempt }}
       RUSTFS_IMAGE: ghcr.io/rustfs/rustfs:1.0.0-glibc@sha256:bffcab0c9d647aab0055d1c69d340b202d0909966b385932d4ead1aeb7602858
 
     steps:

.github/workflows/git-protocol-v2-partial-clone.yml

@@ -27,6 +27,7 @@ on:
       - "crab/src/cmd/fsck*.rs"
       - "crab/src/cmd/history_recovery.rs"
       - "crab/src/cmd/metadb.rs"
+      - "crab/src/cmd/push.rs"
       - "crab/src/cmd/repack.rs"
       - "crab/src/cmd/gc/**"
       - "crab/src/replication/**"
@@ -80,6 +81,7 @@ on:
       - "crab/src/cmd/fsck*.rs"
       - "crab/src/cmd/history_recovery.rs"
       - "crab/src/cmd/metadb.rs"
+      - "crab/src/cmd/push.rs"
       - "crab/src/cmd/repack.rs"
       - "crab/src/cmd/gc/**"
       - "crab/src/replication/**"
@@ -185,6 +187,7 @@ jobs:
             git::push::tests::shared_xorb_non_atomic_replan \
             git::push::tests::ref_lease
           cargo test -p crab --lib git::remote_helper::tests::list_session_does_not_open_a_damaged_staging_index --locked --features gix-transport
+          cargo test -p crab --lib git::remote_helper::tests::capsule_promisor_fetch_ --locked --features gix-transport
           cargo test -p crab-metadata --lib file_index_lookup --locked --features file-index-reader
           cargo test -p crab-metadata --lib git_visibility::tests --locked --features remote-index
           cargo test -p crab-metadata --lib ref_journal::tests --locked --features remote-index

.github/workflows/large-repository-rustfs.yml

@@ -6,6 +6,9 @@ on:
       - ".github/workflows/large-repository-rustfs.yml"
       - "crab/scripts/e2e/run_large_repo_rustfs.py"
       - "crab/scripts/e2e/test_verify_large_repo_rustfs_report.py"
+      - "crab/scripts/e2e/run_capsule_k8s_rustfs.py"
+      - "crab/scripts/e2e/test_run_capsule_k8s_rustfs.py"
+      - "crab/docs/design/capsule-layered-packs.md"
       - "crab/scripts/verify-large-repo-rustfs-report.py"
       - "crab/docs/guides/large-repository-qualification.md"
       - "crates/crab-read/src/upload_pack.rs"
@@ -37,6 +40,9 @@ on:
       - ".github/workflows/large-repository-rustfs.yml"
       - "crab/scripts/e2e/run_large_repo_rustfs.py"
       - "crab/scripts/e2e/test_verify_large_repo_rustfs_report.py"
+      - "crab/scripts/e2e/run_capsule_k8s_rustfs.py"
+      - "crab/scripts/e2e/test_run_capsule_k8s_rustfs.py"
+      - "crab/docs/design/capsule-layered-packs.md"
       - "crab/scripts/verify-large-repo-rustfs-report.py"
       - "crab/docs/guides/large-repository-qualification.md"
       - "crates/crab-read/src/upload_pack.rs"
@@ -85,9 +91,11 @@ jobs:
       - name: Verify report contract tests
         run: |
           python3 -m unittest crab/scripts/e2e/test_verify_large_repo_rustfs_report.py
+          python3 -m unittest crab/scripts/e2e/test_run_capsule_k8s_rustfs.py
           python3 -m py_compile \
             crab/scripts/e2e/run_large_repo_rustfs.py \
-            crab/scripts/verify-large-repo-rustfs-report.py
+            crab/scripts/verify-large-repo-rustfs-report.py \
+            crab/scripts/e2e/run_capsule_k8s_rustfs.py
 
   kubernetes-rustfs:
     name: Kubernetes 1,000-commit RustFS qualification
@@ -104,7 +112,8 @@ jobs:
       CRAB_CACHE_PSK: cache-smoke-psk
       CARGO_TARGET_DIR: /Volumes/Workspace/crabbuild-target/crab-large-repo-qualification-${{ github.run_id }}-${{ github.run_attempt }}
       QUALIFICATION_ROOT: /Volumes/Workspace/CrabBuild/crabbuild-qualification
-      RUSTFS_IMAGE: rustfs/rustfs:1.0.0-beta.8-glibc
+      RUSTFS_IMAGE: ghcr.io/rustfs/rustfs@sha256:bffcab0c9d647aab0055d1c69d340b202d0909966b385932d4ead1aeb7602858
+      RUSTFS_CONTAINER: crab-large-repo-rustfs-${{ github.run_id }}-${{ github.run_attempt }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -135,10 +144,10 @@ jobs:
           set -euo pipefail
           data_root="${QUALIFICATION_ROOT}/rustfs-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
           mkdir -p "$data_root"
+          sudo chown 10001:10001 "$data_root"
           docker pull "$RUSTFS_IMAGE"
-          docker rm -f crab-large-repo-rustfs >/dev/null 2>&1 || true
           docker run -d \
-            --name crab-large-repo-rustfs \
+            --name "$RUSTFS_CONTAINER" \
             -p 9000:9000 \
             -e RUSTFS_ACCESS_KEY=crab \
             -e RUSTFS_SECRET_KEY=crab \
@@ -150,9 +159,16 @@ jobs:
             fi
             sleep 1
           done
-          docker logs crab-large-repo-rustfs >&2 || true
+          docker logs "$RUSTFS_CONTAINER" >&2 || true
           exit 1
 
+      - name: Verify and retain RustFS version
+        run: |
+          set -euo pipefail
+          version_file="${QUALIFICATION_ROOT}/rustfs-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-version.txt"
+          docker exec "$RUSTFS_CONTAINER" rustfs --version | tee "$version_file"
+          test "$(head -n 1 "$version_file")" = "rustfs 1.0.0"
+
       - name: Start cache service
         run: |
           set -euo pipefail
@@ -199,16 +215,17 @@ jobs:
           set -euo pipefail
           first="gha-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-a"
           second="gha-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-b"
+          version_file="${QUALIFICATION_ROOT}/rustfs-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-version.txt"
+          object_store_version="$(head -n 1 "$version_file")"
           common=(
             --crab-bin "${CARGO_TARGET_DIR}/release/crab"
             --root "$QUALIFICATION_ROOT"
             --source /Volumes/Workspace/Github/kubernetes/kubernetes
-            --object-store-version "$RUSTFS_IMAGE"
+            --object-store-version "$object_store_version"
             --require-cache-service
             --cold-clone-fanout 50
             --warm-clone-fanout 100
             --team-load
-            --cleanup-remote
           )
           python3 crab/scripts/e2e/run_large_repo_rustfs.py "${common[@]}" --run-id "$first"
           python3 crab/scripts/verify-large-repo-rustfs-report.py \
@@ -248,9 +265,9 @@ jobs:
       - name: Capture RustFS logs
         if: always()
         run: |
-          docker logs crab-large-repo-rustfs \
+          docker logs "$RUSTFS_CONTAINER" \
             > "$QUALIFICATION_ROOT/rustfs-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}.log" 2>&1 || true
-          docker rm -f crab-large-repo-rustfs >/dev/null 2>&1 || true
+          docker rm -f "$RUSTFS_CONTAINER" >/dev/null 2>&1 || true
 
       - name: Upload qualification evidence
         if: always()
@@ -263,5 +280,6 @@ jobs:
             /Volumes/Workspace/CrabBuild/crabbuild-qualification/comparison-${{ github.run_id }}-${{ github.run_attempt }}.json
             /Volumes/Workspace/CrabBuild/crabbuild-qualification/cache-service-${{ github.run_id }}-${{ github.run_attempt }}-captured.log
             /Volumes/Workspace/CrabBuild/crabbuild-qualification/rustfs-${{ github.run_id }}-${{ github.run_attempt }}.log
+            /Volumes/Workspace/CrabBuild/crabbuild-qualification/rustfs-${{ github.run_id }}-${{ github.run_attempt }}-version.txt
           if-no-files-found: warn
           retention-days: 30

.github/workflows/pb-provider-qualification.yml

@@ -49,7 +49,8 @@ concurrency:
   cancel-in-progress: false
 
 env:
-  RUSTFS_IMAGE: rustfs/rustfs:1.0.0-beta.8-glibc
+  # RustFS 1.0.0 GA; this immutable index covers Linux amd64 and arm64.
+  RUSTFS_IMAGE: ghcr.io/rustfs/rustfs@sha256:bffcab0c9d647aab0055d1c69d340b202d0909966b385932d4ead1aeb7602858
 
 jobs:
   evidence-contract:
@@ -86,7 +87,7 @@ jobs:
       CRAB_S3_FORCE_PATH_STYLE: "true"
       CRAB_PROVIDER_QUALIFICATION_PROVIDER: s3
       CRAB_PROVIDER_QUALIFICATION_BUCKET: crab-provider-qualification
-      CRAB_PROVIDER_QUALIFICATION_SERVICE: rustfs-1.0.0-beta.8-glibc
+      CRAB_PROVIDER_QUALIFICATION_SERVICE: rustfs-1.0.0-ga
       CRAB_PROVIDER_QUALIFICATION_REGION: local
       CRAB_PROVIDER_QUALIFICATION_SOURCE_SHA: ${{ github.sha }}
       CRAB_PROVIDER_QUALIFICATION_WORKFLOW_RUN_ID: ${{ github.run_id }}
@@ -123,6 +124,14 @@ jobs:
           docker logs crab-provider-rustfs >&2 || true
           exit 1
 
+      - name: Verify and retain RustFS version
+        run: |
+          set -euo pipefail
+          version_report="$(dirname "$CRAB_PROVIDER_QUALIFICATION_REPORT")/service-version.txt"
+          mkdir -p "$(dirname "$version_report")"
+          docker exec crab-provider-rustfs rustfs --version | tee "$version_report"
+          test "$(head -n 1 "$version_report")" = "rustfs 1.0.0"
+
       - name: Run provider contract
         run: |
           cargo test -p crab --test provider_qualification --locked \

.github/workflows/s3-gateway.yml

@@ -295,9 +295,11 @@ jobs:
       - name: Build minimal Crab fixture publisher
         env:
           CARGO_TARGET_DIR: ${{ runner.temp }}/crab-s3-gateway-publisher-target
-        run: >-
-          cargo build --release --locked -p crab --bin crab
-          --no-default-features --features simd-accel,gix-pathmatch
+        run: |
+          cargo build --release --locked -p crab --bin crab \
+            --no-default-features --features simd-accel,gix-pathmatch
+          cargo build --release --locked -p crab-sdk \
+            --example s3_gateway_fixture --features content,write
 
       - name: Build locked gateway image
         id: build
@@ -485,11 +487,6 @@ jobs:
               for _ in range(64):
                   stream.write(source.randbytes(1024 * 1024))
           PY
-          cp "${source_root}/qualification/xet-large.bin" \
-            "${source_root}/qualification/xet-duplicate.bin"
-          git -C "${source_root}" init -q -b main
-          git -C "${source_root}" config user.name 'S3 Xet qualification'
-          git -C "${source_root}" config user.email 'qualification@example.invalid'
           export AWS_ACCESS_KEY_ID="${RUSTFS_ACCESS_KEY}"
           export AWS_SECRET_ACCESS_KEY="${RUSTFS_SECRET_KEY}"
           export AWS_DEFAULT_REGION=us-east-1
@@ -500,55 +497,28 @@ jobs:
           export AWS_EC2_METADATA_DISABLED=true
           export AWS_VIRTUAL_HOSTED_STYLE_REQUEST=false
           export CRAB_CACHE_DIR="${xet_root}/publisher-cache"
-          crab_bin="${RUNNER_TEMP}/crab-s3-gateway-publisher-target/release/crab"
-          (
-            cd "${source_root}"
-            "${crab_bin}" init --storage-provider s3 \
-              crab://crab-s3-gateway-qualification/repositories/qualification
-            "${crab_bin}" track '*.bin'
-            "${crab_bin}" add qualification/xet-large.bin \
-              qualification/xet-duplicate.bin
-            git show :qualification/xet-large.bin > "${xet_root}/xet-pointer-staged"
-            LISTING_ROOT="${source_root}/qualification/listing" \
-            XET_POINTER="${xet_root}/xet-pointer-staged" python3 - <<'PY'
-          import os
-          from pathlib import Path
-
-          root = Path(os.environ["LISTING_ROOT"])
-          pointer = Path(os.environ["XET_POINTER"]).read_bytes()
-          root.mkdir(parents=True)
-          for index in range(10_000):
-              (root / f"flat-{index:05}.pointer").write_bytes(pointer)
-          for group in ("group-a", "group-b"):
-              directory = root / group
-              directory.mkdir()
-              for index in range(16):
-                  (directory / f"item-{index:02}.pointer").write_bytes(pointer)
-          PY
-            aws s3api create-bucket \
-              --bucket crab-s3-gateway-listing-baseline >/dev/null
-            aws s3 cp qualification/listing \
-              s3://crab-s3-gateway-listing-baseline/main/qualification/listing/ \
-              --recursive --only-show-errors --no-progress
-            git add crab.toml .gitattributes qualification/listing
-            git commit -q -m 'add Xet range qualification fixture'
-            "${crab_bin}" push --upload-concurrency 0 \
-              origin HEAD:refs/heads/main
-            git show HEAD:qualification/xet-large.bin > "${xet_root}/xet-pointer"
-            git show HEAD:qualification/xet-duplicate.bin \
-              > "${xet_root}/xet-duplicate-pointer"
-          )
+          "${RUNNER_TEMP}/crab-s3-gateway-publisher-target/release/examples/s3_gateway_fixture" \
+            crab-s3-gateway-qualification repositories/qualification \
+            "${xet_root}/publisher-cache" \
+            "${source_root}/qualification/xet-large.bin" \
+            "${xet_root}/xet-pointer" \
+            "${source_root}/qualification/listing"
+          cp "${xet_root}/xet-pointer" "${xet_root}/xet-duplicate-pointer"
+          aws s3api create-bucket \
+            --bucket crab-s3-gateway-listing-baseline >/dev/null
+          aws s3 cp "${source_root}/qualification/listing" \
+            s3://crab-s3-gateway-listing-baseline/main/qualification/listing/ \
+            --recursive --only-show-errors --no-progress
           grep -Eq '^version https://crab.build/spec/v1$' \
             "${xet_root}/xet-pointer"
           grep -Fx 'size 67108864' "${xet_root}/xet-pointer"
           test "$(sed -n 's/^file-hash //p' "${xet_root}/xet-pointer")" = \
             "$(sed -n 's/^file-hash //p' "${xet_root}/xet-duplicate-pointer")"
-          git -C "${source_root}" ls-tree -r --name-only HEAD \
-            qualification/listing | wc -l | tr -d ' ' \
+          find "${source_root}/qualification/listing" -type f | wc -l | tr -d ' ' \
             > "${xet_root}/listing-object-count"
           test "$(cat "${xet_root}/listing-object-count")" = 10032
-          git -C "${source_root}" ls-tree -r HEAD qualification/listing | \
-            awk '{print $3}' | sort -u | wc -l | tr -d ' ' \
+          find "${source_root}/qualification/listing" -type f -print0 | \
+            xargs -0 sha256sum | awk '{print $1}' | sort -u | wc -l | tr -d ' ' \
             > "${xet_root}/listing-blob-count"
           test "$(cat "${xet_root}/listing-blob-count")" = 1
           aws --endpoint-url http://127.0.0.1:19000 s3api list-objects-v2 \

CONTEXT.md

@@ -100,3 +100,22 @@ _Avoid_: Cache-warm or sparse-active Cell
 An advisory, revision-pinned ranking or movement decision derived from signed
 fleet capacity. It never grants ownership; Cell authority remains decisive.
 _Avoid_: Ownership record or scheduler assignment
+## Capsule protocol language
+
+**Capsule**:
+A content-addressed immutable object that co-locates one ref transaction with
+its Git pack, authenticated indexes, and external Xorb/Shard dependency evidence.
+Large-file payloads remain outside the capsule.
+_Avoid_: Pack, because a capsule contains a Git pack plus non-pack evidence
+
+**Repository root**:
+The bounded mutable record for checkpoint, symbolic HEAD, GC, and maintenance
+transitions. Ordinary branch publication uses independently conditional per-ref
+heads rather than contending on this record.
+_Avoid_: Manifest, when referring to the capsule-protocol storage protocol
+
+**Checkpoint**:
+An immutable repository view binding refs, indexes, and a layered pack set.
+Stable pack bodies remain in their immutable sources; maintenance compacts a
+bounded suffix instead of rewriting the complete repository.
+_Avoid_: Snapshot, when referring to the stored capsule-protocol artifact