Rete 0.3.2

Rete 0.3.0

The first release of rete-core, rete-cli, and rete-wasm on crates.io.

This is deliberately a 0.x. The code is the same code the 1.0 line will ship,
and the on-disk format is already stable generation 1 — but publishing at 0.3.0
first proves the packaging, the docs.rs builds, cargo install rete-cli, and
the release automation against the real registry before any version has to
honour a compatibility promise. Report problems here rather than against 1.0.0.

Install and artifacts

cargo install rete-cli --version 0.3.0 --locked

The release also provides native archives for:

• Linux GNU: x86-64 and ARM64
• macOS: Intel x86-64 and Apple Silicon ARM64
• Windows MSVC: x86-64 and ARM64

Each archive includes rete, Bash/Zsh/Fish/PowerShell completions, rete(1),
README, license, and changelog.

Three more artifacts ship alongside them:

• rete-<version>-wasm.tar.gz — the browser/WASM bundle.
• rete-blender-<version>.zip — the Blender add-on, which turns a SPARQL
  answer into scene content: 3D assets imported, geometry placed, RDF properties
  inherited as drivable custom properties, relations as hierarchy or rigid-body
  constraints, time on the timeline. Install it with Preferences ▸ Add-ons ▸
  Install from Disk…; the engine is bundled for every platform, so there is no
  further install step. See the Blender guide.
• rete-<version>.mcpb — the Claude Desktop extension
  (MCP Bundle). Download it and
  double-click, or drag it into Claude Desktop. It carries the same engine
  compiled to wasm, so one file installs on macOS, Windows and Linux; it queries
  your own .rete files offline and the published catalogue over HTTP Range.
  See the agentic interfaces guide.

SHA256SUMS covers every archive, the WASM bundle, and both extensions. A
CycloneDX JSON SBOM and GitHub artifact attestations are published with the
release; the SBOM describes the Rust dependency graph and is bound to the
native and WASM archives, while the extension carries build provenance only.

Crates.io publication runbook

crates.io can only attach a trusted publisher to a crate that already exists, so
this first publication is a one-time manual bootstrap; every later tag publishes
through GitHub OIDC with no stored registry secret. It runs only after the
signed tag is checked out in a clean worktree. Enter the ephemeral token inside
the running devcontainer; do not use cargo login:

read -r -s -p "crates.io bootstrap token: " CARGO_REGISTRY_TOKEN
printf '\n'
export CARGO_REGISTRY_TOKEN
bash scripts/publish_crates.sh --bootstrap 0.3.0
unset CARGO_REGISTRY_TOKEN

The script packages and publishes rete-core, waits for registry and sparse
index visibility, then repeats for rete-cli and rete-wasm. Reruns skip an
existing package only when its registry checksum matches the locally packaged
archive. It then downloads all three registry archives, tests fresh native and
WASM consumers, and writes the non-secret
target/release/crates-io-receipt.json. Revoke the bootstrap token immediately
after attaching that receipt to the release and verifying the crates and
docs.rs pages.

After bootstrap, configure trusted publishers for all three crates with owner
caviri, repository rete, workflow release.yml, and environment
crates-io. Configure that GitHub environment with required approval and only
protected v* tags; it must contain no crates.io secret. Run the release
workflow manually against the v0.3.0 tag with verify_crates_io_auth=true.
This requests and automatically revokes a short-lived OIDC token, validates the
tag and package preflight, and makes no publish call. Later release tags publish
in dependency order through the same protected job.

Language clients

Client versions track the engine's MAJOR.MINOR: rete-graph 0.3.x on PyPI and
npm, and the R package, all embed engine 0.3.x. The patch component moves
independently, so a binding-only fix ships as 0.3.1 without an engine release.
scripts/sync_versions.py --check enforces this in CI; --write realigns.
Every client also exposes the engine version it embeds — rete_graph .__engine_version__ in Python — which is the reliable answer to "does my
install support feature X?", since the binding's own version tracks the binding.

Clients release from their own tags (py-v0.3.0, js-v0.3.0), not the v*
release tag.

Cutting a version

scripts/sync_versions.py --set X.Y.Z stamps the workspace, the exact
rete-core pins the publishable crates carry, and every client manifest.
--write will not do this: it only repairs MAJOR.MINOR drift (it writes
{minor}.0), so it is a no-op for the patch bump that is the release.

Two groups deliberately lag the bump, because they name a version a registry
must already serve:

