mercury
A Rust port of mercury-composable —
Accenture's event-driven, composable application platform (the Java engine is the canonical
reference; both engines release in lock-step at the same version), carrying the same vision: build applications from small, fully-decoupled functions
wired by route name, orchestrated as configuration, and modeled as an executable knowledge
graph.
Status: all three layers ported and milestone-closed across 96 verified increments;
full workspace test suite, clippy and fmt clean; benchmarked (RPC ~155K ops/s @ 6µs).
The AI-agent documentation is battle-tested — twelve consecutive fresh-agent exercises
passed with zero documentation lookups, across both engines. See
CHANGELOG.md and docs/INCREMENTS.md.
The three paradigm layers
Each layer builds on the one below (foundation → UI):
- platform-core — the actor-model event bus: route-addressed functions coupled only by
route name + an immutable
EventEnvelope, over a tokio async runtime. Plus the operable
runtime: REST automation (rest.yaml is the router, on hyper), actuators, tracing +
correlation-id, an async HTTP client, and a WebSocket server.
- event-script — composable orchestration: a YAML flow DSL that choreographs functions
into transactions (sequential / decision / parallel + fork-join / pipelines / sub-flows),
with data mapping, resilience, and an HTTP flow adapter. No orchestration in code.
- active knowledge graph — the semantic layer: MiniGraph property graphs whose nodes
carry executable skills, so traversing the graph is running the application — with
the browser-based MiniGraph Playground for building, running and inspecting graphs.
Use from crates.io
The seven library crates publish under mercury-prefixed package names, while the lib
(code-facing) names stay short — Cargo.toml and code look like:
[dependencies]
mercury-platform-core = "4.12" # code: use platform_core::...
mercury-event-script = "4.12" # code: use event_script::...
mercury-knowledge-graph = "4.12" # code: use knowledge_graph::...
(Declare the crates your code names plus the engine crate of your top layer — a Layer 3
application needs only mercury-platform-core and mercury-knowledge-graph, which brings
mercury-event-script along transitively. The macro crates are pulled in automatically; add mercury-minigraph-state-redis for
the Redis suspend/resume state store, mercury-distributed-cache for the opt-in Redis L2
cache (v1.cache.redis), mercury-sync-over-async for the cross-pod streaming return
route — the last two share the mercury-redis-connection client foundation — or
mercury-opentelemetry-forwarder to export the engine's distributed traces over OTLP/HTTP,
off until otel.forwarding=true.)
Quick start
Rust (stable) + Cargo. Run any example:
cargo run -p hello-world # layer 1 — event bus + HTTP
cargo run -p hello-flow # layer 2 — a YAML flow over HTTP (port 8100)
cargo run -p minigraph-playground # layer 3 — the Playground; open http://127.0.0.1:8085/
Verify the workspace:
cargo test --workspace
cargo clippy --workspace --all-targets
cargo fmt --all --check
cargo audit # RustSec advisories against Cargo.lock (cargo install cargo-audit --locked)
Repository layout
| Path | What |
|---|
crates/platform-core | layer 1 — event bus, runtime, REST/WebSocket automation |
crates/event-script | layer 2 — the composable-flow engine |
crates/knowledge-graph | layer 3 — MiniGraph engine; serves the Playground bundle and help pages deployed from the Java repo's webapp (npm run release:rust there) |
crates/*-macros | annotation macros (#[preload], #[websocket_service], …) |
examples/ | runnable example apps, one per layer |
extensions/api-playground | the API playground - Swagger UI in a Mercury page that loads a graph's OpenAPI document from a MiniGraph application (twin of the Java module) |
docs/INCREMENTS.md | the increment-by-increment port ledger |
draft-design-specs/ | per-layer design docs (the why behind the port) |
docs/arch-decisions/ADR.md | the durable architecture decisions |
memory/ | the shared cross-session AI-memory layer |
Documentation
The human developer guide is a 20-page MkDocs site under docs/ (Getting Started,
per-layer guides, references, port scope) — published at
https://accenture.github.io/mercury/, or build it locally with mkdocs serve.
AI agents start at
docs/llms.txt: the machine-readable map of the AI-agent documentation
that the fresh-agent validation sweep was driven from.
Non-goals
The Kafka service mesh (service discovery + sync-over-Kafka, the connectors/ tree) and
Spring (rest-spring-3/-4) are out of scope. The lightweight cloud-native connectors are not part
of that exclusion: minimalist-kafka is ported (crates/minimalist-kafka, crate
mercury-minimalist-kafka — the Kafka flow adapter, simple.kafka.notification, kafka.health
and the Confluent Schema Registry wire format; see
docs/guides/minimalist-kafka.md), as are sync-over-async
(extensions/sync-over-async) and the OpenTelemetry forwarder (extensions/opentelemetry-forwarder); twin-kafka (the second-cluster bridge) is deferred until a bridge
need exists (see docs/background/port-scope.md). graph.js is
deliberately retired in this port (an arbitrary-code interpreter is an attack surface); graph.math
and graph.task cover its use cases.
Legacy versions
This repository previously hosted the original Java implementation of Mercury (up to
v3.0.19); it was repurposed as the home of the Rust version on 2026-07-20. Versions 1.13.0
and 2.1.0–2.7.0 remain available as release branches in this repository. All known field
installations have been upgraded to version 4.x using the
mercury-composable repo — the canonical
Java implementation this port follows.
Contributing & license
See CONTRIBUTING.md and CODE_OF_CONDUCT.md.
Licensed under the Apache License 2.0.
