Heisenberg · Vidocq

Heisenberg is the MicroProfile Fault Tolerance 4.1 implementation of the Vidocq ecosystem. It applies the @Retry, @Timeout, @CircuitBreaker, @Bulkhead, @Fallback and @Asynchronous policies to CDI beans through a single interceptor, wired into Vauban for the container and Ravel for configuration. Goal: 100% conformance to the MicroProfile Fault Tolerance 4.1 TCK (currently 463/463), zero external dependency beyond the specs, strict Java Modules, jlink-ready.

Origin of the name

Werner Heisenberg (1901-1976), German physicist. In 1927 he formulated the uncertainty principle, cornerstone of quantum mechanics: a particle’s position and momentum cannot be simultaneously measured with arbitrary precision — Δp · Δx ≥ ℏ/2. Nobel Prize in Physics 1932 "for the creation of quantum mechanics". See Wikipedia.

Heisenberg established that uncertainty is intrinsic, not a flaw of the instrument. The Heisenberg runtime encapsulates the uncertainty inherent in network calls and remote services — variable latency, transient failures, overload — and responds with formally composable policies, ordered like non-commutative operators.

Heisenberg, the physicist Heisenberg, the runtime

Heisenberg, the physicist	Heisenberg, the runtime
Uncertainty principle	The network call is intrinsically uncertain — success is not predetermined.
Non-commutative observable matrices	Non-commutative policies: `@Retry ∘ @Timeout ≠ @Timeout ∘ @Retry`.
Matrix mechanics (Göttingen, 1925)	Formal composition of aspects — interceptor chain ordered by spec §2.5.
Inequality `Δp · Δx ≥ ℏ/2`	Intrinsic latency × throughput bound (Little’s Law) — a `@Bulkhead` makes it explicit.
Wave packet collapse	`@CircuitBreaker` opens — state becomes discrete (OPEN), subsequent calls are short-circuited.
Eigenstates and compatible observables	Compatible policies, composable in a single canonical order.

Uncertainty principle

The network call is intrinsically uncertain — success is not predetermined.

Non-commutative observable matrices

Non-commutative policies: @Retry ∘ @Timeout ≠ @Timeout ∘ @Retry.

Matrix mechanics (Göttingen, 1925)

Formal composition of aspects — interceptor chain ordered by spec §2.5.

Inequality Δp · Δx ≥ ℏ/2

Intrinsic latency × throughput bound (Little’s Law) — a @Bulkhead makes it explicit.

Wave packet collapse

@CircuitBreaker opens — state becomes discrete (OPEN), subsequent calls are short-circuited.

Eigenstates and compatible observables

Compatible policies, composable in a single canonical order.

At a glance

Implemented spec

MicroProfile Fault Tolerance 4.1

Repository

https://codefloe.com/Vidocq/heisenberg

Java

25 (LTS)

Java modules

io.vidocq.heisenberg.api, io.vidocq.heisenberg.core, io.vidocq.heisenberg.cdi.vauban

Public packages

io.vidocq.heisenberg.api (stable SPI: FtMetricsRecorder, FaultToleranceException). The CDI module exports io.vidocq.heisenberg.cdi.internal so the container can invoke the interceptor without opens — internal by contract, not application API.

Runtime dependencies

microprofile-fault-tolerance-api 4.1, jakarta.enterprise.cdi-api 4.1 (provided), jakarta.interceptor-api 2.2 (provided), ravel-mp-config-api (MicroProfile Config 3.1), opentelemetry-api 1.39 (requires static)

jlink-ready

✅ — every sub-module has its module-info.java, no Automatic-Module-Name fallback in production.

MP FT 4.1 TCK

✅ 463 / 463 — see detailed status

Three identity traits

Zero third-party implementation library — only the specified Jakarta EE and MicroProfile APIs are compiled. No SmallRye Fault Tolerance, no Hystrix, no Resilience4j. The automata (retry, circuit breaker, bulkhead) are hand-written in heisenberg-core.
Native virtual threads for @Asynchronous and @Timeout — Thread.ofVirtual() + join(Duration) bound each attempt; no platform thread pool is created. No synchronized, no ThreadLocal in the policy engines — fair Semaphore, ConcurrentHashMap, atomics (AtomicInteger, AtomicReference, AtomicBoolean) and volatile snapshots instead.
Ravel config + Vauban BCE — all MP FT config keys (<FQCN>/<method>/<Annotation>/<param>, MP_Fault_Tolerance_NonFallback_Enabled, mp.fault.tolerance.interceptor.priority, …) are resolved through Ravel (MicroProfile Config 3.1); the interceptor binding is added by a Vauban Build Compatible Extension that scans annotated classes at startup.

Position in the ecosystem

The chain wrapping order follows MP FT 4.1 spec §2.5 — @Fallback is the outermost policy and the target method is at the core; @Asynchronous, when present, wraps the whole chain in a virtual thread. Cassini and any application HTTP client benefit from fault tolerance without code change. Humboldt (OpenTelemetry) and the Dirac MP Metrics implementation can collect the §9 and §10 metrics; the run-tck-no-observability.sh script disables them to validate that tolerance works with zero observability dependency on the classpath.

Quick links

Getting started — first guarded method, first @Retry + @CircuitBreaker + @Fallback chain.
Concepts — annotations, composition order, circuit breaker states.
Usage — robust REST clients, @Asynchronous, FallbackHandler, MP Config overrides.
Reference — artifacts, Java modules, annotations, MicroProfile Config keys.
Internals — pure engines, shared state registries, virtual threads.
TCK — execution, status, no-observability mode.
Migration — from SmallRye Fault Tolerance or Resilience4j.

Consolidated bugs and benchmarks: BUG.md, BENCH.md.

Next: Getting started.