what	when	why
the three PyPI floors — hf-space/requirements.txt, clients/blender/{build.sh,Dockerfile}	after the wheel is on PyPI, via --set-published X.Y.Z	they pip install rete-graph at image-build time; bumping them early fails every image build with Could not find a version that satisfies rete-graph>=X.Y.Z
the Pyodide fallback URL in docs/python.md	with the bump (--set does it)	publish_pyodide_wheel.sh refuses to upload a wheel whose version disagrees with the docs, so the doc has to promise it first — the URL 404s until that upload

--check keeps passing while the floors lag, because the lockstep contract
compares MAJOR.MINOR only.

Also note the engine version is compiled into the wasm (rete_core::VERSION),
so a bump changes the shipped browser binaries: rerun scripts/build_wasm.sh
and commit the artifacts, or the parity gate rejects the release PR.

The Pyodide fallback wheel

%pip install rete-graph resolves from PyPI and needs no pin. But Pyodide
0.29's installer predates PEP 783, which renamed the wheel platform tag
pyodide_* to pyemscripten_*, so it cannot see the wheel PyPI now requires.
docs/python.md points those users at a retagged copy on our own bucket.

The publish workflow builds that copy for every py-v* tag and uploads it as
the pyodide-legacy-wheel artifact — kept out of dist, which goes to PyPI and
would reject the legacy tag. Actually publishing it is a separate step, because
the repository has no R2 credentials in Actions:

scripts/publish_pyodide_wheel.sh          # after the py-v<version> run finishes

It pulls the artifact from that tag's run, refuses anything whose version or
platform tag disagrees with what docs/python.md promises, uploads it to
wheels/, and verifies the documented URL returns 200 with a plausible body.
sync_versions.py --check keeps that URL's version honest; only this step makes
it resolve.

Compatibility statement

Pre-1.0 .rete bytes were explicitly unstable. Rebuild every dataset from its
source RDF with the 0.3 toolchain; do not rename an older file and assume it is
compatible. Files produced by 0.3.0 may still need one final rebuild if review
changes the format before 1.0.0. The durable compatibility promise starts at
1.0.0.

The Rust crates declare Rust 1.87 as their minimum supported version. The
public Rust, CLI, and WASM surfaces carry no semantic-versioning promise while
the crates are 0.x; semver applies from 1.0.0 onward.

Verify a download

sha256sum -c SHA256SUMS
gh attestation verify rete-0.3.0-x86_64-unknown-linux-gnu.tar.gz \
  --repo caviri/rete
./rete-0.3.0-x86_64-unknown-linux-gnu/rete --version

Then build and query a source graph:

rete build source.nq -o graph.rete --pyramid-algo types --card
rete verify graph.rete
rete sparql graph.rete 'SELECT * WHERE { ?s ?p ?o } LIMIT 1'

Known limitations

• Browser execution is single-threaded by default. Threads are experimental and
  require cross-origin isolation.
• Range reads are lazy; query result materialization is currently eager.
• Federation unions results from independent files and does not resolve general
  joins spanning files.
• The RDF/XML parser resolves quick-xml 0.37.5 through upstream Oxigraph:
  every published oxrdfxml, including the current 0.2.3, requires
  quick-xml ^0.37, so the patched 0.41 line is unreachable from here.
  RUSTSEC-2026-0194 and RUSTSEC-2026-0195 are consequently carried as documented
  exceptions in deny.toml and in the publish preflight. Both are
  availability-only denial-of-service findings whose exposure is a caller
  parsing untrusted RDF/XML; neither affects confidentiality or integrity. Both
  exceptions are removed as soon as Oxigraph ships a quick-xml >= 0.41 bump.

Full changes are in the changelog.

v0.3.0

What's Changed

