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):

1. 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.
2. 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.
3. 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, or mercury-agent-loop for llm.run, the agent loop that runs model turns through a language pack's llm.chat and calls a route for each tool.)

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 v1.12.8–v3.0.19 remain available as tagged releases 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.