@@ -241,14 +241,86 @@ jobs:
         working-directory: gui/app
         run: npm run build:web   # presync check + prebuild sync-wasm (js/wasm → public/wasm), then next build → out/ (basePath /app)
 
+      # ---- Build the mdBook guide for the /guide/ mount ----
+      # [OPUS-5] issue #5022 — the guide's publish half. docs.yml validates the same guide on
+      # PRs but deliberately ships no deploy job (one Pages slot, owned here); this is where it
+      # actually reaches the web. The mdbook version below MUST equal docs.yml's pin — the two
+      # lanes are only equivalent if they build with the same renderer, and
+      # scripts/check-guide-publish-wiring.py fails the build if they diverge.
+      - name: Install mdbook (pinned)
+        uses: taiki-e/install-action@18b1216eba7f8039b0f8d131d5473787f0edce68 # v2.85.3
+        with:
+          tool: mdbook@0.4.40
+      # Shared with docs.yml so the validate lane and the publish lane cannot drift. The script
+      # carries the load-bearing detail: mdBook exits 0 on a broken {{#include}}/anchor
+      # (rust-lang/mdBook#1094), so it greps the build log for [ERROR] — without that, an anchor
+      # rename in README.md/SKILL.md would PUBLISH a guide full of raw include directives, green.
+      - name: Build the mdBook guide
+        run: bash scripts/build-guide.sh book
+
+      # ---- Overlay the mdBook guide at /guide/ ----
+      # [OPUS-5] issue #5022 — place the rendered guide (book/book) into out/guide/, mirroring
+      # the dev/bench* and /app overlays: another sub-tree of the SAME single Pages artifact, so
+      # there is still exactly ONE producer for the one Pages deploy slot.
+      #
+      # Runs BEFORE the lychee link-check so the site's own links INTO /guide/ (the app-shell
+      # Docs link) resolve against the real render; check-site-links.sh excludes guide/ as an
+      # INPUT, so the guide's own HTML is not scanned. The guide is a separate first-party render with its own link shape (mdBook resolves chapter links
+      # relatively, and the `link-fixup` preprocessor rewrites the {{#include}}d repo-relative
+      # links to absolute github.com URLs, which lychee --offline cannot resolve anyway); its
+      # broken-include gate is the [ERROR] grep in scripts/build-guide.sh, not lychee.
+      #
+      # UNLIKE the /app overlay there is NO placeholder route to replace here — the site export
+      # has no /guide route — so an out/guide that ALREADY exists means the site grew one and
+      # this step would silently clobber it. That is a hard failure, not a merge.
+      - name: Overlay mdBook guide (out/guide/)
+        working-directory: site
+        run: |
+          set -euo pipefail
+          guide_out="$GITHUB_WORKSPACE/book/book"
+          if [ ! -f "$guide_out/index.html" ]; then
+            echo "::error::mdBook render missing ($guide_out/index.html) — the guide build step did not produce book/book/"
+            exit 1
+          fi
+          if [ -e out/guide ]; then
+            echo "::error::out/guide already exists BEFORE the guide overlay — the site export now has its own /guide route, which this overlay would silently clobber. Pick a different mount or drop the site route (issue #5022)."
+            exit 1
+          fi
+          echo "Overlaying mdBook render -> out/guide/"
+          mkdir -p out/guide
+          # Plain `cp -a` (not the /app overlay's `rsync -a --delete`): that overlay mirrors
+          # ONTO a pre-existing placeholder tree and needs --delete to clear its orphans. Here
+          # the guard above has already proven out/guide did not exist, so there is nothing to
+          # delete and a copy is the whole operation.
+          cp -a "$guide_out/." out/guide/
+          # MOUNT ASSERTION: mdBook stamps book.toml's `site-url` into the guide's OWN 404.html
+          # as <base href="...">. GitHub Pages serves that directory-level 404 for /guide/<typo>,
+          # so if the baked base href ever stops matching the sub-path we overlay to, every asset
+          # on that page resolves against the wrong root. Assert the two agree here, at the point
+          # where the mount is actually chosen.
+          if grep -q '<base href="/guide/">' out/guide/404.html; then
+            echo "OK: guide 404.html carries <base href=\"/guide/\"> matching the overlay mount"
+          else
+            echo "::error::out/guide/404.html does not carry <base href=\"/guide/\"> — book.toml's [output.html] site-url has drifted from the /guide/ mount, so the guide's 404 page would 404 its own assets"
+            exit 1
+          fi
+          # NOTE (measured): a second "no raw {{#include}} survived into the HTML" scan was tried
+          # here and REMOVED — it false-positives on the guide's own legitimate prose, which
+          # discusses the single-sourcing mechanism by name (book/src comments and the README
+          # `features-core` anchor both write `{{#include}}` in running text). The broken-include
+          # guard is the `[ERROR]` log grep in scripts/build-guide.sh, which runs before this step
+          # and whose teeth are pinned in scripts/tests/test_build_guide.sh.
+          echo "OK: mdBook guide overlaid at out/guide/" >> "$GITHUB_STEP_SUMMARY"
+
       # [OPUS-4.8] sq-d8or — anti-drift: link-check the BUILT site HTML before publish.
       # The docs-quality `internal-links` job (sq-5fd1) lychee-checks the repo MARKDOWN;
       # this extends that scope to the static-export HTML the Pages site actually serves —
       # catching renamed routes / stale cross-links / dangling #anchors that markdown linting
       # cannot see. lychee runs --offline (deterministic, no network) over site/out, remapping
       # the /sparq GitHub-Pages base path to the export root. Runs BEFORE the dev/ overlay so
       # it checks only THIS site's source (the overlaid benchmark dashboard is excluded by the