• feat(format)!: 1 KB header with a typed section directory (v0.3, clean break) by @caviri in #54
• Full-text (word/CONTAINS) search — a TEXT_INDEX section by @caviri in #55
• Hybrid BGP join + class-enum seed avoidance (LUBM Q4 14x, Q7 12x) by @caviri in #56
• Six index permutations + sort-merge join (format v0.4) by @caviri in #57
• Lazy / remote SHACL validation — fetch only the shapes' targets by @caviri in #58
• rete why-url — triple-pattern provenance over a remote .rete by @caviri in #59
• wasm: validate the default graph lazily (remote SHACL fetches only targets) by @caviri in #60
• docs: virtual-KG (Ontop/DuckDB over Parquet) alternative + benchmark TODO by @caviri in #61
• docs: validate against code — v0.4 six permutations, subquery support, full CLI/WASM surface by @caviri in #62
• fix(build): pyramid build panics in wasm (clock read breaks the playground Build tab) by @caviri in #63
• playground: SHACL examples for 15 more datasets by @caviri in #64
• Release 1.0.0-rc1 by @caviri in #65
• Playground PR previews and stable BCN dataset by @caviri in #66
• feat(core): split mega-groups across index tiles — bounded build memory + range-scan reader by @caviri in #68
• feat(playground): publish crossref.rete (3.78B triples, remote-lazy) + rebuild reader artifacts by @caviri in #69
• fix(core): u64 section offsets — un-break >4 GiB sections on wasm32 (crossref remote open) by @caviri in #70
• feat(docker): publish multi-arch rete-dev, rete-relay and rete-cli to GHCR by @caviri in #71
• feat(cordis): CORDIS EURIO KG recipe — N-Quads → Parquet + extracted ontology by @caviri in #72
• feat(playground): crossref ontology-browser example (schema without a pyramid) by @caviri in #73
• fix(playground): keep the ontology reference when the schema pyramid is absent by @caviri in #74
• feat: GHCR images, Blender client, and dataset/playground additions by @caviri in #75
• feat(docs): 3D neuromorphology viewer + neuron meshes by @caviri in #76
• feat(docs): neuro viewer — enlarge modal + depth lighting by @caviri in #77
• fix(docs): neuro viewer — coherent tubes + lighting selector by @caviri in #78
• feat(docs): neuro viewer — properties + SPARQL panel, colored lighting by @caviri in #79
• fix(docs): neuro viewer — neurons no longer pitch black (missing normals) by @caviri in #81
• feat(playground): ETH Research Collection — 306,835 works as a scholarly graph by @caviri in #82

Full Changelog: v0.1.0...v0.3.0

rete v0.1.0

rete v0.1.0 — first tagged minor release.

Put an RDF graph in one immutable .rete file, drop it on any HTTP host that honors range requests, and run real SPARQL against it in place — including in the browser via WebAssembly, fetching only the bytes a query needs. Think Parquet (tables) or PMTiles (maps), but for RDF graphs + SPARQL.

▶ Try it in your browser · Docs · Benchmarks

Highlights

Format & storage

• Single-file, immutable .rete image — dictionary, SPO/POS/OSP permutation indexes, and a pyramidal community summary — queryable in place over HTTP Range requests, no server.
• Tiled permutation sections with per-tile zone maps plus tile synopses: per-tile min/max of the non-leading columns in a backward-compatible trailer, so a range reader prunes a routed tile by a bound secondary component before fetching it (a negative/sparse lookup costs zero tile reads).
• Append-only pyramid-meta blocks: schema pyramid (semantic zoom), planner query_stats, characteristic sets / entity shapes, and a bounded label index.

Query

• SPARQL SELECT / ASK / CONSTRUCT / DESCRIBE with joins, OPTIONAL, UNION, MINUS, FILTER, BIND, property paths, aggregation, GeoSPARQL — ~75% of the W3C query-evaluation suite.
• Cost-based BGP join ordering from the summary + measured per-predicate selectivity; hash + index-nested-loop joins.
• rete search — case-insensitive label prefix search from a bounded label index (~22× a FILTER(STRSTARTS(LCASE(…))) scan).

Reasoning, validation, federation

• Prototype OWL RL / RDFS reasoner (coherence + optional materialization), SHACL Core validation, and UNION federation across several .rete files.

Performance

• Build peak RAM cut ~39% on a 3 M-triple build (stream-parse + drop the raw string statements before the pyramid).
• Louvain community-pyramid build ~2.7× faster (dense-scratch local moving, byte-identical output).
• WASM query-result serialization ~13× less peak heap and ~10× faster (direct-to-string envelope instead of a serde_json::Value tree).

Tooling — the rete CLI, the WASM browser client + static playground, and the rete-bench build/query memory profilers.

Format compatibility

On-disk format version v0.2 (readers still accept v0.1), tracked separately from this crate version, in the file header. Experimental: the format is not yet guaranteed stable across releases — rebuild to upgrade.

Full notes in CHANGELOG.md.

What's Changed

