rete-graph 0.2.1__tar.gz → 0.2.3__tar.gz

{rete_graph-0.2.1 → rete_graph-0.2.3}/Cargo.toml

@@ -14,7 +14,7 @@ members = [
 # release gates (--locked checks, feature matrix, coverage floors) stay
 # untouched by binding-only changes. Future clients (R, Go) follow the same
 # pattern — clients/ consumes crates/, never the other way around.
-exclude = ["fuzz", "clients/python"]
+exclude = ["fuzz", "clients/python", "clients/r/src/rust"]
 
 [workspace.package]
 version = "1.0.0-rc.1"

{rete_graph-0.2.1 → rete_graph-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rete-graph
-Version: 0.2.1
+Version: 0.2.3
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research

{rete_graph-0.2.1 → rete_graph-0.2.3}/clients/python/Cargo.lock

@@ -671,7 +671,7 @@ dependencies = [
 
 [[package]]
 name = "rete-python"
-version = "0.2.1"
+version = "0.2.3"
 dependencies = [
  "pyo3",
  "rete-core",

{rete_graph-0.2.1 → rete_graph-0.2.3}/clients/python/Cargo.toml

@@ -5,7 +5,7 @@
 name = "rete-python"
 # Keep in lockstep with pyproject.toml's [project] version — __version__
 # comes from here (CARGO_PKG_VERSION), the wheel metadata from pyproject.
-version = "0.2.1"
+version = "0.2.3"
 edition = "2021"
 license = "Apache-2.0"
 repository = "https://github.com/caviri/rete"

rete_graph-0.2.3/clients/python/examples/jupyterlite-build-tutorial.ipynb

@@ -0,0 +1,315 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "intro",
+   "metadata": {},
+   "source": [
+    "# Anatomy of a `.rete` — build one from an rdflib graph\n",
+    "\n",
+    "This notebook builds a **knowledge graph with a small ontology** in\n",
+    "[rdflib](https://rdflib.readthedocs.io), turns it into a **`.rete` file**,\n",
+    "and then dissects every part of that file: the **dictionary**, the **triple\n",
+    "indexes**, the **pyramid**, the **Dataset Card**, and the **embedded example\n",
+    "queries**. Everything runs in your browser tab (Pyodide + JupyterLite — no\n",
+    "server anywhere).\n",
+    "\n",
+    "Project: <https://github.com/caviri/rete> · docs:\n",
+    "[Python API](https://caviri.github.io/rete/python.html) ·\n",
+    "[format spec](https://caviri.github.io/rete/SPEC.html)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "install",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%pip install rete-graph rdflib pandas\n",
+    "\n",
+    "import pandas as pd\n",
+    "import rdflib\n",
+    "import rete_graph as rete\n",
+    "print(f\"rete-graph {rete.__version__} · rdflib {rdflib.__version__}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "kg-md",
+   "metadata": {},
+   "source": [
+    "## 1. A small KG + ontology, in rdflib\n",
+    "\n",
+    "Eight bodies of the solar system, and — this is the part that makes the rest\n",
+    "of the notebook interesting — a tiny **ontology** on top: `Planet` and\n",
+    "`Moon` are both `rdfs:subClassOf` **`CelestialBody`**, and the `orbits`\n",
+    "property declares its domain and range. No instance is ever typed as a\n",
+    "`CelestialBody` directly; later, the reasoner will *infer* that they all are."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "kg",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from rdflib import RDF, RDFS, XSD, Literal, Namespace\n",
+    "\n",
+    "SOL = Namespace(\"https://example.org/solar/\")\n",
+    "kg = rdflib.Graph()\n",
+    "\n",
+    "# --- the ontology (TBox) ---\n",
+    "for cls in (\"CelestialBody\", \"Planet\", \"Moon\"):\n",
+    "    kg.add((SOL[cls], RDF.type, RDFS.Class))\n",
+    "kg.add((SOL.Planet, RDFS.subClassOf, SOL.CelestialBody))\n",
+    "kg.add((SOL.Moon, RDFS.subClassOf, SOL.CelestialBody))\n",
+    "kg.add((SOL.orbits, RDFS.domain, SOL.CelestialBody))\n",
+    "kg.add((SOL.orbits, RDFS.range, SOL.CelestialBody))\n",
+    "\n",
+    "# --- the data (ABox) ---\n",
+    "bodies = {\n",
+    "    \"Sun\":     (None,      None,   695_700),\n",
+    "    \"Mercury\": (\"Planet\", \"Sun\",     2_440),\n",
+    "    \"Venus\":   (\"Planet\", \"Sun\",     6_052),\n",
+    "    \"Earth\":   (\"Planet\", \"Sun\",     6_371),\n",
+    "    \"Moon\":    (\"Moon\",   \"Earth\",   1_737),\n",
+    "    \"Mars\":    (\"Planet\", \"Sun\",     3_390),\n",
+    "    \"Phobos\":  (\"Moon\",   \"Mars\",       11),\n",
+    "    \"Deimos\":  (\"Moon\",   \"Mars\",        6),\n",
+    "}\n",
+    "for name, (cls, parent, radius) in bodies.items():\n",
+    "    node = SOL[name]\n",
+    "    kg.add((node, RDFS.label, Literal(name, lang=\"en\")))\n",
+    "    kg.add((node, SOL.radius_km, Literal(radius, datatype=XSD.integer)))\n",
+    "    if cls:\n",
+    "        kg.add((node, RDF.type, SOL[cls]))\n",
+    "    if parent:\n",
+    "        kg.add((node, SOL.orbits, SOL[parent]))\n",
+    "\n",
+    "print(f\"{len(kg)} triples in the rdflib graph — a taste, as Turtle:\\n\")\n",
+    "print(\"\\n\".join(kg.serialize(format=\"turtle\").splitlines()[8:16]))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "build-md",
+   "metadata": {},
+   "source": [
+    "## 2. From rdflib to `.rete` — what the Builder assembles\n",
+    "\n",
+    "`rete.Builder()` accepts the rdflib graph directly (anything with a\n",
+    "`.serialize()` method works). Configuration is **lazy** — each call just\n",
+    "records intent — and `run()` assembles the actual file, which is built from\n",
+    "four kinds of sections:\n",
+    "\n",
+    "| Part | What it is | Why it exists |\n",
+    "|---|---|---|\n",
+    "| **Dictionary** | every distinct term (IRI, literal, bnode) stored **once**, sorted, in role-split sections | queries compare small integer ids, not strings; sorted order → prefix lookups & compression |\n",
+    "| **Triple indexes** | the id-triples in **three permutations** (SPO / POS / OSP) with zone maps | any triple pattern — `(s ? ?)`, `(? p ?)`, `(? ? o)` — becomes a *range scan*, which is also what makes lazy HTTP-range querying possible |\n",
+    "| **Pyramid** | a leveled *summary* of the graph — communities of nodes, rolled up level by level, plus the label index | \"zoom out\" views, the schema profile, and label autocomplete, all readable without touching the big indexes |\n",
+    "| **Dataset Card** | a JSON self-description in the metadata section | the file documents itself: title, license, counts, and runnable starter queries |\n",
+    "\n",
+    "For the pyramid we choose `algo=\"types\"`: **one community per `rdf:type`\n",
+    "class** — for an ontology-shaped graph like ours, the summary *is* the class\n",
+    "structure. (The default, `louvain`, clusters by connectivity instead.)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "build",
+   "metadata": {},
+   "outputs": [],
+   "source": "builder = (\n    rete.Builder()\n    .add(kg)                                  # the rdflib graph, directly\n    .card(\n        title=\"Solar system micro-KG\",\n        description=\"Eight bodies + a tiny ontology (Planet/Moon ⊑ CelestialBody), \"\n                    \"authored in rdflib inside a browser tab.\",\n        license=\"CC0-1.0\",\n        created=\"2026-07-17\",\n    )\n    .example(\n        \"SELECT ?body ?parent WHERE { ?body <https://example.org/solar/orbits> ?parent }\",\n        title=\"Who orbits whom?\",\n        question=\"Which body orbits which other body?\",\n    )\n    .example(\n        \"SELECT DISTINCT ?b WHERE { ?b a <https://example.org/solar/CelestialBody> }\",\n        title=\"All celestial bodies (needs reasoning!)\",\n        question=\"Which things are celestial bodies — including inferred ones?\",\n    )\n    .pyramid(algo=\"types\")                    # communities = classes\n    .text_index()                             # opt-in full-text index\n)\n\ndata = builder.run()\nprint(f\"{len(data):,} bytes\")\nbuilder.stats"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dict-md",
+   "metadata": {},
+   "source": [
+    "## 3. The dictionary — terms are stored once\n",
+    "\n",
+    "Look at `stats` above: the file holds more **statements** than **terms**.\n",
+    "Every IRI like `sol:Sun` appears in many triples but is written once; each\n",
+    "triple is just three small integers pointing into the dictionary. That's the\n",
+    "same trick as HDT and column stores — and because the dictionary is sorted\n",
+    "and chunked, a remote client can fetch *only the chunks a query touches* and\n",
+    "run **prefix searches** against the label index without a full scan:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dict",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "g = builder.graph()\n",
+    "print(f\"statements: {g.quads} · distinct terms: {g.terms}\")\n",
+    "g.prefix_search(\"M\")   # label index: everything labelled M… (Moon, Mars, Mercury)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "pyramid-md",
+   "metadata": {},
+   "source": [
+    "## 4. The pyramid — the graph, summarized by class\n",
+    "\n",
+    "`pyramidLevels` in the build stats came from the `types` algorithm: level 0\n",
+    "groups every node under its `rdf:type` class, and the **schema profile** is\n",
+    "exactly that quotient graph — which classes exist, and how they relate\n",
+    "through predicates. A client reads this in a couple of small range requests\n",
+    "*before* deciding what to query — it's the \"map\" you see first in the\n",
+    "[playground](https://caviri.github.io/rete/playground.html):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "pyramid",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "s = g.schema()\n",
+    "display(pd.DataFrame(s[\"classes\"], columns=[\"class\", \"instances\"]))\n",
+    "pd.DataFrame(s[\"relations\"], columns=[\"subject class\", \"predicate\", \"object class\", \"count\"])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "card-md",
+   "metadata": {},
+   "source": [
+    "## 5. The Dataset Card — the file documents itself\n",
+    "\n",
+    "The card travels **inside** the file's metadata section. We wrote the curated\n",
+    "fields (`title`, `description`, `license`, `created`); the counts and\n",
+    "`format_version` were stamped automatically at build time. Every client reads\n",
+    "the same card — this notebook, the CLI (`rete card solar.rete`), the\n",
+    "playground's catalog view:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "card",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "card = g.card()\n",
+    "{k: card[k] for k in (\"title\", \"description\", \"license\", \"created\",\n",
+    "                       \"triple_count\", \"term_count\", \"format_version\")}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "examples-md",
+   "metadata": {},
+   "source": [
+    "## 6. Embedded example queries — a dataset that ships its own questions\n",
+    "\n",
+    "The two `.example()` calls landed in the card's starter-query library. Anyone\n",
+    "who opens this file — today or in ten years, in any client — can list them\n",
+    "and run them as-is:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "examples",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "examples = g.examples()\n",
+    "display(pd.DataFrame(examples)[[\"title\", \"question\"]])\n",
+    "g.query_df(examples[0][\"sparql\"])   # \"Who orbits whom?\", straight from the file"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "reason-md",
+   "metadata": {},
+   "source": [
+    "## 7. The ontology at work — reasoning by query rewriting\n",
+    "\n",
+    "Remember: nothing is *asserted* to be a `CelestialBody`. A plain query finds\n",
+    "nothing — but with `reason=True` the engine rewrites the query through the\n",
+    "ontology (`Planet ⊑ CelestialBody`, `Moon ⊑ CelestialBody`, plus the\n",
+    "`orbits` domain/range), computing OWL 2 QL entailment **without\n",
+    "materializing a single new triple**. That's why it works over lazy remote\n",
+    "files too:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "reason",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "q = examples[1][\"sparql\"]           # \"All celestial bodies\" from the card\n",
+    "print(\"asserted only:\", len(g.query(q)), \"rows\")\n",
+    "print(\"with OWL 2 QL reasoning:\")\n",
+    "g.query_df(q, reason=True)          # planets, moons — and the Sun, via orbits' range"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "export-md",
+   "metadata": {},
+   "source": [
+    "## 8. Export — one immutable file, queryable anywhere\n",
+    "\n",
+    "`export()` writes the finished file (here into the notebook's in-browser\n",
+    "filesystem — check the file browser on the left; you can download it). Host\n",
+    "it on anything that serves HTTP `Range` and it is queryable in place from\n",
+    "Python, JavaScript, the CLI, and the playground — carrying its card, its\n",
+    "examples, and its ontology with it. For datasets beyond a few million\n",
+    "triples, graduate to the streaming\n",
+    "[`rete build` CLI](https://caviri.github.io/rete/cli.html)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "export",
+   "metadata": {},
+   "outputs": [],
+   "source": "path = builder.export(\"solar.rete\")\nreopened = rete.open(path)\nprint(path, \"·\", reopened.quads, \"triples · content hash\", reopened.content_hash())"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "outro",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "\n",
+    "**Where next:** the [guided tour notebook](rete-graph.ipynb) (remote graphs,\n",
+    "lazy range reads) · [Python build tutorial](https://caviri.github.io/rete/python-build-tutorial.html) ·\n",
+    "[Dataset Cards](https://caviri.github.io/rete/dataset-cards.html) ·\n",
+    "[semantic zoom / pyramid](https://caviri.github.io/rete/semantic-zoom.html) ·\n",
+    "[reasoning](https://caviri.github.io/rete/reasoning.html)\n",
+    "\n",
+    "Source & issues: **<https://github.com/caviri/rete>**\n",
+    "\n",
+    "© 2026 Carlos Vivar Ríos — released under the\n",
+    "[Apache License 2.0](https://github.com/caviri/rete/blob/main/LICENSE)."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python (Pyodide)",
+   "language": "python",
+   "name": "python"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

{rete_graph-0.2.1 → rete_graph-0.2.3}/clients/python/examples/jupyterlite-demo.ipynb

@@ -30,7 +30,7 @@
    "id": "install",
    "metadata": {},
    "outputs": [],
-   "source": "# Pyodide is mid-transition on binary wheel tags (PEP 783): this deployment\n# pins Pyodide 0.29, whose installer predates the new PyPI tag spelling — so\n# we install the SAME published wheel from the project's bucket. On newer\n# runtimes, a plain `%pip install rete-graph` resolves from PyPI.\n%pip install pandas\n%pip install https://data.graphplaza.com/wheels/rete_graph-0.2.0-cp39-abi3-pyodide_2025_0_wasm32.whl\n\nimport sys\nimport rete_graph as rete\nprint(f\"rete-graph {rete.__version__} running on platform: {sys.platform!r}\")"
+   "source": "%pip install rete-graph pandas\n\nimport sys\nimport rete_graph as rete\nprint(f\"rete-graph {rete.__version__} running on platform: {sys.platform!r}\")"
   },
   {
    "cell_type": "markdown",

{rete_graph-0.2.1 → rete_graph-0.2.3}/clients/python/src/lib.rs

@@ -18,7 +18,8 @@ use pyo3::prelude::*;
 use pyo3::types::PyBytes;
 use rete_core::{
     eval_query, eval_query_reasoned, results_envelope_json, schema_classes, schema_summary,
-    BlockCacheReader, CountingReader, RangeReader, Rete, DEFAULT_BLOCK,
+    validate_shacl, BlockCacheReader, CountingReader, DataGraph, RangeReader, Rete, ReteGraph,
+    ShaclShapes, DEFAULT_BLOCK,
 };
 #[cfg(not(target_os = "emscripten"))]
 use rete_core::{parse_sparql_json_results, Binding, ServiceClient};
@@ -126,16 +127,59 @@ impl Graph {
         }
         Ok(())
     }
+
+    /// The incompleteness verdict is PER CALL on this resident handle: reset
+    /// the sticky failure flags before evaluating, so one transient network
+    /// failure fails only the call it happened in — failed tiles/chunks are
+    /// never cached, so the next call simply retries them. (Same shape as the
+    /// browser engine's RemoteGraph entry points.)
+    fn fresh_verdict(&self) {
+        self.rete.reset_load_failures();
+    }
 }
 
 #[pymethods]
 impl Graph {
+    /// Validate the graph against SHACL Core shapes written in Turtle.
+    /// Lazy-aware: over the default graph only the shapes' targets are
+    /// fetched (the index is consulted in place); a named `graph` view
+    /// materializes that graph first. `format` is "json" (default) or "ttl".
+    #[pyo3(signature = (shapes_turtle, *, graph=None, format="json"))]
+    fn shacl(
+        &self,
+        py: Python<'_>,
+        shapes_turtle: &str,
+        graph: Option<&str>,
+        format: &str,
+    ) -> PyResult<String> {
+        self.fresh_verdict();
+        let out = py
+            .allow_threads(|| -> Result<String, String> {
+                let shapes =
+                    ShaclShapes::parse_turtle(shapes_turtle).map_err(|e| e.to_string())?;
+                let report = match graph {
+                    None => validate_shacl(&ReteGraph::new(&self.rete), &shapes),
+                    Some(g) => {
+                        validate_shacl(&DataGraph::from_rete(&self.rete, Some(g)), &shapes)
+                    }
+                };
+                Ok(match format {
+                    "ttl" => report.to_turtle(),
+                    _ => report.to_json(),
+                })
+            })
+            .map_err(PyRuntimeError::new_err)?;
+        self.incomplete_guard()?;
+        Ok(out)
+    }
+
     /// Run a SPARQL query (SELECT / ASK / CONSTRUCT / DESCRIBE). Returns the
     /// JSON envelope `{"kind": "select", "vars": [...], "rows": [...]}` etc.;
     /// the Python wrapper parses it into values. `reason=True` turns on OWL 2
     /// QL entailment by query rewriting.
     #[pyo3(signature = (query, *, reason=false))]
     fn query(&self, py: Python<'_>, query: &str, reason: bool) -> PyResult<String> {
+        self.fresh_verdict();
         let out = py
             .allow_threads(|| {
                 if reason {

{rete_graph-0.2.1 → rete_graph-0.2.3}/clients/python/tests/test_rete_graph.py

@@ -97,6 +97,43 @@ def test_open_custom_reader(rete_bytes):
     assert r.calls >= 1
 
 
+SHAPES_PREFIX = """\
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix ex: <http://example.org/> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+"""
+
+
+def test_shacl_validation(rete_bytes, serve_bytes):
+    g = rete.open(rete_bytes)
+
+    labeled = SHAPES_PREFIX + """
+ex:PersonShape a sh:NodeShape ;
+  sh:targetClass ex:Person ;
+  sh:property [ sh:path rdfs:label ; sh:minCount 1 ] .
+"""
+    report = g.shacl(labeled)
+    assert report["conforms"] is True
+    assert report["results"] == []
+
+    emailed = SHAPES_PREFIX + """
+ex:PersonShape a sh:NodeShape ;
+  sh:targetClass ex:Person ;
+  sh:property [ sh:path ex:email ; sh:minCount 1 ] .
+"""
+    report = g.shacl(emailed)
+    assert report["conforms"] is False
+    assert len(report["results"]) == 2  # alice and bob both lack ex:email
+
+    ttl = g.shacl(emailed, format="ttl")
+    assert "ValidationReport" in ttl
+
+    # Lazy path: same verdicts over HTTP range reads.
+    remote = rete.open(serve_bytes(rete_bytes))
+    assert remote.shacl(labeled)["conforms"] is True
+    assert remote.shacl(emailed)["conforms"] is False
+
+
 def test_schema_and_search(rete_bytes):
     g = rete.open(rete_bytes)
     classes = dict(g.schema()["classes"])

{rete_graph-0.2.1 → rete_graph-0.2.3}/crates/rete-core/src/bgp.rs

@@ -17,7 +17,7 @@
 use std::collections::{BTreeMap, HashMap};
 
 use crate::file::Rete;
-use crate::index::{GraphIndex, Pattern};
+use crate::index::{GraphIndex, Pattern, Tile};
 use crate::row::{Ctx, Row, Slots, Val};
 
 /// A term in a pattern: a named variable or a constant term token.
@@ -189,7 +189,7 @@ pub(crate) fn eval_bgp_rows(ctx: &Ctx, index: &GraphIndex, patterns: &[TriplePat
             && shares_bound
             && !rows.is_empty()
             && if index.is_remote() {
-                rows.len() <= REMOTE_PROBE_MAX
+                rows.len() <= remote_probe_max(index)
                     && (rows.len() <= REMOTE_PROBE_MIN || !pattern_is_selective(&t))
             } else {
                 rows.len() <= BGP_PROBE_THRESHOLD
@@ -275,6 +275,22 @@ fn try_merge_join(
     if ca != cb {
         return None; // cross-role: the two role id-spaces aren't co-sorted
     }
+    // A merge MATERIALIZES both sides in full (`collect` below builds a Vec per
+    // side). When one side is a pinpoint (a bound leading key routing to a few
+    // KB of tiles) and the other is fat (a broad predicate spanning megabytes),
+    // the linear merge costs building — and, on a remote index, FETCHING — the
+    // fat extent end-to-end: gigabytes over HTTP, and the 32-bit wasm OOM
+    // behind `?x wdt:P279 <C> . ?x rdfs:label ?l` on a 185M-triple remote
+    // graph. The hybrid loop handles that shape strictly better (scan the
+    // pinpoint side, probe the fat one per surviving row), so leave the merge
+    // seed to comparably-sized sides.
+    let (lo, hi) = {
+        let (a, b) = (pattern_scan_bytes(index, ta), pattern_scan_bytes(index, tb));
+        (a.min(b), a.max(b))
+    };
+    if hi >= FAT_SCAN_BYTES && hi / 4 >= lo {
+        return None;
+    }
     let lower = |t: &(SlotTerm, SlotTerm, SlotTerm)| -> Option<Pattern> {
         Some((
             const_subject(&t.0, dict)?,
@@ -366,6 +382,87 @@ const BGP_PROBE_THRESHOLD: usize = 512;
 const REMOTE_PROBE_MIN: usize = 8;
 const REMOTE_PROBE_MAX: usize = 1024;
 
+/// The remote probe budget, widened by the reader's concurrency: a serial
+/// sync-XHR reader (a phone without the COI pool) pays one full round trip per
+/// probe, so its budget stays at [`REMOTE_PROBE_MAX`]; a reader overlapping
+/// 16 range reads (the CLI's thread pool, the asyncified fetch variant, the
+/// COI fetch-worker pool) amortizes ~16 probes per round trip and gets a
+/// proportionally larger budget before the one-pass scan wins again.
+fn remote_probe_max(index: &GraphIndex) -> usize {
+    REMOTE_PROBE_MAX * index.read_concurrency().clamp(1, 16)
+}
+
+/// Batch-fault the tiles that a [`ProbePlan`]'s FIRST pattern will route to
+/// across a batch of seed rows — one coalesced read per section instead of a
+/// blocking round trip per row. Only the first pattern is prefetchable (later
+/// ones bind from earlier probe results), and only rows whose seed binds the
+/// pattern's subject or object are included: a predicate-only pattern routes
+/// to the predicate's WHOLE span, which for the fat sides this path serves
+/// would prefetch the very extent the probe strategy exists to avoid.
+pub(crate) fn prefetch_plan_probes(ctx: &Ctx, index: &GraphIndex, plan: &ProbePlan, rows: &[Row]) {
+    if !index.is_remote() {
+        return;
+    }
+    let Some(t) = plan.pats.first() else {
+        return;
+    };
+    let mut pats: Vec<Pattern> = Vec::new();
+    for base in rows {
+        if let (Some(s), Some(p), Some(o)) = (
+            probe_subject(ctx, &t.0, base),
+            probe_predicate(ctx, &t.1, base),
+            probe_object(ctx, &t.2, base),
+        ) {
+            if s.is_some() || o.is_some() {
+                pats.push((s, p, o));
+            }
+        }
+    }
+    index.prefetch_probe_tiles(&pats);
+}
+
+/// Batch-fault the tiles that probing `patterns` from `subject_ids` (each
+/// bound onto the subject variable `sv`) will route to — one coalesced read
+/// per section instead of one round trip per candidate. Purely a cache
+/// warmer: correctness is untouched, and a local index is a no-op. Used by
+/// the FILTER-CONTAINS pushdown before it probes its candidate subjects.
+pub(crate) fn prefetch_subject_probes(
+    ctx: &Ctx,
+    index: &GraphIndex,
+    patterns: &[TriplePattern],
+    sv: &str,
+    subject_ids: &[u32],
+) {
+    if !index.is_remote() {
+        return;
+    }
+    let Some(lowered) = lower(patterns, ctx) else {
+        return;
+    };
+    let Some(slot) = ctx.slots.slot(sv) else {
+        return;
+    };
+    let dict = ctx.rete.dictionary();
+    let mut pats: Vec<Pattern> = Vec::new();
+    for &sid in subject_ids {
+        let mut base = ctx.slots.empty_row();
+        base[slot] = Some(Val::Id(dict.subject_node(sid) as i64));
+        for t in &lowered {
+            if !matches!(t.0, SlotTerm::Var(i) if i == slot) {
+                continue;
+            }
+            if let (Some(s), Some(p), Some(o)) = (
+                probe_subject(ctx, &t.0, &base),
+                probe_predicate(ctx, &t.1, &base),
+                probe_object(ctx, &t.2, &base),
+            ) {
+                pats.push((s, p, o));
+            }
+        }
+    }
+    index.prefetch_probe_tiles(&pats);
+}
+
 /// A pattern whose own constant terms (a bound subject or object) already route
 /// it to a narrow index range — a few coalesced range reads to scan in full.
 fn pattern_is_selective(t: &(SlotTerm, SlotTerm, SlotTerm)) -> bool {
@@ -531,6 +628,59 @@ fn pattern_estimates(
     )
 }
 
+/// The minimum, over a BGP's patterns, of [`pattern_scan_bytes`] — the
+/// cheapest single-pattern scan the hash-join path would at least perform to
+/// materialize this BGP. `None` = a constant term is unknown to the
+/// dictionary (the BGP is unsatisfiable; the caller short-circuits anyway).
+/// Unlike [`pattern_estimates`], this needs no pyramid summary, so it works on
+/// remote-lazy files — exactly where the answer matters most.
+pub(crate) fn bgp_min_scan_bytes(
+    ctx: &Ctx,
+    index: &GraphIndex,
+    patterns: &[TriplePattern],
+) -> Option<u64> {
+    let lowered = lower(patterns, ctx)?;
+    lowered.iter().map(|t| pattern_scan_bytes(index, t)).min()
+}
+
+/// One pattern's cheapest scan extent in BYTES: for each permutation, sum the
+/// encoded lengths of the tiles a scan of this pattern would route to (all
+/// tiles covering the bound leading key, or the whole section when the leading
+/// key is unbound), and take the minimum. Tile *counts* are useless here — a
+/// broad predicate can sit inside one giant tile — but the directory's byte
+/// lengths expose it. Reads only resident metadata, never tile data.
+fn pattern_scan_bytes(index: &GraphIndex, t: &(SlotTerm, SlotTerm, SlotTerm)) -> u64 {
+    let sections = index.tile_sections();
+    let comp = |role: usize| match role {
+        0 => &t.0,
+        1 => &t.1,
+        _ => &t.2,
+    };
+    let mut best = u64::MAX;
+    for perm in crate::index::ALL_PERMS {
+        let tiles = sections[perm.section_index()];
+        best = best.min(match comp(perm.roles()[0]) {
+            SlotTerm::Node(id) | SlotTerm::Pred(id) => tiles
+                .iter()
+                .filter(|tile| {
+                    let (lo, hi) = tile.leading_range();
+                    lo <= *id && *id <= hi
+                })
+                .map(Tile::encoded_len)
+                .sum(),
+            SlotTerm::Var(_) => tiles.iter().map(Tile::encoded_len).sum(),
+        });
+    }
+    best
+}
+
+/// Scan extent above which a join side counts as "fat": materializing (or, on
+/// a remote index, fetching) ≥2 MiB of encoded tiles to build a hash/merge
+/// side is past the point where probing it per surviving row wins. Shared by
+/// the merge-seed asymmetry gate here and the left-join force-probe gate in
+/// `sparql::eval`.
+pub(crate) const FAT_SCAN_BYTES: u64 = 2 << 20;
+
 /// Order pattern indices for a left-deep join: cheapest (smallest estimated
 /// cardinality) first, always preferring a pattern that shares a variable with
 /// the already-joined set so the join stays connected and intermediate relations