feat: add engineVersion option to projection create

[w1am]

Summary

• Adds engineVersion(int) to CreateProjectionOptions, exposing the V2 projection engine introduced in KurrentDB
• Adds the engine_version field (5) to CreateReq.Options in the client proto so the value is sent to the server
• Wires the option through CreateProjection so it lands on the gRPC CreateReq.Options

V2 selection: engineVersion(2) selects V2. 0 (default) or 1 selects V1. The engine version is pinned at create time and cannot be changed via update.

V2 has limitations vs V1 (documented on the option's javadoc):

• Result streams are not emitted (no outputState() live updates — poll state instead)
• Bi-state projections ($initShared) are not supported
• trackEmittedStreams=true is rejected by the server

Closes DEV-1657.

Test plan

• Build with a supported JDK (JDK 25 + Gradle 8.13 fail to evaluate the project locally — unrelated to this change)
• Confirm protoc generates setEngineVersion(int) on CreateReq.Options.Builder
• Manual: create a projection against a KurrentDB build with the V2 engine, with engineVersion(2), verify it runs as V2
• Manual: create with default options, verify it still runs as V1

[linear]

DEV-1657 Java | Support projection v2 engine

[qodo-code-review]

Review Summary by Qodo

Add engineVersion option to projection create for V2 engine support

✨ Enhancement

Walkthroughs

Description

• Adds engineVersion option to projection creation API
• Exposes V2 projection engine with partition-based parallel processing
• Engine version pinned at create time, cannot be changed via update
• V2 has limitations: no result streams, no bi-state projections, rejects trackEmittedStreams

Diagram

flowchart LR
  A["CreateProjectionOptions"] -->|"engineVersion int"| B["CreateProjection"]
  B -->|"setEngineVersion"| C["CreateReq.Options"]
  C -->|"engine_version field 5"| D["gRPC Server"]
  D -->|"0/1=V1, 2=V2"| E["Projection Engine"]

Loading

File Changes

1. src/main/java/io/kurrent/dbclient/CreateProjectionOptions.java ✨ Enhancement +18/-0

Add engineVersion field and builder method

• Added engineVersion private field to store engine version selection
• Added getEngineVersion() accessor method
• Added engineVersion(int value) public builder method with comprehensive javadoc
• Javadoc documents V1/V2 selection, immutability, and V2 limitations

src/main/java/io/kurrent/dbclient/CreateProjectionOptions.java

---

2. src/main/java/io/kurrent/dbclient/CreateProjection.java ✨ Enhancement +3/-0

Wire engineVersion through to gRPC request

• Added engineVersion private field to store extracted option value
• Extract engineVersion from options in constructor
• Pass engineVersion to gRPC CreateReq.Options builder via setEngineVersion()

src/main/java/io/kurrent/dbclient/CreateProjection.java

---

3. src/main/proto/kurrentdb/protocol/v1/projectionmanagement.proto ⚙️ Configuration changes +1/-0

Add engine_version field to proto definition

• Added int32 engine_version = 5 field to CreateReq.Options message
• Field comment documents version selection: 0 or 1 for V1, 2 for V2

src/main/proto/kurrentdb/protocol/v1/projectionmanagement.proto

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0)

1. Missing engineVersion validation 🐞 Bug ☼ Reliability

Description

CreateProjection forwards engine_version and track_emitted_streams without validating the documented
contract (only 0/1/2 supported; V2 rejects trackEmittedStreams), so callers can construct requests
that are known-invalid per the API docs and only fail at runtime. This is avoidable with fail-fast
validation in CreateProjectionOptions and/or before building the gRPC request.

Code

src/main/java/io/kurrent/dbclient/CreateProjection.java[R38-42]

            Projectionmanagement.CreateReq.Options.Builder optionsBuilder =
                Projectionmanagement.CreateReq.Options.newBuilder()
                    .setQuery(query)
+                    .setEngineVersion(engineVersion)
                    .setContinuous(continuousBuilder);

Evidence

The V2 limitations are explicitly documented in the client API, but the request builder always sends
both track_emitted_streams and engine_version as provided, with no cross-field validation (e.g.,
engineVersion==2 with trackEmittedStreams==true). The proto comment also documents the supported
engine_version values (0/1/2), but the Java API accepts any int and forwards it.

src/main/java/io/kurrent/dbclient/CreateProjection.java[33-42]
src/main/java/io/kurrent/dbclient/CreateProjectionOptions.java[50-61]
src/main/proto/kurrentdb/protocol/v1/projectionmanagement.proto[24-32]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`CreateProjectionOptions.engineVersion(int)` accepts any integer, and `CreateProjection` always forwards `engine_version` plus `track_emitted_streams` without validating the documented contract (supported values, and the V2 restriction on `trackEmittedStreams`). This allows callers to build requests that are documented as invalid and only discover it via a server error.

### Issue Context
The javadoc states V2 rejects `trackEmittedStreams`, and the proto comment documents valid engine version values.

### Fix Focus Areas
- src/main/java/io/kurrent/dbclient/CreateProjectionOptions.java[50-61]
- src/main/java/io/kurrent/dbclient/CreateProjection.java[33-42]

### Suggested fix
- Add fail-fast validation:
 - Reject `engineVersion` values outside the documented set (0/1/2) with `IllegalArgumentException`.
 - Reject the documented-invalid combination `engineVersion == 2 && trackEmittedStreams == true` (either when setting either option, or in `CreateProjection.execute()` right before building the request).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---