V1 A: CPU cache contract; hot tier does not use erasure coding

.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test-x86_64:
+    name: test (x86_64)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+      - name: Format
+        run: cargo fmt --all -- --check
+      - name: Clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+      - name: Test
+        run: cargo test --workspace --all-targets
+      - name: Reject accelerator crates in V1 A
+        run: |
+          if grep -RInE 'cuda|doca|nixl|rdma|spdk' crates/*/Cargo.toml; then
+            echo "V1 A crates must not depend on GPU or DPU stacks"
+            exit 1
+          fi
+
+  test-aarch64:
+    name: test (aarch64 runner)
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Test
+        run: cargo test --workspace --all-targets
+
+  test-aarch64-qemu:
+    name: test (aarch64 qemu-user)
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+      - name: Cross toolchain
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-aarch64-linux-gnu qemu-user-static libc6-dev-arm64-cross
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: aarch64-unknown-linux-gnu
+      - name: Test under qemu-aarch64
+        env:
+          CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: aarch64-linux-gnu-gcc
+          CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_RUNNER: qemu-aarch64-static -L /usr/aarch64-linux-gnu
+        run: cargo test --workspace --all-targets --target aarch64-unknown-linux-gnu

.gitignore

@@ -0,0 +1,7 @@
+/target
+**/*.rs.bk
+.DS_Store
+*.log
+/tmp
+.cargo/registry
+.cargo/git

AGENTS.md

@@ -0,0 +1,35 @@
+# Agent notes
+
+GPUCache is the G3.5 shared KV tier. RustFS is the colder G4 backend. Read [README.md](README.md), [docs/adr/0001-integration-route.md](docs/adr/0001-integration-route.md), and [docs/adr/0002-no-erasure-coding.md](docs/adr/0002-no-erasure-coding.md) before changing scope.
+
+## Phase
+
+The active phase is **V1 milestone A** unless a human explicitly starts a later milestone. Do not implement V1 B, V2 RDMA, or V3 DPU work in a V1 A change. Do not publish crates, cut releases, deploy, or edit a website unless asked.
+
+## Honesty rules
+
+- Do not claim DPU, DOCA, RDMA, SPDK, or CUDA acceleration. V1 is CPU only. An aarch64 build is not a BlueField test.
+- Do not invent vLLM, LMCache, or NIXL results. A real engine KV export/import needs a GPU and stays `NOT_RUN_HARDWARE` until that run exists.
+- Do not treat a KV block as model-agnostic long-term memory. A miss falls back to recompute. A wrong-tenant or wrong-layout hit is a defect.
+- Do not add erasure coding, parity, or durability replicas. A lost or failed hot block is a clean miss, then recompute and repopulate. Cold durability belongs to RustFS. An extra hot-prefix copy, if it is ever added, is a latency hint and not a durability promise.
+- Docs in this repo are English.
+
+## Crates
+
+| Crate | May depend on |
+| --- | --- |
+| `gpucache-core-types` | `sha2` only |
+| `gpucache-protocol` | `gpucache-core-types` |
+| `gpucache-storage` | the two crates above |
+
+No crate may add CUDA, DOCA, NIXL, RDMA, SPDK, erasure coding, or replica placement. `unsafe` is forbidden. Registered buffers whose completion is unknown stay quarantined until drain or a newer epoch; do not free them only because a lease timer fired.
+
+## Checks
+
+```bash
+cargo fmt --all -- --check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace --all-targets
+```
+
+`cargo test --workspace --all-targets` is the one-command CPU repro.

COMPATIBILITY.md

@@ -0,0 +1,24 @@
+# Compatibility manifest
+
+Recorded for V1 milestone A. This file is not a performance acceptance report and not a hardware inventory of a BlueField node.
+
+| Component | Value | Result |
+| --- | --- | --- |
+| OS | Ubuntu 24.04.5 LTS | Recorded on the V1 A build host |
+| Kernel | Linux 6.12.94+ | Recorded on the V1 A build host |
+| Architecture exercised locally | x86_64 native, and aarch64 via qemu-user (`qemu-aarch64-static`) | `PASS` for `cargo test --workspace --all-targets` on both. This is not a BlueField run. |
+| Rust | stable 1.99.0 (b940084d7 2026-09-28); MSRV declared as 1.85 | `PASS` |
+| Python | 3.12.3 present on the build host | Not used by V1 A |
+| CUDA | Not installed | `NOT_RUN_HARDWARE` |
+| GPU / driver | None in this environment | `NOT_RUN_HARDWARE` |
+| vLLM | Not pinned; no engine commit | `NOT_RUN_HARDWARE` |
+| LMCache | Not a dependency | `NOT_RUN_HARDWARE` (route undecided) |
+| NIXL / UCX / RDMA | Not a dependency | Not in V1 |
+| DOCA / BlueField BFB / firmware | Not present | `NOT_RUN_HARDWARE` |
+| RustFS server / client | No endpoint authorized | `NOT_RUN_HARDWARE` |
+| Direct Rust deps | `sha2` 0.10.8; dev `proptest` 1.4.0 | Apache-2.0 OR MIT; see `Cargo.lock` |
+| License of this repo | Apache-2.0 | See `LICENSE` |
+
+CI (see `.github/workflows/ci.yml`) builds and runs the same tests on x86_64 and on aarch64 (GitHub ARM runner, plus qemu-user cross execution). An aarch64 result is a CPU result. It does not certify BlueField-3, DOCA, or NVMe-on-DPU.
+
+The integration decision between a native vLLM KV connector and LMCache is pending. No engine commit is pinned because the spike did not run.