Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
feat: four community extension surfaces — packs, skills, companions, WASM plugins
FABIOTESSc58baf98df94
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 63d6add3..42efd6eb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,26 @@ All notable changes to Open Ontologies are documented here.## [Unreleased]### Added+- **Four extension surfaces** (ECOSYSTEM.md maps them). (1) **Community+ marketplace packs**: `onto_marketplace` now merges an open runtime-fetched+ registry (`community/registry.json`, override with+ `OPEN_ONTOLOGIES_COMMUNITY_REGISTRY`, `community=false` to skip) with the+ curated catalogue — entries are tagged `"source": "curated"|"community"`,+ curated IDs always shadow community IDs, and the shipped registry is+ validated in CI. Seeded with the Manchester/Stanford Pizza teaching+ ontology. (2) **Community skills**: `skills/community/` with a template —+ zero-code markdown workflow recipes. (3) **Companion servers**: the+ five-rule contract (`docs/companion-servers.md`) naming the compose-over-MCP+ pattern OpenCheir already uses (no embedded LLM, no `onto_*` squatting,+ packs/files as interchange, lineage webhook, graceful degradation).+ (4) **WASM plugins** (`--features plugins`): sandboxed community tools via+ the pure-Rust wasmi interpreter — `onto_plugin_list` / `onto_plugin_call`,+ ABI v1 (no host imports, no IO, fuel-metered, fresh instance per call,+ 16 MB return cap), graph access only by caller-passed `sparql` whose rows+ are injected as `bindings`. Reference plugin in+ `examples/plugins/label-case-lint`; ABI exercised by WAT-built plugins in+ `tests/plugin_host_test.rs` (including fuel-exhaustion and oversized-return+ guards). Docs: `docs/plugins.md`.- **fenic support.** [fenic](https://github.com/typedef-ai/fenic) (typedef-ai'ssemantic DataFrame framework) keeps its local catalog in a plain DuckDB filewith user tables under the `typedef_default` schema. The DuckDB schemadiff --git a/CLAUDE.md b/CLAUDE.mdindex 9996b465..2cd696fd 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -58,7 +58,9 @@ Claude dynamically decides the next tool call based on what the previous tool re| `onto_save` | To persist the ontology to a file || `onto_convert` | To convert between formats (Turtle, N-Triples, RDF/XML, N-Quads, TriG) || `onto_clear` | To reset the store before loading a different ontology |-| `onto_marketplace` | To browse and install standard ontologies from a curated catalogue of 33 W3C/ISO/industry standards |+| `onto_marketplace` | To browse and install ontologies: 33 curated W3C/ISO/industry standards plus community packs from the open registry (`community/registry.json`, fetched at runtime; `community=false` for curated/offline only). Curated IDs always win over community IDs |+| `onto_plugin_list` | To discover installed WASM plugins (community `.wasm` tools in `~/.open-ontologies/plugins` or `./plugins`) and the tools each declares. Requires a build with `--features plugins` |+| `onto_plugin_call` | To invoke a plugin tool. Plugins are sandboxed pure JSON→JSON transforms with no store access — pass `sparql` to run a SELECT and inject its rows into the plugin input as `bindings`. Use for domain-specific lint/validation logic contributed by the community || `onto_pull` | To fetch an ontology from a remote URL or SPARQL endpoint || `onto_push` | To push an ontology to a SPARQL endpoint || `onto_import` | To resolve and load owl:imports chains |diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex b659ef77..92450af8 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -71,6 +71,16 @@ The codebase is organized into domain modules under `src/`:| `embed.rs` | ONNX text embedder (embeddings feature) || `structembed.rs` | Poincaré structural embedding trainer (embeddings feature) |+## Contributing Without Writing Rust++Three extension surfaces accept contributions that never touch the core:++- **Community ontology packs** — add a manifest to [`community/registry.json`](community/registry.json); it becomes installable via `onto_marketplace` for every user as soon as the PR merges. Rules and acceptance criteria: [community/README.md](community/README.md).+- **Community skills** — markdown workflow recipes in [`skills/community/`](skills/community/); start from the template there.+- **Companion servers** — build your own MCP server against the [companion contract](docs/companion-servers.md) and PR a listing row to [ECOSYSTEM.md](ECOSYSTEM.md).++For in-process tools, see the **WASM plugin** surface ([docs/plugins.md](docs/plugins.md)) — plugins live in their own repos and need no PR here at all, though we happily link notable ones from ECOSYSTEM.md.+## Pull Requests- Keep PRs focused on a single changediff --git a/Cargo.lock b/Cargo.lockindex 1b082a0a..6a802b9c 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -2209,6 +2209,12 @@ version = "1.5.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"+[[package]]+name = "leb128fmt"+version = "0.1.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"+[[package]]name = "lexical-core"version = "1.0.6"@@ -2782,6 +2788,8 @@ dependencies = ["tracing","tracing-subscriber","tract-onnx",+ "wasmi",+ "wat",][[package]]@@ -4212,6 +4220,12 @@ dependencies = ["spargebra",]+[[package]]+name = "spin"+version = "0.9.9"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3763264f6b73151db08c50ff20d7d8a0b8796e021cdea7ceedad07b80155fa0e"+[[package]]name = "spm_precompiled"version = "0.1.4"@@ -4384,6 +4398,16 @@ dependencies = ["serde",]+[[package]]+name = "string-interner"+version = "0.19.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "23de088478b31c349c9ba67816fa55d9355232d63c3afea8bf513e31f0f1d2c0"+dependencies = [+ "hashbrown 0.15.5",+ "serde",+]+[[package]]name = "stringprep"version = "0.1.5"@@ -4971,7 +4995,7 @@ dependencies = ["parking_lot","scan_fmt","smallvec",- "string-interner",+ "string-interner 0.15.0",][[package]]@@ -5318,6 +5342,100 @@ dependencies = ["unicode-ident",]+[[package]]+name = "wasm-encoder"+version = "0.256.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ec1492381bfd5ea51c2a99a919b676662559925cb8d7490547ec2e14c1ad3eb1"+dependencies = [+ "leb128fmt",+ "wasmparser 0.256.0",+]++[[package]]+name = "wasmi"+version = "1.1.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "2300d0f78cba12f14e29e8dd157ea64050c0a688179aefdb2050105805594a0c"+dependencies = [+ "spin",+ "wasmi_collections",+ "wasmi_core",+ "wasmi_ir",+ "wasmparser 0.239.0",+ "wat",+]++[[package]]+name = "wasmi_collections"+version = "1.1.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f8a8c42a2a76148d43097b1d7cc2a5bf33d5c23bd4dd69015fc887e311767884"+dependencies = [+ "string-interner 0.19.0",+]++[[package]]+name = "wasmi_core"+version = "1.1.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9013136083d988725953390bf668b64b7a218fabf26f8b913bbc59546b97ee27"+dependencies = [+ "libm",+]++[[package]]+name = "wasmi_ir"+version = "1.1.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ba1fa003f79156f406d62ef0e1464dc03e11ace37170e9fa7524299a75ad8f68"+dependencies = [+ "wasmi_core",+]++[[package]]+name = "wasmparser"+version = "0.239.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "8c9d90bb93e764f6beabf1d02028c70a2156a6583e63ac4218dd07ef733368b0"+dependencies = [+ "bitflags 2.13.0",+ "indexmap",+]++[[package]]+name = "wasmparser"+version = "0.256.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "60bd825ffedc6cba8a642924ba7ae424afbc47811cffbcb7b92031ec24e59b4c"+dependencies = [+ "bitflags 2.13.0",+ "indexmap",+ "semver",+]++[[package]]+name = "wast"+version = "256.0.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a3ad42723fc9222da007f05812a3249c9a4ee7af79d497fc2a2079579ad7efe6"+dependencies = [+ "bumpalo",+ "leb128fmt",+ "memchr",+ "unicode-width",+ "wasm-encoder",+]++[[package]]+name = "wat"+version = "1.256.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "37cc86c54d8011b3202e265bfebada440733ea3a788ffaf46d395f7d2fdeacfb"+dependencies = [+ "wast",+]+[[package]]name = "web-sys"version = "0.3.103"diff --git a/Cargo.toml b/Cargo.tomlindex 25287e66..e333b076 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -44,6 +44,7 @@ instant-distance = { version = "0.6", optional = true, features = ["with-serde"]bincode = { version = "1.3", optional = true }sha2 = "0.10"dirs = "6"+wasmi = { version = "1.1.0", optional = true }[features]default = []@@ -58,6 +59,11 @@ embeddings = ["tract-onnx", "tokenizers", "instant-distance", "bincode"]# structural proxy. Zero additional Rust dependencies — the entire feature# is shipped as embedded Python + subprocess plumbing.causal-pywhy = []+# WASM plugin host: community tools compiled to wasm32-unknown-unknown, run+# in-process behind onto_plugin_list / onto_plugin_call. Pure-Rust interpreter+# (wasmi) with fuel metering — no system deps, the binary stays self-contained.+plugins = ["dep:wasmi"][dev-dependencies]tempfile = "3"+wat = "1.256.0"diff --git a/ECOSYSTEM.md b/ECOSYSTEM.mdnew file mode 100644index 00000000..fc33682a--- /dev/null+++ b/ECOSYSTEM.md@@ -0,0 +1,32 @@+# Ecosystem++Open Ontologies is extensible on four surfaces, in increasing order of coupling:++| Surface | What it is | Contribute via |+| ------- | ---------- | -------------- |+| **Community packs** | Ontology data packs, installable through `onto_marketplace` at runtime | PR to [`community/registry.json`](community/registry.json) — see [community/README.md](community/README.md) |+| **Community skills** | Markdown workflow recipes that teach agents to chain `onto_*` tools | PR to [`skills/community/`](skills/community/) |+| **Companion servers** | Independent MCP servers composing with the core in one session | Follow the [companion contract](docs/companion-servers.md), then PR a row below |+| **WASM plugins** | Community `onto_*`-adjacent tools running in-process, sandboxed | See [docs/plugins.md](docs/plugins.md) |++## Companion servers++| Name | What it does | Contract surface |+| ---- | ------------ | ---------------- |+| [OpenCheir](https://github.com/fabio-rovai/opencheir) | Workflow governance — enforcer rules over ontology-engineering sessions (validate-after-save, version-before-push), automatic verdict logging | Lineage webhook consumer (`GOVERNANCE_WEBHOOK`) |++## Clients & surfaces++| Name | What it does |+| ---- | ------------ |+| [Studio](studio/) | Desktop app (Tauri) wrapping the engine — ontology tree, AI chat panel, property inspector, lineage viewer |+| [Obsidian plugin](https://github.com/fabio-rovai/obsidian-open-ontologies) | Brings the engine to Obsidian vaults — notes as a knowledge-graph surface |++## Community packs (highlights)++The live registry is [`community/registry.json`](community/registry.json); `onto_marketplace list` shows the current set with `"source": "community"`.++## Getting listed++- **Packs and skills**: merged PR = listed, no separate step.+- **Companion servers**: PR a row to the table above; criteria in [docs/companion-servers.md](docs/companion-servers.md#getting-listed).diff --git a/README.md b/README.mdindex 9f4292e3..a34f199d 100644--- a/README.md+++ b/README.md@@ -30,6 +30,7 @@<a href="#benchmarks">Benchmarks</a> ·<a href="#ies-support">IES</a> ·<a href="#tools">Tools</a> ·+ <a href="#extending-open-ontologies">Extending</a> ·<a href="#architecture">Architecture</a> ·<a href="#documentation">Docs</a></p>@@ -822,7 +823,8 @@ The same tool, applied to any ontology, produces the same kind of improvement. T| **Core** | `validate` `load` `save` `clear` `stats` `query` `diff` `lint` `convert` `status` | RDF/OWL validation, querying, and management || **Repository** | `repo_list` `repo_load` | Browse and load ontologies from configured `[general] ontology_dirs` directories || **Cache** | `cache_status` `cache_list` `cache_remove` `unload` `recompile` | On-disk N-Triples compile cache, idle-TTL eviction, per-name management ([details](docs/cache-and-registry.md)) |-| **Marketplace** | `marketplace` | Browse and install 33 standard W3C/ISO/industry ontologies |+| **Marketplace** | `marketplace` | Browse and install 33 curated W3C/ISO/industry ontologies + open [community packs](community/README.md) |+| **Plugins** | `plugin_list` `plugin_call` | Discover and invoke sandboxed community WASM plugins (`--features plugins`, [details](docs/plugins.md)) || **Remote** | `pull` `push` `import` | Fetch/push ontologies, resolve owl:imports || **Schema** | `import-schema` `sql-ingest` | Postgres + DuckDB → OWL + SQL → RDF ingest || **Data** | `map` `ingest` `shacl` `shacl_check` `vocab_check` `reason` `extend` | Structured data → RDF pipeline; `vocab_check` = closed-world check that generated data uses only ontology-declared terms (catches what open-world SHACL misses) |@@ -848,6 +850,21 @@ The same tool, applied to any ontology, produces the same kind of improvement. T---+## Extending Open Ontologies++Four extension surfaces, in increasing order of coupling — full map in [ECOSYSTEM.md](ECOSYSTEM.md):++| Surface | Contribution is | How |+| ------- | --------------- | --- |+| **[Community packs](community/README.md)** | Data — an ontology manifest in an open registry, installable via `onto_marketplace` the moment the PR merges (no release) | PR to [`community/registry.json`](community/registry.json) |+| **[Community skills](skills/community/)** | Markdown — workflow recipes teaching agents to chain `onto_*` tools | PR a `SKILL.md` directory |+| **[Companion servers](docs/companion-servers.md)** | An independent MCP server composing with this one in-session (lineage webhook, pack interchange, SPARQL endpoints) — [OpenCheir](https://github.com/fabio-rovai/opencheir) is the reference | Follow the five-rule contract, PR an [ECOSYSTEM.md](ECOSYSTEM.md) row |+| **[WASM plugins](docs/plugins.md)** | Code — sandboxed wasm32 tools run in-process with fuel metering, no imports, no IO, per-call capability grants | Implement ABI v1 (reference: [`examples/plugins/`](examples/plugins/)) |++Everything holds the MCP-native convention: extensions provide validation and scaffolding; the connected LLM does the intelligence.++---+## Architecture### Enginediff --git a/community/README.md b/community/README.mdnew file mode 100644index 00000000..056780ed--- /dev/null+++ b/community/README.md@@ -0,0 +1,64 @@+# Community Packs++The marketplace has two tiers:++- **Curated catalogue** — 33 W3C/ISO/industry standard ontologies, compiled into the binary and vetted by maintainers.+- **Community packs** (this directory) — an open-submission registry. Anyone can add an ontology pack by PR. The server fetches `registry.json` at runtime, so a merged pack becomes installable by every user immediately — no release needed.++A pack is **data, not code**: a manifest pointing at an ontology file the server fetches over HTTPS and loads into the triple store. Nothing in a pack executes.++## Installing community packs++```bash+onto_marketplace list # curated + community, each entry tagged with its source+onto_marketplace install pizza # curated IDs are checked first, then community+```++The registry is resolved in priority order:++1. `OPEN_ONTOLOGIES_COMMUNITY_REGISTRY` — a URL or local file path (use this to pin, mirror, or run your own registry)+2. `./community/registry.json` if the server runs from a source checkout+3. The canonical registry on GitHub: `https://raw.githubusercontent.com/fabio-rovai/open-ontologies/main/community/registry.json`++If the registry cannot be fetched, `onto_marketplace` degrades gracefully to the curated catalogue and reports the error.++## Submitting a pack++Open a PR adding one object to the `packs` array in [`registry.json`](registry.json):++```json+{+ "id": "my-pack",+ "name": "Human-Readable Name",+ "description": "What it is and when a Claude session would install it.",+ "domain": "one-word-domain",+ "url": "https://example.org/my-ontology.ttl",+ "format": "turtle",+ "maintainer": "@your-github-handle",+ "homepage": "https://example.org",+ "license": "CC-BY-4.0"+}+```++| Field | Required | Rules |+| ----- | -------- | ----- |+| `id` | yes | Lowercase kebab-case (`[a-z0-9-]`), unique, must not collide with a curated ID (curated always wins) |+| `name` | yes | Human-readable name |+| `description` | yes | One or two sentences; say when an agent should install it |+| `domain` | yes | Short domain tag used for filtering (e.g. `teaching`, `maritime`, `legal`) |+| `url` | yes | Direct HTTPS link to the raw ontology file — stable, no auth, no HTML landing page |+| `format` | yes | One of `turtle`, `rdfxml`, `ntriples`, `nquads`, `trig` |+| `maintainer` | no | GitHub handle of the submitter |+| `homepage` | no | Project or documentation page |+| `license` | no (strongly encouraged) | SPDX identifier of the ontology's licence |++## Acceptance criteria++A PR is merged when:++1. `cargo test marketplace` passes — the shipped registry is validated in CI (`shipped_community_registry_is_valid`), so a malformed manifest fails the build.+2. The URL serves the raw ontology file and `onto_validate` + `onto_load` succeed on it.+3. The ontology is openly licensed (or the licence is clearly stated and permits redistribution by fetch).+4. The description honestly says what the pack is. Teaching examples, niche domain vocabularies, and drafts are all welcome — that is what the community tier is for.++Maintainers may remove packs whose URLs go dead. Pin a specific version in the URL (a tagged raw GitHub link, a w3id.org PURL) rather than a moving branch where possible.diff --git a/community/registry.json b/community/registry.jsonnew file mode 100644index 00000000..a2288522--- /dev/null+++ b/community/registry.json@@ -0,0 +1,16 @@+{+ "version": 1,+ "packs": [+ {+ "id": "pizza",+ "name": "Pizza Ontology",+ "description": "The Manchester/Stanford Pizza tutorial ontology — the canonical OWL teaching example, with defined classes, disjointness, and value partitions. Useful for demos, tests, and learning DL reasoning with onto_dl_check / onto_dl_explain.",+ "domain": "teaching",+ "url": "https://protege.stanford.edu/ontologies/pizza/pizza.owl",+ "format": "rdfxml",+ "maintainer": "Stanford Protégé team (pack submitted by @fabio-rovai)",+ "homepage": "https://protege.stanford.edu",+ "license": "CC-BY-3.0"+ }+ ]+}diff --git a/docs/companion-servers.md b/docs/companion-servers.mdnew file mode 100644index 00000000..a849c201--- /dev/null+++ b/docs/companion-servers.md@@ -0,0 +1,46 @@+# Companion Servers++Open Ontologies is extensible without touching its binary: because it is an MCP server, **any other MCP server connected to the same session composes with it** — the orchestrating agent chains tools across servers in one conversation. [OpenCheir](https://github.com/fabio-rovai/opencheir) already works this way: it watches Open Ontologies' lineage events and enforces workflow rules, with zero coupling beyond a webhook.++This document names that pattern — the **companion server** — and defines the contract that makes a companion feel like part of one product instead of two tools that happen to coexist.++## The contract++A companion server that follows these five rules gets listed in [ECOSYSTEM.md](../ECOSYSTEM.md).++### 1. MCP-native: no embedded LLM++The connected orchestrator is already an LLM. A companion provides validation primitives, scaffolding outputs, and feedback channels — it never embeds its own LLM client, requires an API key, or hides judgment inside a server function. This is the same convention the core server holds itself to (see "Architecture Convention: MCP-Native Tool Design" in [CLAUDE.md](../CLAUDE.md)).++### 2. Tool naming: never squat `onto_*`++The `onto_` prefix belongs to the core server. A companion picks its own short prefix (`oo_<name>_*` or a product name like `opencheir_*`) so a session with both servers connected has an unambiguous tool namespace, and skills can reference tools without qualification.++### 3. Interchange: packs and files, not shared memory++Companions never reach into the core server's in-memory store. The interchange artifacts are:++- **Ontology files** — Turtle/N-Triples in directories both servers can be pointed at (`[general] ontology_dirs`).+- **Packs** — `onto_pack` output is the promotion artifact: sorted N-Triples + manifest + checksums + recorded lint/enforce evidence. A companion that consumes graphs should accept packs and verify checksums (`onto_unpack --verify_only` semantics) rather than trusting bare files.+- **SPARQL endpoints** — the core can `onto_push`/`onto_pull` against any endpoint a companion exposes or consumes.++### 4. Events: the lineage webhook++The core POSTs every lineage event (plan, apply, save, push, …) to `GOVERNANCE_WEBHOOK` if set. A companion that wants to observe the engineering workflow subscribes there — it does not poll, and it does not require the core to know it exists:++```bash+your-companion serve & # listens on :9900+GOVERNANCE_WEBHOOK=http://localhost:9900/api/enforcer/event open-ontologies serve+```++### 5. Degrade gracefully++The core must work fully with the companion absent, and vice versa. Optional integration, never a hard dependency — the OpenCheir enforcer rules are the reference implementation of this posture.++## What makes a good companion++The distinguishing question is the same one used for core tools: *what primitive does the orchestrator need that it can't compute itself?* Good companion territory: domain rule packs behind a validation surface (regulatory, clinical, defence), storage/deployment backends (pack registries, triple-store sync), observability (dashboards over lineage events), and editor/UI surfaces (the Obsidian plugin is a companion in this sense — it brings vault notes to the same engine).++## Getting listed++Open a PR adding a row to [ECOSYSTEM.md](../ECOSYSTEM.md) with: name, repo link, one-line description, and which of the five contract rules your server exercises (webhook consumer, pack consumer, endpoint provider, …). Listing criteria: the repo is public, the README shows it composing with Open Ontologies in a real session, and it holds rule 1.diff --git a/docs/plugins.md b/docs/plugins.mdnew file mode 100644index 00000000..02932de3--- /dev/null+++ b/docs/plugins.md@@ -0,0 +1,96 @@+# WASM Plugins++The in-process extension surface: community-authored tools compiled to WebAssembly, discovered from a plugin directory, and exposed through two MCP tools — `onto_plugin_list` and `onto_plugin_call`. The host is the pure-Rust wasmi interpreter, so the single-binary story holds: no system dependencies, no dynamic linking.++Enable it at build time:++```bash+cargo build --release --features plugins+```++Without the feature, both tools exist and return a clean "compiled without plugins" error.++## Trust and capability model++Plugins are sandboxed harder than any other extension tier:++- **No imports.** ABI v1 plugins may not import host functions at all — a module that declares imports fails instantiation. No filesystem, no network, no clocks.+- **No store access.** A plugin sees graph data only when the *caller* passes `sparql` to `onto_plugin_call`; the host runs the SELECT and injects the result rows into the plugin's input as `bindings`. The capability grant is explicit, per-call, and read-only.+- **Fuel metering.** Every invocation gets a bounded instruction budget; an infinite loop traps instead of hanging the server.+- **Fresh instance per call.** Plugins are stateless by construction; nothing persists between invocations.+- **Bounded output.** Returns are capped at 16 MB.++This makes a plugin the right home for *pure validation and transformation logic*: domain-specific lint rules, naming-convention checks, metric computations, report formatting. It is the wrong home for anything needing IO — that is a [companion server](companion-servers.md).++## Installing plugins++Drop `.wasm` files into either directory (or set `OPEN_ONTOLOGIES_PLUGIN_DIRS`, colon-separated, to override both):++```+~/.open-ontologies/plugins/+./plugins/+```++`onto_plugin_list` shows what was found, the tools each plugin declares, and any files that failed to load (a broken plugin never hides the working ones).++## ABI v1++A plugin is a wasm32 module exporting:++| Export | Signature | Contract |+| ------ | --------- | -------- |+| `memory` | linear memory | Host reads results from and writes inputs into it |+| `oo_abi_version` | `() -> i32` | Must return `1` |+| `oo_alloc` | `(len: i32) -> i32` | Return a pointer to `len` writable bytes for the host's input |+| `oo_describe` | `() -> i64` | Return `(ptr << 32) \| len` of a UTF-8 JSON manifest |+| `oo_call` | `(ptr: i32, len: i32) -> i64` | Handle one invocation; return packed ptr/len of UTF-8 JSON |++The manifest:++```json+{+ "name": "my-plugin",+ "version": "0.1.0",+ "tools": [{"name": "my_tool", "description": "When an agent should call this"}]+}+```++The input document `oo_call` receives:++```json+{+ "tool": "my_tool",+ "input": { "whatever the caller passed": true },+ "bindings": [ {"class": "<http://…>", "label": "…"} ]+}+```++`bindings` is present only when the caller supplied `sparql`; it is the SELECT's result rows keyed by variable name. Return any JSON value; by convention `{"ok": true, …}` on success and `{"error": "…"}` on failure.++## Writing a plugin in Rust++The reference implementation is [`examples/plugins/label-case-lint`](../examples/plugins/label-case-lint/) — a label-convention linter over injected bindings. Build and install:++```bash+rustup target add wasm32-unknown-unknown+cd examples/plugins/label-case-lint+cargo build --release --target wasm32-unknown-unknown+mkdir -p ~/.open-ontologies/plugins+cp target/wasm32-unknown-unknown/release/label_case_lint.wasm ~/.open-ontologies/plugins/+```++Then, in a session:++```text+onto_plugin_list+onto_plugin_call plugin=label-case-lint tool=lint_labels \+ sparql='SELECT ?class ?label WHERE { ?class a <http://www.w3.org/2002/07/owl#Class> ; <http://www.w3.org/2000/01/rdf-schema#label> ?label }'+```++Any language that compiles to freestanding wasm32 with exported functions works the same way — the test suite ([`tests/plugin_host_test.rs`](../tests/plugin_host_test.rs)) exercises the ABI with plugins hand-written in WAT.++## Design position++Plugins hold the project's MCP-native convention at the binary level: they are validation/scaffolding primitives, not agents. If your plugin wants to call an LLM, phone home, or orchestrate — flip the design (see [CLAUDE.md](../CLAUDE.md), "Architecture Convention"). The orchestrator judges; plugins compute.++ABI v1 is deliberately minimal. Planned, gated on real demand: host-function imports under named capabilities (e.g. a plugin declaring `sparql-select` gets a host import instead of caller-injected bindings), and dynamic MCP tool registration (`tools/list_changed`) so plugin tools appear as first-class `onto_*` entries.diff --git a/examples/plugins/README.md b/examples/plugins/README.mdnew file mode 100644index 00000000..c2b7a4a1--- /dev/null+++ b/examples/plugins/README.md@@ -0,0 +1,16 @@+# Example Plugins++Reference implementations of the [WASM plugin ABI](../../docs/plugins.md).++| Plugin | What it does |+| ------ | ------------ |+| [`label-case-lint`](label-case-lint/) | Lints class labels from injected SPARQL bindings: empty labels, stray whitespace, lowercase-initial class labels |++Each is an independent Cargo project (not part of the main build). Build with:++```bash+rustup target add wasm32-unknown-unknown+cargo build --release --target wasm32-unknown-unknown+```++and copy the resulting `.wasm` from `target/wasm32-unknown-unknown/release/` into `~/.open-ontologies/plugins/`.diff --git a/examples/plugins/label-case-lint/Cargo.toml b/examples/plugins/label-case-lint/Cargo.tomlnew file mode 100644index 00000000..a551c0f5--- /dev/null+++ b/examples/plugins/label-case-lint/Cargo.toml@@ -0,0 +1,15 @@+[package]+name = "label-case-lint"+version = "0.1.0"+edition = "2021"+publish = false++[lib]+crate-type = ["cdylib"]++[dependencies]+serde_json = "1"++[profile.release]+opt-level = "s"+lto = truediff --git a/examples/plugins/label-case-lint/src/lib.rs b/examples/plugins/label-case-lint/src/lib.rsnew file mode 100644index 00000000..4e02d103--- /dev/null+++ b/examples/plugins/label-case-lint/src/lib.rs@@ -0,0 +1,94 @@+//! Reference Open Ontologies plugin (ABI v1): lints class labels for+//! convention violations. Demonstrates the full contract — manifest,+//! allocation, packed-pointer returns, and consuming injected SPARQL+//! bindings.+//!+//! Invoke as:+//!+//! ```text+//! onto_plugin_call plugin=label-case-lint tool=lint_labels \+//! sparql='SELECT ?class ?label WHERE { ?class a <http://www.w3.org/2002/07/owl#Class> ; <http://www.w3.org/2000/01/rdf-schema#label> ?label }'+//! ```++use serde_json::{json, Value};++const MANIFEST: &str = r#"{+ "name": "label-case-lint",+ "version": "0.1.0",+ "tools": [{+ "name": "lint_labels",+ "description": "Checks class labels from injected SPARQL bindings (?label, plus any subject var for attribution): flags empty labels, leading/trailing/double whitespace, and labels not starting with an uppercase letter"+ }]+}"#;++#[no_mangle]+pub extern "C" fn oo_abi_version() -> i32 {+ 1+}++#[no_mangle]+pub extern "C" fn oo_alloc(len: i32) -> i32 {+ let layout = std::alloc::Layout::from_size_align(len.max(1) as usize, 1).unwrap();+ unsafe { std::alloc::alloc(layout) as i32 }+}++/// Pack a byte buffer into the ABI's `(ptr << 32) | len` return form. The+/// buffer is leaked on purpose: the instance is torn down after each call.+fn pack(bytes: Vec<u8>) -> i64 {+ let len = bytes.len() as u64;+ let ptr = Vec::leak(bytes).as_ptr() as u32 as u64;+ ((ptr << 32) | len) as i64+}++#[no_mangle]+pub extern "C" fn oo_describe() -> i64 {+ pack(MANIFEST.as_bytes().to_vec())+}++#[no_mangle]+pub extern "C" fn oo_call(ptr: i32, len: i32) -> i64 {+ let input = unsafe { std::slice::from_raw_parts(ptr as *const u8, len as usize) };+ let doc: Value = match serde_json::from_slice(input) {+ Ok(v) => v,+ Err(e) => return pack(json!({"error": format!("invalid input JSON: {e}")}).to_string().into_bytes()),+ };+ match doc["tool"].as_str() {+ Some("lint_labels") => pack(lint_labels(&doc).to_string().into_bytes()),+ other => pack(json!({"error": format!("unknown tool {other:?}")}).to_string().into_bytes()),+ }+}++fn lint_labels(doc: &Value) -> Value {+ let Some(rows) = doc["bindings"].as_array() else {+ return json!({"error": "no bindings — pass a `sparql` SELECT with a ?label variable to onto_plugin_call"});+ };+ let mut issues = Vec::new();+ for row in rows {+ let Some(label) = row["label"].as_str() else { continue };+ let label = label.trim_start_matches('"');+ let label = label.split('"').next().unwrap_or(label);+ let subject = row+ .as_object()+ .and_then(|o| o.iter().find(|(k, _)| *k != "label"))+ .and_then(|(_, v)| v.as_str())+ .unwrap_or("?");+ let mut problems = Vec::new();+ if label.is_empty() {+ problems.push("empty label");+ } else {+ if label != label.trim() {+ problems.push("leading/trailing whitespace");+ }+ if label.contains(" ") {+ problems.push("double whitespace");+ }+ if label.chars().next().is_some_and(|c| c.is_lowercase()) {+ problems.push("class label should start uppercase");+ }+ }+ if !problems.is_empty() {+ issues.push(json!({"subject": subject, "label": label, "problems": problems}));+ }+ }+ json!({"ok": true, "checked": rows.len(), "issues": issues})+}diff --git a/skills/community/README.md b/skills/community/README.mdnew file mode 100644index 00000000..cbc8de38--- /dev/null+++ b/skills/community/README.md@@ -0,0 +1,38 @@+# Community Skills++Skills are the zero-code extension tier: markdown workflow recipes that teach a connected agent (Claude or any MCP client) how to chain the `onto_*` tools for a specific job. The bundled [`ontology-engineering`](../ontology-engineering/SKILL.md) skill is the reference — community skills live here, one directory per skill.++If you have a tool-chaining pattern that works — a validation gauntlet for a specific domain, a migration recipe, an alignment review loop — you can contribute it without writing a line of Rust.++## Layout++```+skills/community/+ your-skill-name/+ SKILL.md # required — frontmatter + instructions+ references/ # optional — supporting files the skill points at+```++`SKILL.md` starts with YAML frontmatter:++```yaml+---+name: your-skill-name+description: One sentence saying WHEN an agent should use this skill, not just what it does.+---+```++Copy [`TEMPLATE.md`](TEMPLATE.md) to `your-skill-name/SKILL.md` to start.++## What makes a good skill++1. **Trigger-first description.** The frontmatter description is what an agent reads to decide relevance. "Use when validating a clinical ontology against SNOMED crosswalks" beats "clinical utilities".+2. **Tool sequences with decision points**, not fixed pipelines. Say what to call next *based on what the previous tool returned* — that is the project's core orchestration principle.+3. **Real tool names.** Every `onto_*` reference must exist in the current tool set (see the [Tool Reference](../../CLAUDE.md)). CI reviewers will check.+4. **MCP-native.** A skill instructs the *orchestrating agent*; it must not tell the server to call an LLM. Judgment happens in the conversation, verdicts flow back through the `*_feedback` tools.++## Submitting++Open a PR adding your skill directory. Acceptance criteria: frontmatter parses, referenced tools exist, the workflow is honest about failure modes (what to do when `onto_validate` fails, not just the happy path).++Skills here are documentation, not executable code — the same trust model as the community pack registry.diff --git a/skills/community/TEMPLATE.md b/skills/community/TEMPLATE.mdnew file mode 100644index 00000000..a54b03ba--- /dev/null+++ b/skills/community/TEMPLATE.md@@ -0,0 +1,33 @@+---+name: your-skill-name+description: One sentence saying WHEN an agent should use this skill. Name the trigger conditions, domain, and tools involved.+---++# Your Skill Name++One paragraph: what job this skill accomplishes and what state it assumes (e.g. "an ontology is already loaded" or "starts from a Turtle file on disk").++## Workflow++### 1. First stage++- Call `onto_validate` on the input — if it fails, fix the reported syntax errors and re-validate before anything else.+- Call `onto_load`, then `onto_stats` to confirm counts match expectations.++### 2. Decision point++- If `onto_stats` shows N classes but the spec expects M, do X.+- If `onto_lint` reports missing labels, add them and reload — do not proceed with a dirty lint.++### 3. Verify and persist++- State the checks that must pass before the skill is done (lint clean, enforce clean, competency questions answerable via `onto_query`).+- Call `onto_save`, then `onto_version` — always version after save.++## Failure modes++Say what to do when things go wrong, not just the happy path:++- Fetch/parse failures: ...+- Validation that never converges: ...+- When to stop and ask the user: ...diff --git a/src/inputs.rs b/src/inputs.rsindex 9e735e2e..5b06f829 100644--- a/src/inputs.rs+++ b/src/inputs.rs@@ -562,6 +562,20 @@ pub struct OntoMarketplaceInput {pub id: Option<String>,/// Filter list by domain (e.g. "foundational", "metadata", "iot", "geospatial")pub domain: Option<String>,+ /// Include community packs from the open registry (default true). Set false for the curated catalogue only / offline use.+ pub community: Option<bool>,+}++#[derive(Deserialize, JsonSchema)]+pub struct OntoPluginCallInput {+ /// Plugin name (as reported by onto_plugin_list)+ pub plugin: String,+ /// Tool name within the plugin (as reported by onto_plugin_list)+ pub tool: String,+ /// JSON input passed to the plugin tool+ pub input: Option<serde_json::Value>,+ /// Optional SPARQL SELECT run against the loaded store first; its result bindings are injected into the plugin's input as "bindings". This is the only way a plugin sees graph data — plugins have no direct store access.+ pub sparql: Option<String>,}// ─── Prompt input structs ───────────────────────────────────────────────────diff --git a/src/lib.rs b/src/lib.rsindex 90534fed..506c6008 100644--- a/src/lib.rs+++ b/src/lib.rs@@ -55,6 +55,8 @@ pub mod plan;pub mod plan_classical;pub mod plan_pddl;pub mod plan_validate;+#[cfg(feature = "plugins")]+pub mod plugins;#[cfg(feature = "embeddings")]pub mod poincare;pub mod reason;diff --git a/src/main.rs b/src/main.rsindex eae79a08..e2392185 100644--- a/src/main.rs+++ b/src/main.rs@@ -1559,7 +1559,7 @@ async fn async_main() -> anyhow::Result<()> {match action.as_str() {"list" => {let entries = marketplace::list(domain.as_deref());- let items: Vec<serde_json::Value> = entries+ let mut items: Vec<serde_json::Value> = entries.iter().map(|e| {serde_json::json!({@@ -1568,13 +1568,34 @@ async fn async_main() -> anyhow::Result<()> {"description": e.description,"domain": e.domain,"format": marketplace::format_name(e.format),+ "source": "curated",})}).collect();+ let mut community_error = None;+ match marketplace::load_community_packs().await {+ Ok((packs, _shadowed, _source)) => {+ for p in packs+ .iter()+ .filter(|p| domain.as_deref().is_none_or(|d| p.domain == d))+ {+ items.push(serde_json::json!({+ "id": p.id,+ "name": p.name,+ "description": p.description,+ "domain": p.domain,+ "format": p.format,+ "source": "community",+ }));+ }+ }+ Err(e) => community_error = Some(e),+ }output_json(&serde_json::json!({"count": items.len(),"ontologies": items,+ "community_registry_error": community_error,}),cli.pretty,);@@ -1584,26 +1605,40 @@ async fn async_main() -> anyhow::Result<()> {eprintln!("Error: --id is required for install");std::process::exit(1);});- let entry = match marketplace::find(id) {- Some(e) => e,- None => {- eprintln!(- "Unknown ontology ID: '{}'. Run 'marketplace list' to see available IDs.",- id- );- std::process::exit(1);- }- };+ // Curated first; community packs can never shadow a curated ID.+ let (entry_id, entry_name, entry_url, entry_format) =+ match marketplace::find(id) {+ Some(e) => (e.id.to_string(), e.name.to_string(), e.url.to_string(), e.format),+ None => {+ let community = match marketplace::load_community_packs().await {+ Ok((packs, _, _)) => packs.into_iter().find(|p| p.id == id),+ Err(_) => None,+ };+ match community.and_then(|p| {+ marketplace::parse_format(&p.format)+ .map(|f| (p.id, p.name, p.url, f))+ }) {+ Some(t) => t,+ None => {+ eprintln!(+ "Unknown ontology ID: '{}'. Run 'marketplace list' to see curated and community IDs.",+ id+ );+ std::process::exit(1);+ }+ }+ }+ };let (_db, graph) = setup(&cli.data_dir)?;- let content = GraphStore::fetch_url(entry.url).await?;- match graph.load_content_with_base(&content, entry.format, Some(entry.url)) {+ let content = GraphStore::fetch_url(&entry_url).await?;+ match graph.load_content_with_base(&content, entry_format, Some(&entry_url)) {Ok(count) => {let stats = graph.get_stats().unwrap_or_default();output_json(&serde_json::json!({"ok": true,- "installed": entry.id,- "name": entry.name,+ "installed": entry_id,+ "name": entry_name,"triples_loaded": count,"stats": serde_json::from_str::<serde_json::Value>(&stats).unwrap_or_default(),}),diff --git a/src/marketplace.rs b/src/marketplace.rsindex 605a8121..6d864b84 100644--- a/src/marketplace.rs+++ b/src/marketplace.rs@@ -336,6 +336,129 @@ pub fn format_name(fmt: RdfFormat) -> &'static str {}}+/// Parse a manifest format string back into an RdfFormat.+pub fn parse_format(s: &str) -> Option<RdfFormat> {+ match s {+ "turtle" => Some(RdfFormat::Turtle),+ "rdfxml" => Some(RdfFormat::RdfXml),+ "ntriples" => Some(RdfFormat::NTriples),+ "nquads" => Some(RdfFormat::NQuads),+ "trig" => Some(RdfFormat::TriG),+ _ => None,+ }+}++// ─── Community packs ─────────────────────────────────────────────────────────+//+// The curated CATALOGUE above is compiled in and vetted by maintainers. The+// community registry is the open-submission tier: a JSON file of pack+// manifests, contributed by PR to `community/registry.json` and fetched at+// runtime, so new packs become installable without a release. Packs are DATA+// (ontology files fetched over HTTP), never code.++/// A community-contributed ontology pack, loaded at runtime from the registry.+#[derive(Debug, Clone, serde::Deserialize)]+pub struct CommunityEntry {+ pub id: String,+ pub name: String,+ pub description: String,+ pub domain: String,+ pub url: String,+ /// One of: turtle, rdfxml, ntriples, nquads, trig+ pub format: String,+ #[serde(default)]+ pub maintainer: Option<String>,+ #[serde(default)]+ pub homepage: Option<String>,+ #[serde(default)]+ pub license: Option<String>,+}++#[derive(Debug, serde::Deserialize)]+pub struct CommunityRegistry {+ pub version: u32,+ pub packs: Vec<CommunityEntry>,+}++/// Canonical location of the community registry on the default branch.+pub const DEFAULT_COMMUNITY_REGISTRY_URL: &str =+ "https://raw.githubusercontent.com/fabio-rovai/open-ontologies/main/community/registry.json";++/// Resolve where the community registry comes from, in priority order:+/// 1. `OPEN_ONTOLOGIES_COMMUNITY_REGISTRY` (a URL or a local file path)+/// 2. `./community/registry.json` if present (source checkouts, air-gapped installs)+/// 3. the canonical GitHub raw URL+pub fn community_registry_source() -> String {+ if let Ok(v) = std::env::var("OPEN_ONTOLOGIES_COMMUNITY_REGISTRY")+ && !v.trim().is_empty() {+ return v;+ }+ let local = std::path::Path::new("community/registry.json");+ if local.exists() {+ return local.to_string_lossy().into_owned();+ }+ DEFAULT_COMMUNITY_REGISTRY_URL.to_string()+}++/// Fetch and parse the community registry from wherever+/// [`community_registry_source`] resolves to. Returns (packs, shadowed_ids,+/// source) so callers can attribute provenance in their output.+pub async fn load_community_packs() -> Result<(Vec<CommunityEntry>, Vec<String>, String), String> {+ let source = community_registry_source();+ let json = if source.starts_with("http://") || source.starts_with("https://") {+ crate::graph::GraphStore::fetch_url(&source)+ .await+ .map_err(|e| format!("registry fetch failed ({source}): {e}"))?+ } else {+ std::fs::read_to_string(&source)+ .map_err(|e| format!("registry read failed ({source}): {e}"))?+ };+ let (packs, shadowed) = parse_community_registry(&json)?;+ Ok((packs, shadowed, source))+}++/// Parse and validate registry JSON. Rejects malformed manifests outright;+/// packs whose IDs collide with the curated catalogue are dropped (curated+/// wins) and reported back so the caller can surface the shadowing.+pub fn parse_community_registry(json: &str) -> Result<(Vec<CommunityEntry>, Vec<String>), String> {+ let registry: CommunityRegistry =+ serde_json::from_str(json).map_err(|e| format!("invalid registry JSON: {e}"))?;+ if registry.version != 1 {+ return Err(format!("unsupported registry version {}", registry.version));+ }+ let mut shadowed = Vec::new();+ let mut seen = std::collections::HashSet::new();+ let mut packs = Vec::new();+ for pack in registry.packs {+ if pack.id.is_empty()+ || !pack.id.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')+ {+ return Err(format!(+ "pack id '{}' is invalid: ids are lowercase kebab-case ([a-z0-9-])",+ pack.id+ ));+ }+ if parse_format(&pack.format).is_none() {+ return Err(format!(+ "pack '{}' declares unknown format '{}' (expected turtle|rdfxml|ntriples|nquads|trig)",+ pack.id, pack.format+ ));+ }+ if !(pack.url.starts_with("https://") || pack.url.starts_with("http://")) {+ return Err(format!("pack '{}' url must be http(s): {}", pack.id, pack.url));+ }+ if find(&pack.id).is_some() {+ shadowed.push(pack.id);+ continue;+ }+ if !seen.insert(pack.id.clone()) {+ return Err(format!("duplicate pack id '{}' in registry", pack.id));+ }+ packs.push(pack);+ }+ Ok((packs, shadowed))+}+#[cfg(test)]mod tests {use super::*;@@ -372,4 +495,56 @@ mod tests {assert!(live.url.contains("IES-Org"), "live preset should point at IES-Org");assert!(frozen.url.contains("dstl/IES4"), "frozen preset should point at archived dstl/IES4");}++ #[test]+ fn community_registry_parses_and_validates() {+ let json = r#"{"version":1,"packs":[{+ "id":"pizza","name":"Pizza Ontology","description":"Teaching ontology",+ "domain":"teaching","url":"https://example.org/pizza.owl","format":"rdfxml",+ "maintainer":"someone","license":"CC-BY-4.0"}]}"#;+ let (packs, shadowed) = parse_community_registry(json).unwrap();+ assert_eq!(packs.len(), 1);+ assert!(shadowed.is_empty());+ assert_eq!(packs[0].id, "pizza");+ assert!(parse_format(&packs[0].format).is_some());+ }++ #[test]+ fn community_pack_shadowing_curated_id_is_dropped_and_reported() {+ // A community pack must never override a curated entry — `foaf` is curated.+ let json = r#"{"version":1,"packs":[{+ "id":"foaf","name":"Fake FOAF","description":"x",+ "domain":"people","url":"https://example.org/x.ttl","format":"turtle"}]}"#;+ let (packs, shadowed) = parse_community_registry(json).unwrap();+ assert!(packs.is_empty());+ assert_eq!(shadowed, vec!["foaf"]);+ }++ #[test]+ fn community_registry_rejects_bad_ids_formats_urls_and_dupes() {+ let bad_id = r#"{"version":1,"packs":[{"id":"Bad_ID","name":"x","description":"x","domain":"x","url":"https://e.org/x","format":"turtle"}]}"#;+ assert!(parse_community_registry(bad_id).is_err());+ let bad_format = r#"{"version":1,"packs":[{"id":"ok","name":"x","description":"x","domain":"x","url":"https://e.org/x","format":"jsonld"}]}"#;+ assert!(parse_community_registry(bad_format).is_err());+ let bad_url = r#"{"version":1,"packs":[{"id":"ok","name":"x","description":"x","domain":"x","url":"ftp://e.org/x","format":"turtle"}]}"#;+ assert!(parse_community_registry(bad_url).is_err());+ let dupe = r#"{"version":1,"packs":[+ {"id":"ok","name":"x","description":"x","domain":"x","url":"https://e.org/x","format":"turtle"},+ {"id":"ok","name":"y","description":"y","domain":"y","url":"https://e.org/y","format":"turtle"}]}"#;+ assert!(parse_community_registry(dupe).is_err());+ let bad_version = r#"{"version":2,"packs":[]}"#;+ assert!(parse_community_registry(bad_version).is_err());+ }++ #[test]+ fn shipped_community_registry_is_valid() {+ // The registry that ships in-tree (and is served from GitHub raw as the+ // default remote registry) must always parse — a broken merge here+ // would break every user's `onto_marketplace list`.+ let path = concat!(env!("CARGO_MANIFEST_DIR"), "/community/registry.json");+ let json = std::fs::read_to_string(path).expect("community/registry.json missing");+ let (packs, shadowed) = parse_community_registry(&json).expect("shipped registry invalid");+ assert!(shadowed.is_empty(), "shipped registry shadows curated ids: {shadowed:?}");+ assert!(!packs.is_empty(), "shipped registry should seed at least one pack");+ }}diff --git a/src/plugins.rs b/src/plugins.rsnew file mode 100644index 00000000..f487491b--- /dev/null+++ b/src/plugins.rs@@ -0,0 +1,215 @@+//! WASM plugin host — the in-process community extension surface.+//!+//! Plugins are `.wasm` modules (wasm32-unknown-unknown) discovered from the+//! plugin directories and executed in the wasmi interpreter with fuel+//! metering, so a misbehaving plugin runs out of fuel instead of hanging the+//! server. Plugins are pure JSON → JSON transforms: they import nothing from+//! the host, and any graph context they need (e.g. SPARQL results) is injected+//! into their input by the caller. That keeps the capability model explicit —+//! a plugin can compute over what it is handed, and nothing else.+//!+//! ## ABI v1+//!+//! A plugin exports:+//!+//! - `memory` — its linear memory+//! - `oo_abi_version() -> i32` — must return `1`+//! - `oo_alloc(len: i32) -> i32` — allocate `len` bytes, return the pointer+//! - `oo_describe() -> i64` — return `(ptr << 32) | len` of a UTF-8 JSON+//! manifest: `{"name", "version", "tools": [{"name", "description"}]}`+//! - `oo_call(ptr: i32, len: i32) -> i64` — input is UTF-8 JSON+//! `{"tool": ..., "input": ..., "bindings": [...]}`; returns packed ptr/len+//! of the UTF-8 JSON result+//!+//! See `examples/plugins/` for a Rust reference implementation.++use serde::Deserialize;+use std::path::{Path, PathBuf};+use wasmi::{Config, Engine, Instance, Linker, Module, Store};++/// ABI version this host speaks.+pub const ABI_VERSION: i32 = 1;++/// Fuel budget per plugin invocation. Interpreter instructions, not wall+/// clock; enough for validation-scale work, small enough to stop runaways.+const FUEL_PER_CALL: u64 = 500_000_000;++/// Hard cap on the byte length a plugin may return.+const MAX_RETURN_LEN: usize = 16 * 1024 * 1024;++#[derive(Debug, Clone, Deserialize)]+pub struct PluginToolDecl {+ pub name: String,+ pub description: String,+}++#[derive(Debug, Clone, Deserialize)]+pub struct PluginManifest {+ pub name: String,+ #[serde(default)]+ pub version: Option<String>,+ #[serde(default)]+ pub tools: Vec<PluginToolDecl>,+}++/// A discovered plugin: its file plus the manifest it reported.+#[derive(Debug, Clone)]+pub struct DiscoveredPlugin {+ pub path: PathBuf,+ pub manifest: PluginManifest,+}++/// Plugin search directories, in priority order:+/// 1. `OPEN_ONTOLOGIES_PLUGIN_DIRS` (colon-separated), if set — exclusively+/// 2. `~/.open-ontologies/plugins` and `./plugins`+pub fn plugin_dirs() -> Vec<PathBuf> {+ if let Ok(v) = std::env::var("OPEN_ONTOLOGIES_PLUGIN_DIRS")+ && !v.trim().is_empty() {+ return v.split(':').map(|p| PathBuf::from(crate::config::expand_tilde(p))).collect();+ }+ let mut dirs = Vec::new();+ if let Some(home) = std::env::var_os("HOME").or_else(|| std::env::var_os("USERPROFILE")) {+ dirs.push(Path::new(&home).join(".open-ontologies").join("plugins"));+ }+ dirs.push(PathBuf::from("plugins"));+ dirs+}++/// Enumerate `.wasm` files in the plugin directories and describe each.+/// A plugin that fails to load or describe is reported as an error string+/// rather than aborting discovery — one broken plugin must not hide the rest.+pub fn discover() -> (Vec<DiscoveredPlugin>, Vec<String>) {+ let mut plugins = Vec::new();+ let mut errors = Vec::new();+ for dir in plugin_dirs() {+ let Ok(entries) = std::fs::read_dir(&dir) else { continue };+ let mut paths: Vec<PathBuf> = entries+ .flatten()+ .map(|e| e.path())+ .filter(|p| p.extension().is_some_and(|ext| ext == "wasm"))+ .collect();+ paths.sort();+ for path in paths {+ match describe(&path) {+ Ok(manifest) => plugins.push(DiscoveredPlugin { path, manifest }),+ Err(e) => errors.push(format!("{}: {e}", path.display())),+ }+ }+ }+ (plugins, errors)+}++/// Find a discovered plugin by manifest name.+pub fn find(name: &str) -> Result<DiscoveredPlugin, String> {+ let (plugins, errors) = discover();+ plugins+ .into_iter()+ .find(|p| p.manifest.name == name)+ .ok_or_else(|| {+ let mut msg = format!("plugin '{name}' not found in {:?}", plugin_dirs());+ if !errors.is_empty() {+ msg.push_str(&format!("; broken plugins: {}", errors.join("; ")));+ }+ msg+ })+}++/// Load a plugin and return its manifest.+pub fn describe(path: &Path) -> Result<PluginManifest, String> {+ let mut runtime = PluginRuntime::load(path)?;+ let packed = runtime+ .typed_call::<(), i64>("oo_describe", ())+ .map_err(|e| format!("oo_describe failed: {e}"))?;+ let bytes = runtime.read_packed(packed)?;+ let manifest: PluginManifest = serde_json::from_slice(&bytes)+ .map_err(|e| format!("oo_describe returned invalid manifest JSON: {e}"))?;+ if manifest.name.is_empty() {+ return Err("manifest name is empty".to_string());+ }+ Ok(manifest)+}++/// Invoke a tool on a plugin. `payload` is the full input document the plugin+/// receives (`{"tool", "input", "bindings"}` — assembled by the caller).+/// Each call runs in a fresh instance: plugins are stateless by construction.+pub fn call(path: &Path, payload: &serde_json::Value) -> Result<serde_json::Value, String> {+ let mut runtime = PluginRuntime::load(path)?;+ let input = serde_json::to_vec(payload).map_err(|e| e.to_string())?;+ let ptr = runtime+ .typed_call::<i32, i32>("oo_alloc", input.len() as i32)+ .map_err(|e| format!("oo_alloc failed: {e}"))?;+ runtime+ .memory+ .write(&mut runtime.store, ptr as usize, &input)+ .map_err(|e| format!("input write failed: {e}"))?;+ let packed = runtime+ .typed_call::<(i32, i32), i64>("oo_call", (ptr, input.len() as i32))+ .map_err(|e| format!("oo_call failed (out of fuel or trapped): {e}"))?;+ let bytes = runtime.read_packed(packed)?;+ serde_json::from_slice(&bytes)+ .map_err(|e| format!("plugin returned invalid JSON: {e}"))+}++/// One loaded instance: engine, store (with fuel), instance, memory.+struct PluginRuntime {+ store: Store<()>,+ instance: Instance,+ memory: wasmi::Memory,+}++impl PluginRuntime {+ fn load(path: &Path) -> Result<Self, String> {+ let bytes = std::fs::read(path).map_err(|e| format!("read failed: {e}"))?;+ let mut config = Config::default();+ config.consume_fuel(true);+ let engine = Engine::new(&config);+ let module = Module::new(&engine, &bytes).map_err(|e| format!("invalid wasm: {e}"))?;+ let mut store = Store::new(&engine, ());+ store+ .set_fuel(FUEL_PER_CALL)+ .map_err(|e| format!("fuel setup failed: {e}"))?;+ // Empty linker: ABI v1 plugins import nothing from the host.+ let linker = <Linker<()>>::new(&engine);+ let instance = linker+ .instantiate_and_start(&mut store, &module)+ .map_err(|e| format!("instantiation failed (plugin imports host functions? ABI v1 allows none): {e}"))?;+ let abi = instance+ .get_typed_func::<(), i32>(&store, "oo_abi_version")+ .map_err(|_| "missing export oo_abi_version — not an Open Ontologies plugin".to_string())?+ .call(&mut store, ())+ .map_err(|e| format!("oo_abi_version trapped: {e}"))?;+ if abi != ABI_VERSION {+ return Err(format!("plugin speaks ABI v{abi}, host speaks v{ABI_VERSION}"));+ }+ let memory = instance+ .get_memory(&store, "memory")+ .ok_or_else(|| "plugin exports no `memory`".to_string())?;+ Ok(Self { store, instance, memory })+ }++ fn typed_call<P, R>(&mut self, name: &str, params: P) -> Result<R, String>+ where+ P: wasmi::WasmParams,+ R: wasmi::WasmResults,+ {+ self.instance+ .get_typed_func::<P, R>(&self.store, name)+ .map_err(|e| format!("missing/mistyped export {name}: {e}"))?+ .call(&mut self.store, params)+ .map_err(|e| e.to_string())+ }++ /// Unpack an `(ptr << 32) | len` return value and copy it out of guest memory.+ fn read_packed(&self, packed: i64) -> Result<Vec<u8>, String> {+ let ptr = (packed as u64 >> 32) as usize;+ let len = (packed as u64 & 0xFFFF_FFFF) as usize;+ if len > MAX_RETURN_LEN {+ return Err(format!("plugin returned {len} bytes, cap is {MAX_RETURN_LEN}"));+ }+ let mut buf = vec![0u8; len];+ self.memory+ .read(&self.store, ptr, &mut buf)+ .map_err(|e| format!("result read out of bounds: {e}"))?;+ Ok(buf)+ }+}diff --git a/src/server.rs b/src/server.rsindex 32821e03..d179c63b 100644--- a/src/server.rs+++ b/src/server.rs@@ -707,13 +707,13 @@ impl OpenOntologiesServer {// ── Marketplace ────────────────────────────────────────────────────────- #[tool(name = "onto_marketplace", description = "Browse and install standard ontologies from a curated catalogue of 33 W3C/ISO/industry standards. Actions: 'list' (browse catalogue, optional domain filter) or 'install' (fetch and load by ID)")]+ #[tool(name = "onto_marketplace", description = "Browse and install ontologies from the curated catalogue of 33 W3C/ISO/industry standards plus the open community-pack registry (community/registry.json, fetched at runtime; override with OPEN_ONTOLOGIES_COMMUNITY_REGISTRY). Actions: 'list' (browse both tiers, optional domain filter; community=false for curated only) or 'install' (fetch and load by ID — curated IDs win over community)")]async fn onto_marketplace(&self, Parameters(input): Parameters<OntoMarketplaceInput>) -> String {use crate::marketplace;match input.action.as_str() {"list" => {let entries = marketplace::list(input.domain.as_deref());- let items: Vec<serde_json::Value> = entries.iter().map(|e| {+ let mut items: Vec<serde_json::Value> = entries.iter().map(|e| {serde_json::json!({"id": e.id,"name": e.name,@@ -721,12 +721,46 @@ impl OpenOntologiesServer {"domain": e.domain,"url": e.url,"format": marketplace::format_name(e.format),+ "source": "curated",})}).collect();+ let mut community_error = None;+ let mut registry_source = None;+ if input.community.unwrap_or(true) {+ match marketplace::load_community_packs().await {+ Ok((packs, shadowed, source)) => {+ registry_source = Some(source);+ for p in packs.iter().filter(|p| {+ input.domain.as_deref().is_none_or(|d| p.domain == d)+ }) {+ items.push(serde_json::json!({+ "id": p.id,+ "name": p.name,+ "description": p.description,+ "domain": p.domain,+ "url": p.url,+ "format": p.format,+ "source": "community",+ "maintainer": p.maintainer,+ "license": p.license,+ }));+ }+ if !shadowed.is_empty() {+ community_error = Some(format!(+ "community packs shadowing curated ids were ignored: {}",+ shadowed.join(", ")+ ));+ }+ }+ Err(e) => community_error = Some(e),+ }+ }serde_json::json!({"ok": true,"count": items.len(),"ontologies": items,+ "community_registry": registry_source,+ "community_registry_error": community_error,}).to_string()}"install" => {@@ -734,43 +768,134 @@ impl OpenOntologiesServer {Some(id) => id,None => return r#"{"error":"'id' is required for install action"}"#.to_string(),};- let entry = match marketplace::find(id) {- Some(e) => e,- None => {- let available: Vec<&str> = marketplace::CATALOGUE.iter().map(|e| e.id).collect();- return serde_json::json!({- "error": format!("Unknown ontology ID: '{}'. Use action 'list' to see available IDs.", id),- "available": available,- }).to_string();- }+ // Curated first; community packs can never shadow a curated ID.+ let (name, url, format, tier, license) = match marketplace::find(id) {+ Some(e) => (e.name.to_string(), e.url.to_string(), e.format, "curated", None),+ None => match marketplace::load_community_packs().await {+ Ok((packs, _, _)) => match packs.into_iter().find(|p| p.id == id) {+ Some(p) => {+ let format = match marketplace::parse_format(&p.format) {+ Some(f) => f,+ None => return serde_json::json!({+ "error": format!("community pack '{}' has invalid format '{}'", id, p.format),+ }).to_string(),+ };+ (p.name, p.url, format, "community", p.license)+ }+ None => {+ let available: Vec<&str> = marketplace::CATALOGUE.iter().map(|e| e.id).collect();+ return serde_json::json!({+ "error": format!("Unknown ontology ID: '{}'. Use action 'list' to see curated and community IDs.", id),+ "available_curated": available,+ }).to_string();+ }+ },+ Err(e) => {+ let available: Vec<&str> = marketplace::CATALOGUE.iter().map(|e| e.id).collect();+ return serde_json::json!({+ "error": format!("'{}' is not a curated ID and the community registry could not be loaded: {}", id, e),+ "available_curated": available,+ }).to_string();+ }+ },};- match crate::graph::GraphStore::fetch_url(entry.url).await {+ match crate::graph::GraphStore::fetch_url(&url).await {Ok(content) => {- match self.graph.load_content_with_base(&content, entry.format, Some(entry.url)) {+ match self.graph.load_content_with_base(&content, format, Some(&url)) {Ok(count) => {let stats = self.graph.get_stats().unwrap_or_default();let stats_val: serde_json::Value = serde_json::from_str(&stats).unwrap_or_default();serde_json::json!({"ok": true,- "installed": entry.id,- "name": entry.name,+ "installed": id,+ "name": name,+ "tier": tier,+ "license": license,"triples_loaded": count,- "source": entry.url,+ "source": url,"classes": stats_val["classes"],"properties": stats_val["properties"],"individuals": stats_val["individuals"],}).to_string()}- Err(e) => format!(r#"{{"error":"Parse error for {}: {}"}}"#, entry.id, e),+ Err(e) => format!(r#"{{"error":"Parse error for {}: {}"}}"#, id, e),}}- Err(e) => format!(r#"{{"error":"Fetch error for {}: {}"}}"#, entry.id, e),+ Err(e) => format!(r#"{{"error":"Fetch error for {}: {}"}}"#, id, e),}}other => format!(r#"{{"error":"Unknown action '{}'. Use 'list' or 'install'."}}"#, other),}}+ // ── WASM plugins ───────────────────────────────────────────────────────++ #[tool(name = "onto_plugin_list", description = "Discover installed WASM plugins and the tools they provide. Plugins are community .wasm modules in ~/.open-ontologies/plugins or ./plugins (override with OPEN_ONTOLOGIES_PLUGIN_DIRS), run in-process with fuel metering. Requires a build with --features plugins.")]+ fn onto_plugin_list(&self) -> String {+ #[cfg(not(feature = "plugins"))]+ { r#"{"error":"Compiled without plugins feature. Rebuild with --features plugins"}"#.to_string() }+ #[cfg(feature = "plugins")]+ {+ let (plugins, errors) = crate::plugins::discover();+ let items: Vec<serde_json::Value> = plugins.iter().map(|p| {+ serde_json::json!({+ "name": p.manifest.name,+ "version": p.manifest.version,+ "path": p.path.display().to_string(),+ "tools": p.manifest.tools.iter().map(|t| serde_json::json!({+ "name": t.name,+ "description": t.description,+ })).collect::<Vec<_>>(),+ })+ }).collect();+ serde_json::json!({+ "ok": true,+ "count": items.len(),+ "plugins": items,+ "search_dirs": crate::plugins::plugin_dirs().iter().map(|d| d.display().to_string()).collect::<Vec<_>>(),+ "broken": errors,+ }).to_string()+ }+ }++ #[tool(name = "onto_plugin_call", description = "Invoke a tool on an installed WASM plugin. Plugins are pure JSON->JSON transforms with no direct store access; pass 'sparql' to run a SELECT against the loaded store and inject its result rows into the plugin input as 'bindings'. Requires a build with --features plugins.")]+ async fn onto_plugin_call(&self, Parameters(input): Parameters<OntoPluginCallInput>) -> String {+ #[cfg(not(feature = "plugins"))]+ { let _ = input; return r#"{"error":"Compiled without plugins feature. Rebuild with --features plugins"}"#.to_string(); }+ #[cfg(feature = "plugins")]+ {+ let plugin = match crate::plugins::find(&input.plugin) {+ Ok(p) => p,+ Err(e) => return serde_json::json!({"error": e}).to_string(),+ };+ let mut payload = serde_json::json!({+ "tool": input.tool,+ "input": input.input.unwrap_or(serde_json::Value::Null),+ });+ if let Some(sparql) = input.sparql.as_deref() {+ if let Err(e) = self.registry.ensure_loaded() {+ return format!(r#"{{"error":"ensure_loaded: {}"}}"#, e.to_string().replace('"', "'"));+ }+ match self.graph.sparql_select(sparql) {+ Ok(json) => {+ let parsed: serde_json::Value = serde_json::from_str(&json).unwrap_or_default();+ payload["bindings"] = parsed.get("results").cloned().unwrap_or(serde_json::Value::Null);+ }+ Err(e) => return serde_json::json!({"error": format!("sparql failed: {e}")}).to_string(),+ }+ }+ match crate::plugins::call(&plugin.path, &payload) {+ Ok(result) => serde_json::json!({+ "ok": true,+ "plugin": plugin.manifest.name,+ "tool": input.tool,+ "result": result,+ }).to_string(),+ Err(e) => serde_json::json!({"error": e, "plugin": plugin.manifest.name}).to_string(),+ }+ }+ }+#[tool(name = "onto_version", description = "Save a named snapshot of the current ontology store")]async fn onto_version(&self, Parameters(input): Parameters<OntoVersionInput>) -> String {use crate::ontology::OntologyService;diff --git a/tests/plugin_host_test.rs b/tests/plugin_host_test.rsnew file mode 100644index 00000000..ae0ba5d2--- /dev/null+++ b/tests/plugin_host_test.rs@@ -0,0 +1,124 @@+//! WASM plugin host integration tests (ABI v1).+//!+//! Plugins here are assembled from WAT at test time so the suite needs no+//! wasm32 toolchain — the same ABI a real (Rust-compiled) plugin speaks.+#![cfg(feature = "plugins")]++use open_ontologies::plugins;+use std::path::PathBuf;++const MANIFEST: &str = r#"{"name":"echo","version":"0.1.0","tools":[{"name":"echo","description":"Returns its input document verbatim"}]}"#;++/// A well-behaved ABI v1 plugin: `oo_describe` serves the manifest from a data+/// segment at offset 0; `oo_alloc` hands out a fixed input buffer; `oo_call`+/// echoes the input region back (valid, since the host always sends JSON).+fn echo_plugin_wat() -> String {+ let escaped = MANIFEST.replace('\\', "\\\\").replace('"', "\\\"");+ format!(+ r#"(module+ (memory (export "memory") 2)+ (data (i32.const 0) "{escaped}")+ (func (export "oo_abi_version") (result i32) (i32.const 1))+ (func (export "oo_alloc") (param i32) (result i32) (i32.const 4096))+ (func (export "oo_describe") (result i64) (i64.const {len}))+ (func (export "oo_call") (param $ptr i32) (param $len i32) (result i64)+ (i64.or+ (i64.shl (i64.extend_i32_u (local.get $ptr)) (i64.const 32))+ (i64.extend_i32_u (local.get $len)))))"#,+ len = MANIFEST.len(),+ )+}++fn write_wasm(dir: &tempfile::TempDir, name: &str, wat: &str) -> PathBuf {+ let path = dir.path().join(name);+ std::fs::write(&path, wat::parse_str(wat).expect("WAT should assemble")).unwrap();+ path+}++#[test]+fn describe_reads_manifest_over_abi_v1() {+ let dir = tempfile::tempdir().unwrap();+ let path = write_wasm(&dir, "echo.wasm", &echo_plugin_wat());+ let manifest = plugins::describe(&path).expect("describe should succeed");+ assert_eq!(manifest.name, "echo");+ assert_eq!(manifest.version.as_deref(), Some("0.1.0"));+ assert_eq!(manifest.tools.len(), 1);+ assert_eq!(manifest.tools[0].name, "echo");+}++#[test]+fn call_round_trips_payload_through_guest_memory() {+ let dir = tempfile::tempdir().unwrap();+ let path = write_wasm(&dir, "echo.wasm", &echo_plugin_wat());+ let payload = serde_json::json!({+ "tool": "echo",+ "input": {"answer": 42},+ "bindings": [{"class": "<http://example.org/A>", "label": "A"}],+ });+ let result = plugins::call(&path, &payload).expect("call should succeed");+ assert_eq!(result, payload, "echo plugin must return its input verbatim");+}++#[test]+fn non_plugin_wasm_is_rejected_with_missing_export() {+ let dir = tempfile::tempdir().unwrap();+ let path = write_wasm(&dir, "empty.wasm", "(module)");+ let err = plugins::describe(&path).unwrap_err();+ assert!(err.contains("oo_abi_version"), "unexpected error: {err}");+}++#[test]+fn abi_version_mismatch_is_rejected() {+ let dir = tempfile::tempdir().unwrap();+ let wat = r#"(module+ (memory (export "memory") 1)+ (func (export "oo_abi_version") (result i32) (i32.const 99)))"#;+ let path = write_wasm(&dir, "future.wasm", wat);+ let err = plugins::describe(&path).unwrap_err();+ assert!(err.contains("ABI"), "unexpected error: {err}");+}++#[test]+fn runaway_plugin_is_stopped_by_fuel_not_by_hanging() {+ // An infinite loop in oo_call must trap on fuel exhaustion. If fuel+ // metering regresses this test hangs instead of failing — that IS the+ // signal (the sandbox guarantee is gone).+ let dir = tempfile::tempdir().unwrap();+ let escaped = MANIFEST.replace('\\', "\\\\").replace('"', "\\\"");+ let wat = format!(+ r#"(module+ (memory (export "memory") 2)+ (data (i32.const 0) "{escaped}")+ (func (export "oo_abi_version") (result i32) (i32.const 1))+ (func (export "oo_alloc") (param i32) (result i32) (i32.const 4096))+ (func (export "oo_describe") (result i64) (i64.const {len}))+ (func (export "oo_call") (param i32) (param i32) (result i64)+ (loop $spin (br $spin))+ (i64.const 0)))"#,+ len = MANIFEST.len(),+ );+ let path = write_wasm(&dir, "spin.wasm", &wat);+ let err = plugins::call(&path, &serde_json::json!({"tool": "x", "input": null})).unwrap_err();+ assert!(err.contains("oo_call failed"), "unexpected error: {err}");+}++#[test]+fn oversized_return_is_capped() {+ // A plugin claiming a 4GiB-ish result length must be refused, not allocated.+ let escaped = MANIFEST.replace('\\', "\\\\").replace('"', "\\\"");+ let wat = format!(+ r#"(module+ (memory (export "memory") 2)+ (data (i32.const 0) "{escaped}")+ (func (export "oo_abi_version") (result i32) (i32.const 1))+ (func (export "oo_alloc") (param i32) (result i32) (i32.const 4096))+ (func (export "oo_describe") (result i64) (i64.const {len}))+ (func (export "oo_call") (param i32) (param i32) (result i64)+ (i64.const 0xFFFFFFFF)))"#,+ len = MANIFEST.len(),+ );+ let dir = tempfile::tempdir().unwrap();+ let path = write_wasm(&dir, "huge.wasm", &wat);+ let err = plugins::call(&path, &serde_json::json!({"tool": "x", "input": null})).unwrap_err();+ assert!(err.contains("cap"), "unexpected error: {err}");+}