JustVugg · BColsey · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
@@ -1,6 +1,7 @@
 # CI: run the repo's own dependency-free gate (`make check` = clean + portable
 # CPU build + C unit suites + Python stdlib tests) on the three claimed
-# platforms. No model downloads, no CUDA, no external deps — by design (#140).
+# platforms, then validate the locked Nix package on Linux and macOS. No model
+# downloads or full-model inference — by design (#140).
 name: check
 
 on:
@@ -20,6 +21,37 @@ env:
   PYTHONUTF8: '1'
 
 jobs:
+  committed-range:
+    name: Committed range whitespace
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Reject whitespace errors in the exact committed range
+        shell: bash
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PUSH_BEFORE_SHA: ${{ github.event.before }}
+          PUSH_HEAD_SHA: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+          if [[ "$EVENT_NAME" == "pull_request" ]]; then
+            range="${PR_BASE_SHA}...${PR_HEAD_SHA}"
+            echo "checking pull-request range ${range}"
+            git diff --check "$range"
+          elif [[ "$PUSH_BEFORE_SHA" =~ ^0+$ ]]; then
+            empty_tree="$(git hash-object -t tree /dev/null)"
+            echo "checking new-history range ${empty_tree}..${PUSH_HEAD_SHA}"
+            git diff --check "$empty_tree" "$PUSH_HEAD_SHA"
+          else
+            range="${PUSH_BEFORE_SHA}..${PUSH_HEAD_SHA}"
+            echo "checking push range ${range}"
+            git diff --check "$range"
+          fi
+
   linux:
     name: Linux
     runs-on: ubuntu-latest
@@ -29,6 +61,67 @@ jobs:
       - name: make check
         run: make -C c check
 
