04 — Ecosystem¶

Concentric rings from kernel outward. What exists today vs. what needs to be built vs. what the ecosystem absorbs from external projects. Everything on this map rides the single ADR-0021 progressive surface: capabilities, node types, shapes, and OWL are rungs of one ladder, not separate product lines.

Ring 0 — Kernel & framework (we build)¶

Rust kernel (7 active crates + 5 archived)              Python surface (`trails` package)
+-- trails-graph                     +-- @capability  @node_type  @shape  @policy
+-- trails-shapes                    +-- @before @after @on_error @around
+-- trails-reason                    +-- @resource  @prompt
+-- trails-policy                    +-- orm  kg  shapes  policy
+-- trails-prov                      +-- llm  agent  ingest  vector
+-- trails-caps                      +-- testing  observability  rendering
+-- trails-identity                  +-- mcp_server  http_adapter
+-- trails-cost                      +-- cli (trails new / g / server / kg / ...)
+-- trails-adapters-fuseki           +-- _core (PyO3 abi3-py311)
+-- trails-adapters-qlever
+-- trails-ffi
+-- trails-wasm                      (`trails-wasm` fronts the embedded
                                      OxigraphStore for browser / edge;
                                      CLI + transports are Python-only)

Ring 1 — Runtime companions (we build, thin)¶

Ring 2 — Backends & adapters (swappable)¶

Each is a Rust trait impl (kernel layer) or a Python adapter (surface layer) selected by a trails.toml config key. Rust backends live in trails-adapters-*; Python adapters live as sub-modules under trails.llm, trails.vector, and trails.ingest.

Ring 3 — Registries (we host)¶

This ring makes Trails an ecosystem, not just a framework.

Every registry item: canonical IRI, SemVer, provenance chain to authorship DID.

trails add @trails-community/fhir-r5 — pulls ontology + shapes + example handlers + Cedar policy starter.

Locally, trails registry publish|search|list|show|remove already lands — the hosted trails.dev mirror is the next axis.

Ring 4 — Dev tooling (we build)¶

Ring 5 — Observability & trust (we build)¶

New category — doesn't really exist in Rails-land because Web 2.0 doesn't need it.

trails.observability ships the event hook and Span / tracer / metrics primitives (OTel-friendly) that feed all of the above.

Cost + provenance + consent are table stakes for agentic apps in regulated industries. Bundling them as framework defaults is the core design choice.

Ring 6 — Agent-side integration (we partner)¶

Trails exposes capabilities; something consumes them. This is the distribution surface.

The Trails MCP server implements the full MCP 2024-11-05 surface — not just Tools. @resource projects read-only graph views under resources/list + resources/read (with resources/subscribe emitting list_changed notifications on writes), and @prompt projects parameterised prompt templates under prompts/list + prompts/get. An MCP client that speaks Resources gets graph-snapshot reads "for free" without Trails inventing a new protocol.

An agent-orchestration framework is the killer reference app. Multi-agent orchestration on top of Trails' capability layer = the full story. Orchestration archetypes become capability consumers; Trails handles plumbing (shapes, policy, provenance, cost) they all need anyway.

A compliance ontology service is the killer regulated-industry reference app. A compliance ontology (EU AI Act / MDR / ISO 14971/42001 / IEC 62304) plus a FastAPI service maps cleanly onto Trails capabilities; its Apache Jena Fuseki backend validates the trails-adapters-fuseki crate; PROV-O / ECT provenance chains become Article 12 audit evidence by default.

Ring 7 — Identity & trust fabric (we absorb, not rebuild)¶

Trails ships ACT as the default capability mandate (standards-track, replay-protected, assurance-level aware) and supports biscuit as an attenuation layer under a parent ACT (cheap to verify, offline-capable — good for agent chains).

Ring 8 — Hosting & deployment¶

Ring 9 — Docs, learning, community¶

What already exists — use, don't rebuild¶

• Oxigraph, Qlever, Fuseki — triple stores. Adapt all three, don't write a fourth.
• Cedar — policy engine.
• MCP, A2A, ACP — agent protocols. Speak them; don't invent one.
• biscuit-auth, SD-JWT, JOSE (python-jose / jwcrypto) — tokens.
• schema.org, PROV-O, SOSA, SKOS, FOAF — vocabularies. Import; don't redesign.
• pyshacl, rdflib, pyoxigraph, pyld — Python RDF plumbing; wrap; don't reimplement.
• pypdf, trafilatura, markdown-it-py — ingestion extractors for PDF / HTML / Markdown. Already wired via trails.ingest.
• sqlite-vec, qdrant-client, sentence-transformers — vector store + embeddings. Already wired via trails.vector.
• FastAPI, Jinja2, click, uvicorn, watchdog — surface deps (HTTP, templating, CLI, hot reload).
• anthropic, openai, ollama — LLM SDKs via the shared LLMClient adapter under trails.llm.
• LangGraph, CrewAI — Trails feeds them; doesn't compete.

Optional install extras (pyproject)¶

The core pip install trails pulls in only click, aiohttp, jinja2, pydantic, rdflib, pyoxigraph, and pyld. Everything else is an extras group that activates a feature lazily:

qdrant-client is an additional opt-in for trails.vector when you want a remote Qdrant instead of the embedded SqliteVec path. Each module imports its backend lazily and raises a helpful TrailsError with an install hint when the relevant SDK is missing.

Business-model optionality¶

Not required for v1, but design in now so nothing is foreclosed:

1. Open-core: framework Apache-2.0; managed hosting paid.
2. Consent/provenance-as-a-service: neutral third-party ledger. Regulated industries pay.
3. Certified policy packs: HIPAA, GDPR, EU AI Act, maintained and indemnified.
4. Capability marketplace revenue share: trails.dev/capabilities à la HashiCorp Terraform Registry.

The defensible one is consent/provenance ledger as SaaS — neutral infrastructure every serious agent deployment needs, nobody wants to self-host an audit log that could be subpoenaed.

Ecosystem thesis in one sentence¶

Rails unified CRUD-over-HTTP; Trails unifies capability-over-MCP with shapes, provenance, consent, and cost as first-class primitives — on one progressive surface, opt-in feature by opt-in feature — and the ecosystem around it exists because every serious agent deployment in 2027 will need those same primitives whether they know it yet or not.

The question isn't is there demand — it's who ships the conventions first.

Ecosystem dependency graph¶

                     +------------------+
                     | trails-core      |
                     | (Rust kernel,    |
                     |  7 active crates + 5 archived)      |
                     +--------+---------+
                              |
                  +-----------+-------------+
                  |                         |
         +--------v--------+       +--------v--------+
         | trails (Python) |       | trails-wasm     |
         +--------+--------+       | (OxigraphStore) |
                  |                +--------+--------+
    +-------------+-------------+           |
    |             |             |           |
+---v--+   +------v-----+  +----v-----+  +--v--------+
| CLI  |   | MCP server |  | FastAPI  |  | Edge apps |
| (click|  | (Tools +   |  | HTTP     |  | / browser |
|  trails| | Resources +|  | adapter  |  +-----------+
|   new) | | Prompts)   |  +----------+
+-------+  +------------+
                  |
    +-------------+-------------------------+
    |             |                         |
+---v--------+ +--v--------------+   +------v------------+
| Registries | | Companion tools |   | Managed services  |
| (ontology, | | (sim, trace,    |   | (trails.cloud,    |
|  caps,     | |  doctor, LSP)   |   |  consent ledger)  |
|  policies) | |                 |   |                   |
+------------+ +-----------------+   +-------------------+