• feat: add shacl and progressive summary tooling by @caviri in #2
• chore: add .editorconfig to enforce LF and UTF-8 across editors by @caviri in #3
• feat: add result provenance by @caviri in #4
• docs: refresh oxigraph benchmark by @caviri in #5
• perf: switch SPARQL engine to integer slot rows by @caviri in #6
• perf: adaptive index-nested-loop joins via lazy block group directory by @caviri in #7
• feat: community-split SPARQL - compute per pyramid community, aggrega… by @caviri in #8
• Explorer HF-Space source + sharding/federation + SPARQL conformance by @caviri in #10
• Graph-map / topic-map / 3D experiments + browser graphRAG + Wikidata-1GB by @caviri in #9
• Fix CI rustfmt + de-duplicate graph-map nav group by @caviri in #11
• feat(bench): dataset sha256 + git-commit provenance in the report (re… by @caviri in #12
• playground: bigger causal graph + SPARQL & SHACL examples by @caviri in #13
• core: count named-graph quads in the header quad_count by @caviri in #15
• Playground overhaul: console UX, dataset browser, Map/Time views, WASM test matrix by @caviri in #14
• playground: Map and Time available on every query by @caviri in #16
• playground: lazy Coherence over HTTP range (card-powered inspection, step 1) by @caviri in #18
• playground: cache 'preparing' phase + selective ohm Map/Time examples by @caviri in #17
• playground: switch Output type re-renders the last result (no re-run) by @caviri in #19
• playground: keep the row cache across TTL/JSON-LD switches by @caviri in #20
• playground: group the mode rail into Ask / Inspect, pin History to the bottom by @caviri in #21
• playground: Explore works on remote-lazy datasets (real entities over range) by @caviri in #22
• playground: type FactGrid by P2 so its Explore lists classes by @caviri in #23
• playground: paginated, lazy Explore entity tables (HF dataset-viewer style) by @caviri in #24
• playground: read the packed schema on cache instead of rescanning by @caviri in #25
• wasm/playground: a resident Graph handle for in-memory queries by @caviri in #26
• playground: fix remote schema over worker + rail/header polish by @caviri in #27
• playground: progress for remote schema reads + rail no longer clips History by @caviri in #28
• cli: rete repyramid — rebuild a file's pyramid in place by @caviri in #29
• cli: rete repyramid --card — embed a Dataset Card while rebuilding by @caviri in #30
• playground: adapt the layout for phones by @caviri in #31
• playground: add the Chemotion chemistry-ELN dataset (remote, lazy) by @caviri in #32
• playground: federation across sources + the full ChEBI ontology (remote, lazy) by @caviri in #33
• perf: parallelize and speed up the .rete build by @caviri in #34
• playground: surface the federation example on chemotion too by @caviri in #35
• perf(wasm): cache remote byte ranges across queries (resident RemoteGraph) by @caviri in #36
• docs: federation (CLI + playground), full optimized .rete builds, remote caching by @caviri in #37
• perf(query): cardinality-aware BGP join ordering (cost-based) by @caviri in #38
• perf(wasm): key the remote session/block cache by content hash by @caviri in #39
• docs(architecture): join order is now cost-based by @caviri in #40
• feat(format): query_stats block — per-predicate planner cardinality by @caviri in #41
• perf(query): measured distinct-S/O selectivity in the planner (1b) by @caviri in #42
• docs(architecture): planner uses measured query_stats selectivity (1b) by @caviri in #43
• perf(query): hash join builds the smaller side by @caviri in #44
• docs(architecture): hash join builds the smaller side by @caviri in #45
• feat(format): characteristic sets — entity shapes in the pyramid by @caviri in #46
• docs: rete stats planner stats + entity shapes by @caviri in #47
• feat: label prefix-search index (autocomplete without a literal scan) by @caviri in #48
• perf(build): cut peak RAM on big builds (~1371→836 MiB, 39%) by @caviri in #49
• perf(build): 2.7× faster Louvain pyramid (dense scratch, byte-identical) by @caviri in #50
• feat(index): tile synopses — prune a routed tile by a bound secondary before fetching by @caviri in #51
• perf(wasm): serialize query results direct-to-string (~13× less heap, ~10× faster) by @caviri in #52
• chore(release): v0.1.0 — version bump, CHANGELOG, README/docs by @caviri in #53

Full Changelog: 0.0.1...v0.1.0

0.0.1

Initial Release

Basic functionalities and benchmarks.

What's Changed

• rete v0: cloud-native single-file RDF graph format by @caviri in #1

New Contributors

• @caviri made their first contribution in #1

Full Changelog: https://github.com/caviri/rete/commits/0.0.1