Phased Approach: Generate Java Library Artifact for flagd-evaluator WASM (with later compile-time optimization)

[aepfli]

Summary

Create a standalone Java library artifact from flagd-evaluator that bundles the WASM runtime and module, enabling easier consumption and testing. This sets the foundation for future compile-time WASM-to-Java optimization.

Context

Currently, the Java integration of flagd-evaluator requires:

• Manually copying flagd_evaluator.wasm into consuming projects
• Implementing WASM runtime setup (Chicory configuration, host functions)
• Maintaining duplicate WASM loading and initialization code

This proposal aims to package everything into a single, reusable Java artifact.

---

Short-Term Goal: Java Library Artifact

Objectives

Create a Java library (flagd-evaluator-java) that:

• Bundles the WASM module as a classpath resource
• Provides runtime implementation with all required host functions
• Exposes a clean Java API for flag evaluation
• Manages Chicory runtime (compilation, instance lifecycle)
• Is testable within flagd-evaluator to ensure compatibility

Architecture

flagd-evaluator-java/
├── src/main/java/
│   └── dev/openfeature/flagd/evaluator/
│       ├── FlagEvaluator.java           # Main API
│       ├── runtime/
│       │   ├── WasmRuntime.java         # Chicory setup
│       │   └── HostFunctions.java       # Host function implementations
│       └── model/
│           └── EvaluationResult.java    # Result types
└── src/main/resources/
    └── flagd_evaluator.wasm             # Bundled WASM module

Benefits

• ✅ Single dependency: implementation 'dev.openfeature:flagd-evaluator-java:1.0.0'
• ✅ Version synchronization: WASM module version matches Java library version
• ✅ Consistent behavior: All consumers use the same WASM runtime setup
• ✅ Easier testing: Can validate WASM + Chicory integration in CI
• ✅ Better developer experience: No manual WASM file management

Implementation Tasks

• Create new Gradle/Maven module flagd-evaluator-java in flagd-evaluator repo
• Implement FlagEvaluator API wrapping WASM calls
• Extract and package WASM runtime setup from java-sdk-contrib#1672
• Bundle flagd_evaluator.wasm as classpath resource
• Add integration tests using Chicory
• Publish to Maven Central
• Update java-sdk-contrib to consume the artifact

Acceptance Criteria

• Java library builds successfully in flagd-evaluator CI
• Integration tests validate evaluation correctness
• Library works with Chicory interpreter and JIT compiler
• java-sdk-contrib can replace manual WASM integration with library dependency
• Documentation covers usage and migration path

---

Long-Term Goal: Compile-Time WASM → Java

Objectives

Optimize runtime performance by converting WASM to native Java bytecode at build time.

Approach

Leverage Chicory's AOT compilation (currently in development):

• Use Chicory's WASM → Java compiler to generate Java source/bytecode at build time
• Package the compiled Java code instead of (or alongside) the WASM module
• Eliminate WASM interpretation/JIT overhead
• Enable JVM optimizations (inlining, escape analysis, etc.)

Benefits

• ⚡ Better performance: Native Java bytecode instead of WASM interpretation
• 📦 Smaller artifacts: No WASM runtime needed if using compiled code
• 🔍 Better observability: Java stack traces instead of WASM stack traces
• 🚀 JVM optimizations: Full JIT compiler benefits

Considerations

• Chicory AOT is still experimental (track progress: dylibso/chicory#589)
• May need fallback to WASM for platforms where AOT doesn't work
• Build-time compilation adds complexity to CI/CD pipeline

---

Related Work

• PR: java-sdk-contrib#1672 - WASM integration PoC
• Storage Architecture: flagd-evaluator#55 - Stateless API discussion
• Chicory AOT: dylibso/chicory#589 - Ahead-of-time compilation

---

Phases

Phase	Goal	Deliverable
Phase 1	Java library artifact	Reusable flagd-evaluator-java library with bundled WASM
Phase 2	Testing & validation	Integration tests in flagd-evaluator, migration in java-sdk-contrib
Phase 3	Publish & adopt	Maven Central release, update documentation
Phase 4	AOT compilation (future)	Compile-time WASM → Java conversion when Chicory supports it

---

This issue serves as an epic for tracking the evolution from WASM runtime to optimized Java library.