-      # script anyway). The remap + teeth live in a shared, self-tested script
+      # script anyway). It runs AFTER the guide overlay so links into /guide/ resolve; the
+      # script skips guide/ as an input. The remap + teeth live in a shared, self-tested script
       # (scripts/check-site-links.sh + scripts/tests/test_check_site_links.sh, run in
       # docs-quality's ci-scripts job) so the logic is pinned and reusable locally. A broken
       # internal link FAILS the build → no broken deploy. lychee is installed via the same
@@ -262,23 +334,6 @@ jobs:
       - name: Link-check the static-export HTML (lychee --offline)
         run: bash scripts/check-site-links.sh site/out
 
-      # ---- Build the mdBook guide for the /guide/ mount ----
-      # [OPUS-5] issue #5022 — the guide's publish half. docs.yml validates the same guide on
-      # PRs but deliberately ships no deploy job (one Pages slot, owned here); this is where it
-      # actually reaches the web. The mdbook version below MUST equal docs.yml's pin — the two
-      # lanes are only equivalent if they build with the same renderer, and
-      # scripts/check-guide-publish-wiring.py fails the build if they diverge.
-      - name: Install mdbook (pinned)
-        uses: taiki-e/install-action@18b1216eba7f8039b0f8d131d5473787f0edce68 # v2.85.3
-        with:
-          tool: mdbook@0.4.40
-      # Shared with docs.yml so the validate lane and the publish lane cannot drift. The script
-      # carries the load-bearing detail: mdBook exits 0 on a broken {{#include}}/anchor
-      # (rust-lang/mdBook#1094), so it greps the build log for [ERROR] — without that, an anchor
-      # rename in README.md/SKILL.md would PUBLISH a guide full of raw include directives, green.
-      - name: Build the mdBook guide
-        run: bash scripts/build-guide.sh book
-
       # ---- Preserve the existing benchmark dashboard(s) at /dev/ ----
       # [OPUS-4.8] sq-zngy — fold ALL `dev/bench*` subtrees (not just dev/bench).
       # bench.yml writes benchmark-data:dev/bench (benchmark-data-dir-path: dev/bench);
@@ -366,59 +421,6 @@ jobs:
           fi
           echo "OK: operational GUI overlaid at out/app/" >> "$GITHUB_STEP_SUMMARY"
 
