K2 + Codex Java Development Workflow

Add a Flink REST endpoint for checkpoint summary

Codex should identify guardrails, Flink 2.2 docs, Java implementation anchors, route registration, message classes, and tests before editing code.

Collections

Agents

Orchestration

Codex output

Select a step or node to inspect how evidence moves from K2 into Codex. Live smoke: 4 agent steps returned sources

K2 platform value map

Each card maps a K2 feature to the development value shown in this demo.

Collections

Separate corpora for guides, docs, and code

K2 keeps Confluence-style guidance, versioned documentation, source, and tests queryable without mixing their roles.

Demo assets: `java-rd-guides`, `flink-docs-2.2`, `flink-code-2.2`.
Customer value: the agent knows whether evidence is a rule, API doc, implementation, or test.

Metadata filters

Precise retrieval for legacy Java

Framework, version, source kind, module, package, class, API surface, and path metadata keep answers scoped.

Demo filter examples target Flink 2.2 REST handlers and tests.
Customer value: fewer irrelevant snippets and less prompt waste.

Hybrid search

Semantic questions plus exact symbols

Dense retrieval helps with conceptual questions, while sparse matching protects exact Java class and method names.

Demo symbols: `JobVertexWatermarksHandler`, `MessageQueryParameter`.
Customer value: code references survive even when names are obscure.

Agents

Specialized context workers

Guide, docs, code, and architect agents each answer a bounded part of the development question.

Demo agents return guardrails, release docs, source/test anchors, and a cited plan.
Customer value: Codex receives structured context instead of a pile of text.

Knowledge Feed

Turn repeated discoveries into durable guidance

The feed loop can promote recurring source findings back into the guide corpus for future sessions.

Demo feed: `Flink REST Guide Feed` from code agent to `java-rd-guides`.
Customer value: institutional knowledge improves instead of being rediscovered every time.

Pipeline + MCP

Auditable route from K2 to Codex

The Pipeline Spec shows the topology; MCP makes the same Codex workflow use K2 context before editing.

Demo result: answer excerpts, code diff excerpts, and verification artifacts are linked.
Customer value: reviewers can inspect what evidence influenced the patch.

Question sent to both Codex runs

Add a backwards-compatible `includeMissing` query parameter to Flink 2.2 `JobVertexWatermarksHandler`; default behavior must stay unchanged, and focused handler tests must cover default, partial, and include-missing behavior.

Baseline answer, repo-only Codex

Added `includeMissing` and a watermark-specific message-parameters class.
Used local source search and model reasoning; no K2 source citations were available.
Reported focused test pass: `Tests run: 5, Failures: 0`.
Remaining uncertainty: broader `flink-runtime` and REST integration tests were not run.

K2-assisted answer, Codex with MCP

Added the same `includeMissing` behavior while citing retrieved Flink source, docs, tests, and generated guide material.
Used K2 context before editing: REST handler checklist, docs URL, handler source, headers source, response body, and neighboring test.
Reported focused test pass: `Tests run: 4, Failures: 0`.
Remaining uncertainty: only the focused handler test was run, not the full `flink-runtime` suite.

Baseline answer excerpt

Changes:
- Added a local watermark-specific message-parameters subclass.
- Added the optional boolean query parameter `includeMissing`, defaulting to `false`.
- Updated `JobVertexWatermarksHandler` to preserve existing behavior when absent or false.
- Expanded `JobVertexWatermarksHandlerTest` to cover default behavior, partial availability,
  explicit `includeMissing=true`, and explicit `includeMissing=false`.

Tests:
`mvn -pl flink-runtime -P!java21 -Dtest=JobVertexWatermarksHandlerTest ... test` passed.

Remaining uncertainty:
Validation was limited to the focused handler test.

K2-assisted answer excerpt

Implemented the vertex watermark REST extension with backward-compatible
optional missing-subtask reporting.