+  wheel-backend:
+    name: Wheel backend (Linux, ${{ matrix.label }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - label: setuptools 77.0.1 minimum
+            requirement: setuptools==77.0.1
+            expected: 77.0.1
+          - label: current setuptools
+            requirement: setuptools
+            expected: current
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      # This is the lane's only dependency resolution step. The packaging test
+      # itself builds and installs without package-index access, using
+      # --no-index and --no-build-isolation.
+      - name: Install selected wheel backend
+        run: python -m pip install --upgrade "${{ matrix.requirement }}"
+      - name: Verify selected backend
+        env:
+          EXPECTED_SETUPTOOLS: ${{ matrix.expected }}
+        run: |
+          python - <<'PY'
+          import os
+          import setuptools
+
+          actual = setuptools.__version__
+          expected = os.environ["EXPECTED_SETUPTOOLS"]
+          print("setuptools", actual)
+          if expected != "current" and actual != expected:
+              raise SystemExit(
+                  "expected setuptools %s, got %s" % (expected, actual)
+              )
+          PY
+      - name: Build and smoke-test wheel without index access
+        run: >-
+          python -m unittest -v
+          c.tests.test_ramdisk_packaging.RamdiskPackagingTest.test_wheel_contains_runnable_ramdisk_control_plane
+
+  wheel-isolated:
+    name: Wheel backend (Linux, default isolated PEP 517)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Report packaging frontend
+        run: python -m pip --version
+      - name: Build, install, and smoke-test with default PEP 517 isolation
+        env:
+          COLIBRI_TEST_ISOLATED_PEP517: '1'
+        run: >-
+          python -m unittest -v
+          c.tests.test_ramdisk_packaging.RamdiskPackagingTest.test_default_isolated_pep517_wheel_installs_and_runs
+
   windows:
     # The job that would have caught #68/#137 pre-merge: native MinGW-w64
     # (MSYS2/UCRT64), the exact toolchain the README's Windows port targets.
@@ -87,3 +180,26 @@ jobs:
         run: brew install libomp
       - name: make check (V4 execution gated off)
         run: make -C c check
+
+  nix:
+    name: Nix flake (${{ matrix.name }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: Linux
+            os: ubuntu-latest
+          - name: macOS
+            os: macos-latest
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Nix
+        # cachix/install-nix-action v31.10.7, pinned to its verified release commit.
+        uses: cachix/install-nix-action@a49548c11d9846ad46ecc0115273879b045f001c
+        with:
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Validate locked, model-free flake
+        run: |
+          nix flake check --no-update-lock-file --print-build-logs
+          nix build --no-link --print-build-logs .#colibri
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -537,3 +537,64 @@ jobs:
             'tests.test_convert_positioned_write'
           )
           python -m unittest -v @suites
+
+  ramdisk-integration:
+    # P0.1: the only Python test that mounts a REAL tmpfs (prepare/status/destroy,
+    # swap-before/after, durable-state survival) is gated on COLI_RAMDISK_INTEGRATION=1
+    # and otherwise never runs -- so those documented invariants were unverified in CI.
+    # Run the whole test as root in a private mount namespace. --kill-child and
+    # namespace teardown contain mounts even if the test or workflow is interrupted.
+    name: RAM-disk integration (real tmpfs lifecycle)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Real-tmpfs prepare/status/destroy
+        run: |
+          cd c
+          sudo unshare --mount --fork --kill-child --propagation private \
+            env COLI_RAMDISK_INTEGRATION=1 \
+            /usr/bin/python3 -m unittest discover \
+            -s tests -p 'test_ramdisk_integration.py' -v
+
+  ramdisk-e2e:
+    # P0.2: launch the REAL engine on a tmpfs int4 model and assert the live PROF
+    # output reports ~0 physical SSD reads (the zero-SSD-read contract the unit
+    # suite fakes via FakeEngine). This is the first CI job to generate and run a
+    # model, so it leans on the HF GLM modeling code in tools/make_glm_bench_model
+    # staying importable. This is a blocking contract: a physical-read regression
+    # must fail the pull request.
+    name: RAM-disk e2e (real engine, zero-SSD-read)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install fixture deps
+        run: |
+          pip install --no-input torch --index-url https://download.pytorch.org/whl/cpu
+          pip install --no-input transformers safetensors
+      - name: Build colibri
+        run: cd c && make colibri
+      - name: Generate canonical int4 fixture and stage it onto tmpfs
+        run: |
+          cd c
+          canonical="${RUNNER_TEMP}/glm_i4"
+          staged="/dev/shm/glm_i4"
+          python3 tools/make_glm_bench_model.py --fp8 \
+            --output "${RUNNER_TEMP}/glm_fp8" --device cpu
+          python3 tools/convert_fp8_to_int4.py \
+            --indir "${RUNNER_TEMP}/glm_fp8" --outdir "${canonical}" \
+            --ebits 4 --group-size 128 --min-free-gb 1
+          mkdir -p "${staged}"
+          cp -a --reflink=never "${canonical}/." "${staged}/"
+          findmnt -T "${canonical}" -n -o FSTYPE | grep -Ex 'ext4|xfs'
+          findmnt -T "${staged}" -n -o FSTYPE | grep -Fx 'tmpfs'
+          test "$(stat -c %d "${canonical}")" != "$(stat -c %d "${staged}")"
+          find "${canonical}" -maxdepth 1 -type f -name '*.safetensors' \
+            -exec mv -- '{}' '{}.canonical-only' \;
+      - name: Zero-SSD-read end-to-end assertion
+        env:
+          COLI_RAMMAP_E2E_CANONICAL: ${{ runner.temp }}/glm_i4
+          COLI_RAMMAP_E2E_STAGED: /dev/shm/glm_i4
+        run: cd c && python3 -m unittest discover -s tests -p 'test_rammap_e2e.py' -v
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -137,6 +137,26 @@ jobs:
           cp c/resource_plan.py dist/
           cp c/doctor.py dist/
           cp c/autotune.py dist/
+          cp c/ramdisk.py dist/
+          mkdir -p dist/ramdisk_support
+          cp c/ramdisk_support/__init__.py \
+             c/ramdisk_support/accelerator.py \
+             c/ramdisk_support/cli.py \
+             c/ramdisk_support/common.py \
+             c/ramdisk_support/contracts.py \
+             c/ramdisk_support/discovery.py \
+             c/ramdisk_support/lifecycle.py \
+             c/ramdisk_support/linux_ops.py \
+             c/ramdisk_support/model.py \
+             c/ramdisk_support/mounts.py \
+             c/ramdisk_support/planning.py \
+             c/ramdisk_support/platform_ops.py \
+             c/ramdisk_support/presentation.py \
+             c/ramdisk_support/presets.py \
+             c/ramdisk_support/processes.py \
+             c/ramdisk_support/state.py \
+             c/ramdisk_support/tokens.py \
+             dist/ramdisk_support/
           cp LICENSE dist/
           # web/dist sits NEXT TO coli in the archive; both coli and openai_server.py
           # probe that layout as well as the source checkout's one-level-up form.
@@ -226,7 +246,7 @@ jobs:
               sys.exit("FAIL: packaged launcher misroutes:\n  " + "\n  ".join(bad))
           print("OK: every engine is packaged AND coli dispatches to it:", " ".join(expect))
           PYCHK
-          out=$(python3 coli info 2>&1 || true)
+          out=$(python3 coli info --model . 2>&1)
           echo "$out"
           case "$out" in
             *"engine is not built"*) echo "FAIL: coli cannot find the packaged engine"; exit 1 ;;
@@ -241,6 +261,17 @@ jobs:
           test -f web/dist/index.html   || { echo "FAIL: dashboard missing from archive"; exit 1; }
           test -f web/dist/experts.json || { echo "FAIL: expert atlas missing from archive"; exit 1; }
           python3 -c "import sys; sys.path.insert(0, '.'); from openai_server import APIHandler as A; d = A.WEB_DIST; assert (d / 'index.html').is_file(), 'server resolved WEB_DIST to %s, which has no index.html' % d; assert (d / 'experts.json').is_file(), 'no expert atlas under %s' % d; print('OK: the packaged server resolves the dashboard at', d)"
+          echo "$out" | grep -Fq "ready ✓" || { echo "FAIL: coli cannot find the packaged engine"; exit 1; }
+          python3 coli ramdisk --help > ramdisk-help.txt
+          grep -Fq "interleaved = one shared model copy" ramdisk-help.txt || {
+            echo "FAIL: packaged headless RAM-disk control plane did not load"; exit 1;
+          }
+          test -z "$(find ramdisk_support -type f ! -name '*.py' -print -quit)" || {
+            echo "FAIL: packaged RAM-disk support contains generated artifacts"; exit 1;
+          }
+          python3 -m compileall -q ramdisk.py ramdisk_support
+          PYTHONPATH=. python3 -c "import pkgutil, ramdisk_support; [__import__(item.name) for item in pkgutil.walk_packages(ramdisk_support.__path__, ramdisk_support.__name__ + '.')]"
+          echo "OK: packaged engine and headless RAM-disk control plane load from one archive"
 
       # Only the archives -- never the loose files. `dist/colibri-*.*` used to work by accident
       # (the engine was versioned, so it did not match); now that the engine is plainly named,

diff --git a/README.md b/README.md
@@ -405,12 +405,37 @@ COLI_MODEL=/nvme/glm52_i4 ./coli doctor --deep  # strict tensors/shards/index/mi
 COLI_MODEL=/nvme/glm52_i4 ./coli tune     # measure and save this machine's fastest safe execution profile
 ./coli web  --model /nvme/glm52_i4        # API + dashboard, and opens a browser
 ./coli serve --model /nvme/glm52_i4       # API + dashboard, no browser (headless)
+./coli ramdisk plan --model /nvme/glm52_i4 --json  # review Linux RAM staging
 ```
 
 On Windows the same commands work with `python coli chat --model D:\glm52_i4`.
 The engine at runtime is pure C — python is only used by the one-time converter
 and the optional API gateway.
 
+#### Headless RAM-workspace lifecycle (Linux)
+
+`coli ramdisk` can stage a reviewed full or profile-selected model namespace
+onto NUMA-aware tmpfs without a terminal frontend. Mutations are bound to the
+exact JSON snapshot an operator reviewed:
+
+```bash
+# Save the plan_token from this response.
+./coli ramdisk plan --model /nvme/glm52_i4 --json
+
+./coli ramdisk stage --model /nvme/glm52_i4 \
+  --plan-token <64-lowercase-hex> --yes --json
+
+./coli ramdisk status --json
+./coli ramdisk verify --json
+
+# Save the deployment_token from status, then destroy that exact deployment.
+./coli ramdisk destroy --deployment-token <64-lowercase-hex> --yes --json
+```
+
+`prepare` is an exact alias of `stage`. A bare `coli ramdisk` prints the
+headless action help and exits with status 2. Managed engine `start`, `stop`,
+and benchmark actions are not part of this lifecycle layer.
+
 #### The same commands run any of the models
 
 `coli` reads the model's `config.json`, picks the matching engine binary, and
@@ -459,6 +484,7 @@ Two things that differ per model, both documented in the per-model page:
 | OpenAI-compatible API, KV slots, web dashboard | [docs/api.md](docs/api.md) |
 | Grammar-forced drafts (structured output) | [docs/grammar-draft.md](docs/grammar-draft.md) |
 | Environment variable inventory | [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md) |
+| Headless RAM-workspace CLI and tokens | [docs/SETTINGS.md#ramdisk-linux-only](docs/SETTINGS.md#ramdisk-linux-only) |
 
 ## DeepSeek V4
 

diff --git a/c/Makefile b/c/Makefile
@@ -983,6 +983,12 @@ tests/bench_mla_simd$(EXE): tests/bench_mla_simd.c colibri.c st.h uring.h json.h
 tests/test_uring$(EXE): tests/test_uring.c colibri.c st.h uring.h json.h tok.h tok_unicode.h compat.h grammar.h tier.h quant.h sample.h kv_persist.h telemetry.h route_trace.h
 	$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
 
+tests/test_rammap$(EXE): tests/test_rammap.c colibri.c st.h uring.h json.h tok.h tok_unicode.h compat.h grammar.h tier.h quant.h sample.h kv_persist.h telemetry.h route_trace.h
+	$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
+
+tests/test_resource_masks$(EXE): tests/test_resource_masks.c colibri.c st.h uring.h json.h tok.h tok_unicode.h compat.h grammar.h tier.h quant.h sample.h kv_persist.h telemetry.h route_trace.h
+	$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
+
 tests/test_pipe_block$(EXE): tests/test_pipe_block.c colibri.c st.h uring.h json.h tok.h tok_unicode.h compat.h grammar.h tier.h
 	$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
 
@@ -1083,12 +1089,17 @@ install: colibri$(EXE) olmoe$(EXE) $(if $(filter 1,$(COLI_V4_SUPPORTED)),deepsee
 	$(INSTALL) -d $(DESTDIR)$(LIBEXECDIR)
 	$(INSTALL) -d $(DESTDIR)$(LIBEXECDIR)/tools
 	$(INSTALL) -m 755 coli $(DESTDIR)$(BINDIR)/coli
+	printf '%s\n' '$(LIBEXECDIR)' > '$(DESTDIR)$(BINDIR)/coli.libexec'
+	chmod 644 '$(DESTDIR)$(BINDIR)/coli.libexec'
 	$(INSTALL) -m 755 colibri$(EXE) $(DESTDIR)$(LIBEXECDIR)/colibri$(EXE)
 	$(INSTALL) -m 755 olmoe$(EXE) $(DESTDIR)$(LIBEXECDIR)/olmoe$(EXE)
 	@if [ -f deepseek_v4$(EXE) ]; then \
 	  $(INSTALL) -m 755 deepseek_v4$(EXE) $(DESTDIR)$(LIBEXECDIR)/deepseek_v4$(EXE); \
 	fi
-	$(INSTALL) -m 644 resource_plan.py doctor.py autotune.py openai_server.py version.py $(DESTDIR)$(LIBEXECDIR)/
+	$(INSTALL) -m 644 resource_plan.py doctor.py autotune.py openai_server.py version.py ramdisk.py $(DESTDIR)$(LIBEXECDIR)/
+	rm -rf "$(DESTDIR)$(LIBEXECDIR)/ramdisk_support"
+	$(INSTALL) -d -m 755 "$(DESTDIR)$(LIBEXECDIR)/ramdisk_support"
+	$(INSTALL) -m 644 $(addprefix ramdisk_support/,$(RAMDISK_SUPPORT_MODULES)) "$(DESTDIR)$(LIBEXECDIR)/ramdisk_support/"
 	$(INSTALL) -m 644 tools/*.py $(DESTDIR)$(LIBEXECDIR)/tools/
 	@# The dashboard is an optional build artifact (cd web && npm run build), so install
 	@# it only when it exists. It goes NEXT TO openai_server.py, which probes ./web/dist.
@@ -1100,8 +1111,14 @@ install: colibri$(EXE) olmoe$(EXE) $(if $(filter 1,$(COLI_V4_SUPPORTED)),deepsee
 	  echo "web/dist absent -- skipping the dashboard (build it with: cd web && npm run build)"; \
 	fi
 
+RAMDISK_SUPPORT_MODULES = \
+	__init__.py accelerator.py cli.py common.py contracts.py discovery.py \
+	lifecycle.py linux_ops.py model.py mounts.py planning.py platform_ops.py \
+	presentation.py presets.py processes.py state.py tokens.py
+
 uninstall:
 	rm -f $(DESTDIR)$(BINDIR)/coli
+	rm -f $(DESTDIR)$(BINDIR)/coli.libexec
 	rm -rf $(DESTDIR)$(LIBEXECDIR)
 
 clean:

diff --git a/c/__init__.py b/c/__init__.py
@@ -0,0 +1,5 @@
+"""Bundled Python control-plane support for the Colibri engine.
+
+The native engine is built separately; this package keeps the ``coli`` launcher
+and its Python support modules together in source, editable, and wheel installs.
+"""
diff --git a/c/backend_cuda.cu b/c/backend_cuda.cu
@@ -2020,7 +2020,13 @@ extern "C" size_t coli_cuda_tensor_bytes(const ColiCudaTensor *tensor) {
         tensor->compressed ? tensor->archive_bytes :
 #endif
         tensor->weight_bytes;
-    return storage_bytes + (tensor->fmt ? (size_t)tensor->O * ng * sizeof(float) : 0);
+    /* Report exactly what upload charged to the device counter.  In
+     * particular, fmt=6/E8 stores scales inside each weight block and has no
+     * separate scale allocation. */
+    return storage_bytes +
+        ((tensor->fmt && tensor->fmt != 6)
+             ? (size_t)tensor->O * ng * sizeof(float)
+             : 0);
 }
 
 extern "C" int coli_cuda_tensor_device(const ColiCudaTensor *tensor) {