-      # ---- Overlay the mdBook guide at /guide/ ----
-      # [OPUS-5] issue #5022 — place the rendered guide (book/book) into out/guide/, mirroring
-      # the dev/bench* and /app overlays: another sub-tree of the SAME single Pages artifact, so
-      # there is still exactly ONE producer for the one Pages deploy slot.
-      #
-      # Runs AFTER the lychee link-check, which checks only the SITE's own export. The guide is a
-      # separate first-party render with its own link shape (mdBook resolves chapter links
-      # relatively, and the `link-fixup` preprocessor rewrites the {{#include}}d repo-relative
-      # links to absolute github.com URLs, which lychee --offline cannot resolve anyway); its
-      # broken-include gate is the [ERROR] grep in scripts/build-guide.sh, not lychee.
-      #
-      # UNLIKE the /app overlay there is NO placeholder route to replace here — the site export
-      # has no /guide route — so an out/guide that ALREADY exists means the site grew one and
-      # this step would silently clobber it. That is a hard failure, not a merge.
-      - name: Overlay mdBook guide (out/guide/)
-        working-directory: site
-        run: |
-          set -euo pipefail
-          guide_out="$GITHUB_WORKSPACE/book/book"
-          if [ ! -f "$guide_out/index.html" ]; then
-            echo "::error::mdBook render missing ($guide_out/index.html) — the guide build step did not produce book/book/"
-            exit 1
-          fi
-          if [ -e out/guide ]; then
-            echo "::error::out/guide already exists BEFORE the guide overlay — the site export now has its own /guide route, which this overlay would silently clobber. Pick a different mount or drop the site route (issue #5022)."
-            exit 1
-          fi
-          echo "Overlaying mdBook render -> out/guide/"
-          mkdir -p out/guide
-          # Plain `cp -a` (not the /app overlay's `rsync -a --delete`): that overlay mirrors
-          # ONTO a pre-existing placeholder tree and needs --delete to clear its orphans. Here
-          # the guard above has already proven out/guide did not exist, so there is nothing to
-          # delete and a copy is the whole operation.
-          cp -a "$guide_out/." out/guide/
-          # MOUNT ASSERTION: mdBook stamps book.toml's `site-url` into the guide's OWN 404.html
-          # as <base href="...">. GitHub Pages serves that directory-level 404 for /guide/<typo>,
-          # so if the baked base href ever stops matching the sub-path we overlay to, every asset
-          # on that page resolves against the wrong root. Assert the two agree here, at the point
-          # where the mount is actually chosen.
-          if grep -q '<base href="/guide/">' out/guide/404.html; then
-            echo "OK: guide 404.html carries <base href=\"/guide/\"> matching the overlay mount"
-          else
-            echo "::error::out/guide/404.html does not carry <base href=\"/guide/\"> — book.toml's [output.html] site-url has drifted from the /guide/ mount, so the guide's 404 page would 404 its own assets"
-            exit 1
-          fi
-          # NOTE (measured): a second "no raw {{#include}} survived into the HTML" scan was tried
-          # here and REMOVED — it false-positives on the guide's own legitimate prose, which
-          # discusses the single-sourcing mechanism by name (book/src comments and the README
-          # `features-core` anchor both write `{{#include}}` in running text). The broken-include
-          # guard is the `[ERROR]` log grep in scripts/build-guide.sh, which runs before this step
-          # and whose teeth are pinned in scripts/tests/test_build_guide.sh.
-          echo "OK: mdBook guide overlaid at out/guide/" >> "$GITHUB_STEP_SUMMARY"
-
       # [OPUS-4.8] sq-zngy — ARTIFACT-LEVEL smoke check (NOT a live-URL check).
       # This step asserts the ASSEMBLED Pages output dir (site/out, the exact tree handed to
       # upload-pages-artifact below) rather than probing the live https://sparq.jeswr.org/dev/...
 
@@ -0,0 +1,5 @@
+{
+  "pr": 6664,
+  "date": "2026-10-05",
+  "reason": "TripleStore::heap_bytes (always-compiled sparq-core) now also counts the pred_stats map (#3115)"
+}
@@ -1027,11 +1027,14 @@ impl TripleStore {
         self.overlay.as_ref().map_or(0, |ov| ov.added.len() + ov.deleted.len())
     }
 
-    /// Heap footprint of the permutation indexes in bytes (for benchmarking). Memory-
-    /// mapped permutations contribute 0 — their resident pages are OS page cache.
+    /// Heap footprint of the permutation indexes, the overlay and the planner's
+    /// per-predicate statistics map in bytes (for benchmarking). Memory-mapped
+    /// permutations contribute 0 — their resident pages are OS page cache. The stats map
+    /// is counted as capacity × (entry + 1 control byte), like `Dict`'s tables (#3115).
     pub fn heap_bytes(&self) -> usize {
         self.perms.iter().map(PermData::heap_bytes).sum::<usize>()
             + self.overlay.as_ref().map_or(0, |ov| ov.heap_bytes())
+            + self.pred_stats.capacity() * (std::mem::size_of::<(Id, PredStat)>() + 1)
     }
 
     /// Chooses the permutation whose sort order places all bound pattern
