feat(cache): portable mache db — push/pull/verify/inspect, all 5 phases (mache-aeb262)

.github/workflows/cache-roundtrip.yml

@@ -0,0 +1,55 @@
+# Portable-cache round-trip CI (bead mache-aeb262 Phase 5).
+#
+# Runs the cache feature's end-to-end self-test on every push + PR.
+# All inputs are commit-controlled — no untrusted PR/issue body/title
+# is interpolated into run: blocks.
+
+name: cache-roundtrip
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'cmd/cache*.go'
+      - 'cmd/cache_oci*.go'
+      - 'cmd/cache_remote*.go'
+      - 'go.mod'
+      - 'go.sum'
+      - '.github/workflows/cache-roundtrip.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'cmd/cache*.go'
+      - 'cmd/cache_oci*.go'
+      - 'cmd/cache_remote*.go'
+      - 'go.mod'
+      - 'go.sum'
+      - '.github/workflows/cache-roundtrip.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  roundtrip:
+    name: cache round-trip
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          lfs: true
+
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      # 22 cache tests: 7 local push/pull + 12 OCI client + 3 e2e remote.
+      - name: Run cache tests
+        run: go test -v -count=1 ./cmd/ -run "TestCache|TestOCI"
+
+      # The "feature still works end-to-end" smoke test.
+      - name: Round-trip self-test
+        run: go test -v -count=1 -run "TestCachePushPull_RoundTrip|TestCacheRemoteRoundTrip" ./cmd/

README.md

@@ -25,6 +25,34 @@ Seventeen MCP tools wrap the projected graph (sixteen read-surface plus `write_f
 
 For the full tool inventory and capability matrix (which tools need which tables), see [ARCHITECTURE.md § MCP Server](docs/ARCHITECTURE.md#core-abstractions) and [§ Interplay with ley-line-open](docs/ARCHITECTURE.md#interplay-with-ley-line-open).
 
+## Portable cache (mache-aeb262)
+
+`mache cache` push/pulls the projected `.db` as a content-addressed bundle so CI / new dev machines / agents don't re-parse a million lines on every cold start.
+
+```bash
+# Emit a portable bundle from a built db.
+mache cache push --db ./mache.db ./cache-out
+
+# Restore a fresh db from a bundle.
+mache cache pull --out-db ./restored.db ./cache-out
+
+# Push to a remote OCI registry (build-cache/v1 transport).
+mache cache push --db ./mache.db ./cache-out \
+    --remote https://cache.example.com --scope myrepo/abc123 --tag latest
+
+# Pull from a remote registry into a local cache dir, then restore.
+mache cache pull --out-db ./restored.db ./cache-in \
+    --remote https://cache.example.com --scope myrepo/abc123 --ref latest
+
+# CI-friendly: assert a bundle is intact + verifiable, without restoring.
+mache cache verify \
+    --remote https://cache.example.com --scope myrepo/abc123 --ref latest
+```
+
+When the source db has an `_ast` table, chunks carry the AST node rows too — pull restores both `_source` AND `_ast`, so the restored db is queryable without re-parsing. When `_ast` is absent, chunks are raw source bytes (Phase 1 fallback).
+
+See [`docs/cache/phase-4-chunk-shape.md`](docs/cache/phase-4-chunk-shape.md) for the wire format and [`cloister-spec/build-cache/v1/`](https://github.com/agentic-research/cloister/tree/main/cloister-spec/build-cache/v1) for the OCI transport spec.
+
 ## How it works
 
 ```mermaid

Taskfile.yml

@@ -342,3 +342,25 @@ tasks:
       - task: test
       - task: validate
       - task: docs:lint
+
+  # ────────────────────────────────────────────────────────────────
+  # Portable cache (bead mache-aeb262)
+  # ────────────────────────────────────────────────────────────────
+
+  cache:test:
+    desc: Run the cache push/pull/OCI test suite
+    cmds:
+      - go test -v -count=1 ./cmd/ -run "TestCache|TestOCI"
+
+  cache:roundtrip:
+    desc: End-to-end self-test — build a tiny db, push, pull, diff
+    summary: |
+      Builds a synthetic mache db, runs `mache cache push` to emit a
+      lockfile + chunks, runs `mache cache pull` to restore into a
+      fresh db, diffs the two _source tables. Exits 1 on any drift.
+
+      Usage: task cache:roundtrip
+      Used by .github/workflows/cache-roundtrip.yml as a CI smoke test
+      that the cache feature still works end-to-end.
+    cmds:
+      - go test -v -count=1 -run "TestCachePushPull_RoundTrip|TestCacheRemoteRoundTrip" ./cmd/