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 JPMS, 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://codeberg.org/Vidocq/heisenberg

Java

25 (LTS)

JPMS modules

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

Public packages

io.vidocq.heisenberg.api. (stable SPI), io.vidocq.heisenberg.cdi. (CDI integration)

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 — ReentrantLock, Semaphore, LongAdder, ConcurrentHashMap and ScopedValue are preferred.
Ravel config + Vauban BCE — all fault-tolerance/… keys are resolved through Ravel (MicroProfile Config 3.1); the single interceptor is registered by a Vauban Build Compatible Extension that scans and indexes annotations at startup.

Position in the ecosystem

flowchart LR
  App["Application CDI bean<br/>annotated method"]
  Interceptor["FaultToleranceInterceptor<br/>(heisenberg-cdi-vauban)"]
  Fallback["@Fallback"]
  CB["@CircuitBreaker"]
  Retry["@Retry"]
  Timeout["@Timeout"]
  Bulkhead["@Bulkhead"]
  Async["@Asynchronous"]
  Method["target method"]

  App --> Interceptor
  Interceptor --> Fallback
  Fallback --> CB
  CB --> Retry
  Retry --> Timeout
  Timeout --> Bulkhead
  Bulkhead --> Async
  Async --> Method

  Interceptor -.config.-> Ravel["Ravel<br/>MicroProfile Config"]
  Interceptor -.BCE.-> Vauban["Vauban<br/>CDI Lite"]
  Interceptor -.opt. metrics.-> Humboldt["Humboldt<br/>OpenTelemetry"]

  classDef rt fill:#e1f5fe,stroke:#0288d1
  class Interceptor rt

The chain wrapping order follows MP FT 4.1 spec §2.5 — @Fallback is the outermost wrapper, the target method is at the core. 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, JPMS modules, annotations, fault-tolerance/* keys.
Internals — pure engines, StateRegistry, 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.