@@ -2138,6 +2141,25 @@ mod tests {
         }
     }
 
+    /// `heap_bytes` must count the planner's per-predicate statistics map (`pred_stats`),
+    /// not only the permutations + overlay (#3115). Wide-predicate corpora (Wikidata has
+    /// ~100k properties) carry MBs here; it was silently uncounted.
+    #[test]
+    fn heap_bytes_counts_pred_stats() {
+        // 1_000 distinct predicates so the stats map is non-trivially sized.
+        let triples: Vec<[Id; 3]> = (0..1_000u64).map(|p| [1, p as Id, 2]).collect();
+        let store = TripleStore::from_triples(triples);
+        assert_eq!(store.pred_stats.len(), 1_000);
+        let perms: usize = store.perms.iter().map(PermData::heap_bytes).sum();
+        let stats = store.pred_stats.capacity() * (std::mem::size_of::<(Id, PredStat)>() + 1);
+        assert!(stats > 0);
+        assert_eq!(
+            store.heap_bytes(),
+            perms + stats,
+            "heap_bytes must include pred_stats"
+        );
+    }
+
     /// [SONNET-4.6 sq-7d3dj.32.1] Each built raw-mode permutation Vec must carry zero
     /// capacity slack after construction.  heap_bytes() uses capacity(), so any excess
     /// inflates the reported B/triple; shrink_to_fit() (called in both build_raw_perms
 
@@ -24,12 +24,13 @@ all-features = true
 # unblocks the substrate move-chain (research/shared-eval-substrate.md, Option C). It
 # depends ONLY on sparq-core (NOT sparq-engine) so BOTH the engine AND the reasoners
 # (sparq-reason / sparq-reason-el, which depend only on sparq-core) can later consume it
-# with NO dependency cycle. This crate is a SCAFFOLD: it defines / re-exports the shared
-# id-tuple vocabulary and the numeric value tower, behind DEFAULT-OFF features, with NO
-# evaluation logic moved yet (the join kernels + the engine `compare_values`/`Num`
-# arithmetic land in later beads of the epic). Nothing in the workspace depends on it, so
-# the lean default / wasm build does not compile any of it and the wasm_bundle_bytes floor
-# stays byte-identical (Phase-1 acceptance, research record §7.1).
+# with NO dependency cycle. It holds the shared id-tuple vocabulary, the numeric value
+# tower, the comparison helpers and the hash-join kernels, each behind a DEFAULT-OFF
+# feature. It is NO LONGER unconsumed: `sparq-engine` depends on it unconditionally
+# (features numeric + join + compare) and `sparq-reason` depends on it (numeric, plus
+# rows/join behind its own features), so it IS compiled into the lean default / feature-OFF
+# wasm bundle. A change to code behind those features moves `wasm_bundle_bytes` and may need
+# a feature-off declaration (bench/feature-off-declarations/) like any engine change (#3806).
 
 [features]
 # DEFAULT-OFF by construction: the lean core/engine/wasm build must compile NONE of this
 
@@ -70,6 +70,10 @@ echo "check-site-links: lychee --offline over ${OUT_ABS}/**/*.html (root-relativ
 #      fragment. `/?` makes it match both `/#frag` and the slashless `#frag` normalisation.
 # `dev/` (the overlaid benchmark dashboard, a separate first-party artifact written by bench.yml
 # onto benchmark-data) is excluded: it is not part of THIS site's source and carries its own links.
+# `guide/` (the overlaid mdBook guide, issue #5022) is excluded as an INPUT for the same reason: its
+# broken-include gate is scripts/build-guide.sh, and its link-fixup output is not lychee-offline
+# shaped. It must still EXIST under the export when this runs (pages.yml overlays it first), so the
+# site's own links INTO /guide/ (the app-shell Docs link) are resolved and checked against it.
 lychee \
   --offline \
   --include-fragments \