What changed:
- Added `includeMissing` for the watermark endpoint.
- Introduced `JobVertexWatermarksMessageParameters`.
- Updated `JobVertexWatermarksHandler` so default behavior stays the same.
- Extended `JobVertexWatermarksHandlerTest` with an include-missing case.

Sources consulted:
- repo://apache/flink@release-2.2.0/.../JobVertexWatermarksHandler.java
- repo://apache/flink@release-2.2.0/.../JobVertexWatermarksHandlerTest.java
- https://nightlies.apache.org/flink/flink-docs-release-2.2/docs/ops/rest_api/#part-0047
- generated://guides/flink/rest-handler-checklist.md

Baseline context Repository files and local search only. No durable guide, Feed, Pipeline, or K2 citation trail.

Guide context `generated://guides/flink/rest-handler-checklist.md` told Codex which REST conventions and tests to preserve.

Docs context Flink 2.2 REST API docs anchored version-specific endpoint behavior and response expectations.

Code/test context K2 returned `JobVertexWatermarksHandler`, `JobVertexWatermarksHeaders`, `MetricCollectionResponseBody`, and the focused handler test.

5 filesproduction/test files changed in accepted patch

2 new classesquery parameter and message parameters

4 testsfocused test run, 0 failures

K2 MCParm: codex_with_k2_mcp

Baseline accepted patch excerpt

diff --git a/.../JobVertexWatermarksHandler.java b/.../JobVertexWatermarksHandler.java
+import org.apache.flink.runtime.rest.handler.util.HandlerRequestUtils;
+import org.apache.flink.runtime.rest.messages.job.metrics.IncludeMissingQueryParameter;

+final boolean includeMissing =
+        HandlerRequestUtils.getQueryParameter(
+                request, IncludeMissingQueryParameter.class, false);

-if (watermarkValue != null) {
+if (watermarkValue != null || includeMissing) {
     metrics.add(new Metric(id, watermarkValue));
 }

answer style:
No retrieved K2 source URI list; final response summarizes local files changed.

K2 accepted production change excerpt

diff --git a/.../JobVertexWatermarksHandler.java b/.../JobVertexWatermarksHandler.java
+import org.apache.flink.runtime.rest.messages.job.metrics.IncludeMissingQueryParameter;
+import org.apache.flink.runtime.rest.messages.job.metrics.JobVertexWatermarksMessageParameters;

-extends AbstractJobVertexHandler<MetricCollectionResponseBody, JobVertexMessageParameters>
+extends AbstractJobVertexHandler<
+        MetricCollectionResponseBody, JobVertexWatermarksMessageParameters>

+final boolean includeMissingMetrics =
+        request.getQueryParameter(IncludeMissingQueryParameter.class)
+                .contains(Boolean.TRUE);

-if (watermarkValue != null) {
+if (watermarkValue != null || includeMissingMetrics) {
     metrics.add(new Metric(id, watermarkValue));
 }

K2 API, test, and evidence excerpts

new file: IncludeMissingQueryParameter.java
+public class IncludeMissingQueryParameter extends MessageQueryParameter<Boolean> {
+    private static final String QUERY_PARAMETER_NAME = "includeMissing";
+    public IncludeMissingQueryParameter() {
+        super(QUERY_PARAMETER_NAME, MessageParameter.MessageParameterRequisiteness.OPTIONAL);
+    }
+}

new file: JobVertexWatermarksMessageParameters.java
+public class JobVertexWatermarksMessageParameters
+        extends JobVertexMessageParameters {
+    public Collection<MessageQueryParameter<?>> getQueryParameters() {
+        return Collections.singleton(includeMissingParameter);
+    }
+}

test result:
Tests run: 4, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS

sources cited:
repo://apache/flink@release-2.2.0/.../JobVertexWatermarksHandler.java
repo://apache/flink@release-2.2.0/.../JobVertexWatermarksHandlerTest.java
https://nightlies.apache.org/flink/flink-docs-release-2.2/docs/ops/rest_api/
generated://guides/flink/rest-handler-checklist.md