@@ -78,4 +82,5 @@ lychee \
   --remap "file://${OUT_ABS}/((?:[^#]*/)?[^#/.]+)/?#(.+) file://${OUT_ABS}/\$1/index.html#\$2" \
   --remap "file://${OUT_ABS}/?#(.+) file://${OUT_ABS}/index.html#\$1" \
   --exclude-path "${OUT_ABS}/dev" \
+  --exclude-path "${OUT_ABS}/guide" \
   "${OUT_ABS}/**/*.html"
@@ -33,7 +33,7 @@
 # TUNABLES (env; all have safe defaults):
 #   VIRTUOSO_IMAGE        Docker image                 (default docker.io/openlink/virtuoso-opensource-7:latest)
 #   VIRTUOSO_HTTP_PORT    SPARQL HTTP port             (default 8890)
-#   VIRTUOSO_ISQL_PORT    isql port                    (default 1111)
+#   VIRTUOSO_ISQL_PORT    host isql port               (default 1111)
 #   VIRTUOSO_PASSWORD     dba password                 (default dba)
 #   VIRTUOSO_GRAPH        target named graph IRI       (default http://sparq.bench/graph)
 #   VIRTUOSO_PULL_TIMEOUT image-pull hard cap, s       (default 600)
@@ -128,7 +128,8 @@ docker run -d --name "$VIRTUOSO_NAME" \
   || die "failed to start Virtuoso container"
 
 # ---- 2. bounded readiness poll (isql answers once the server is up) --------------------
-isql() { docker exec "$VIRTUOSO_NAME" isql "$VIRTUOSO_ISQL_PORT" dba "$VIRTUOSO_PASSWORD" "$@"; }
+# Inside the container isql always listens on 1111; VIRTUOSO_ISQL_PORT is only the host-side mapping (#3361).
+isql() { docker exec "$VIRTUOSO_NAME" isql 1111 dba "$VIRTUOSO_PASSWORD" "$@"; }
 ready=0
 poll_n=$(( VIRTUOSO_READY_TIMEOUT / 3 )); [ "$poll_n" -ge 1 ] || poll_n=1
 for _ in $(seq 1 "$poll_n"); do
@@ -147,7 +148,7 @@ log "server ready"
 # checkpoint persists. Then verify the graph is non-empty before trusting any query.
 log "bulk-load (<= ${VIRTUOSO_LOAD_TIMEOUT}s) $CORPUS_FILE into <$VIRTUOSO_GRAPH>"
 LOAD_SQL="ld_dir('/data', '${CORPUS_FILE}', '${VIRTUOSO_GRAPH}'); rdf_loader_run(); checkpoint;"
-if ! timeout "$VIRTUOSO_LOAD_TIMEOUT" bash -c "docker exec '$VIRTUOSO_NAME' isql '$VIRTUOSO_ISQL_PORT' dba '$VIRTUOSO_PASSWORD' exec=\"$LOAD_SQL\"" >&2; then
+if ! timeout "$VIRTUOSO_LOAD_TIMEOUT" bash -c "docker exec '$VIRTUOSO_NAME' isql 1111 dba '$VIRTUOSO_PASSWORD' exec=\"$LOAD_SQL\"" >&2; then
   rc=$?
   [ "$rc" = 124 ] && die "bulk load hit the ${VIRTUOSO_LOAD_TIMEOUT}s timeout"
   die "bulk load failed (rc=$rc)"
 
@@ -46,11 +46,11 @@ test("the slim top bar shows the destinations (no Try item) and no full sidebar
   ]) {
     await expect(primary.getByRole("link", { name: label, exact: true })).toBeVisible();
   }
-  // [GPT-5.6] sq-f8ufg — mutation witness: removing Docs or pointing it at the nonexistent
-  // /docs route makes this assertion fail. The Skills router is the canonical live docs index.
+  // #2549 — mutation witness: Docs must point at the mdBook guide overlaid at /guide/ by
+  // pages.yml (basePath-prefixed, trailing slash), not at the agent-skills router.
   await expect(primary.getByRole("link", { name: "Docs", exact: true })).toHaveAttribute(
     "href",
-    "https://github.com/sparq-org/sparq/blob/main/skills/SKILL.md",
+    /\/guide\/$/,
   );
   // [OPUS-4.8] sq-4hiqe — the "Try" nav item is REMOVED (the /try playground is gone). The bar
   // must expose NO "Try" destination now.