feat: add itemNamer for map operation

[wangyb-A]

Description

Adds itemNamer functionality to MapConfig, allowing custom naming of map iterations. This feature provides parity with the Python SDK implementation (PR #387) while adapting to Java's existing API patterns.

Changes

1. MapConfig.java:

   • Added itemNamer: BiFunction<Object, Integer, String> field
   • Added getter itemNamer() method
   • Updated builder to support itemNamer() configuration
   • Maintained backward compatibility

2. MapOperation.java:

   • Updated to use custom iteration names when itemNamer is provided
   • Falls back to default naming ("map-iteration-N" or "name-iteration-N") when no itemNamer is set

3. Unit Tests:

   • MapConfigItemNamerTest.java: 9 comprehensive tests covering all itemNamer functionality
   • MapOperationItemNamerTest.java: 3 integration tests for MapOperation construction
   • All 27 existing map tests continue to pass

Usage

MapConfig config = MapConfig.builder()
    .itemNamer((item, index) -> "process-" + item + "-iteration-" + index)
    .maxConcurrency(2)
    .build();

// Map iterations will be named "process-order-101-iteration-0", etc.
// Instead of default "map-iteration-0", "map-iteration-1"

Testing

• ✅ All new unit tests pass
• ✅ All existing map-related tests pass (backward compatibility)
• ✅ Local integration test verified functionality
• ✅ Feature matches Python SDK reference implementation

Notes

• Java already has named parallel branches via branch(String name, ...), so no ParallelBranch wrapper was needed (unlike Python)
• Implementation follows Java's builder pattern and existing API conventions
• Resolves issue [Feature]: Item namer for map operation #528

[github-actions]

This narrows MapConfig.Builder.nestingType from public to private, an unrelated source-incompatible change bundled into this feature PR. Any external code that read/wrote the field directly (MapConfig.builder().nestingType = ...) will fail to compile against the new SDK. AGENTS.md states "Do not change public API signatures ... without instruction."

Encapsulating the field is the right long-term design (it matches how the other builder fields and ParallelConfig are declared), but since it is a breaking change orthogonal to itemNamer, consider either splitting it into its own change with a note in the changelog/release notes, or explicitly calling it out in the PR description so it is a deliberate, documented break rather than an incidental one.

[wangyb-A]

Correct, and reverted in 0d16426. Confirmed against origin/main, which has public NestingType nestingType; — this branch narrowed it to private. That was incidental tidying on my part with no connection to itemNamer, and you are right that it breaks already-compiled clients. Restored to public; whether that field should be public at all is a separate call, not something this PR should decide as a side effect.

Two other findings from the same round were raised outside this thread, so recording the outcome here for traceability:

Iteration names resolved after START (fixed in the same commit). execute() sends the START checkpoint and calls addAllItems() on the next line, so the ParameterValidator call added in d61dd05 threw after the map was STARTED and its start plugin hook had fired. If the caller caught the IllegalArgumentException, a permanently STARTED map and an unbalanced plugin lifecycle were left behind. Name resolution and validation now happen in the MapOperation constructor, before any checkpoint. Added testCaughtItemNamerValidationLeavesNoHalfOpenMap, which swallows the failure and asserts the rejected map was never checkpointed and that replay still succeeds — verified non-vacuous by running it against d61dd05, where it fails with failed map should not be checkpointed ... but was: TestOperation@f438904.

Parameterizing MapConfig by input type — not done here, deliberately. The WaitForConditionConfig<T> precedent is real and the ergonomic complaint is legitimate; casting Object for domain items is poor. Two reasons I have left it out of this PR rather than silently doing it: MapConfig appears in 28 files, so it turns a focused feature change into a public-API reshape reviewed under the wrong heading; and it sits in tension with the visibility finding above, where the standard applied was to avoid incidental API changes in a feature PR. Worth noting the change is less breaking than it appears — MapConfig<I> erases to MapConfig, so the four DurableContext.map(...) overloads stay binary compatible and existing source keeps compiling with raw-type warnings. Happy to do it as a follow-up, or here if you would rather it land together.

1112 sdk tests and 393 integration tests pass; spotless:check clean project-wide.

[github-actions]

Codex AI review

• [P1] Resolve names before consuming the operation ID — sdk/src/main/java/software/amazon/lambda/durable/operation/MapOperation.java:87
  A caught namer or validation exception leaves an uncheckpointed ID hole. If the namer later succeeds on replay, new work can silently occupy that hole while subsequent operations replay normally. Resolve names before nextOperationId() and add a replay test covering this transition.

• [P1] Validate names for flat-map replays — sdk/src/main/java/software/amazon/lambda/durable/operation/MapOperation.java:126
FLAT iteration operations are virtual, so peekOperation() always returns null and every comparison is skipped. A suspended map can therefore resume with changed context names and observable logging/plugin behavior without detecting nondeterminism. Persist names in the parent checkpoint or reject this combination, with a suspended FLAT replay test.

• [P2] Preserve the existing DurableContext signature — sdk/src/main/java/software/amazon/lambda/durable/DurableContext.java:549
  Replacing the raw MapConfig parameter with MapConfig<? super I> is source-incompatible for downstream DurableContext implementations: their old override has the same erasure but no longer overrides this method. Keep the public signatures raw and adapt internally, or defer the signature change to a major release.

Reviewed commit 841bb2f2cb89ab1846616626ad9ce8ce12203a9c. Workflow run

[github-actions]

Claude AI review

Review: feat: add itemNamer for map operation (PR #576)

No actionable findings. This is a clean, well-tested change. I traced the full path — MapConfig<I> generification, the DurableContext/DurableContextImpl signature changes to MapConfig<? super I>, MapOperation.resolveIterationNames()/validateIterationNamesAgainstCheckpoint(), ExecutionManager.peekOperation(), and the existing name/replay validation in BaseDurableOperation and ChildContextOperation — and verified backward compatibility across all existing MapConfig call sites.

Verified correct:

• Generic variance: MapConfig<? super I> correctly models config as an item consumer (PECS); itemNamer composes with MapOperation's BiFunction<? super I,Integer,String> and apply(items.get(i), i).
• Backward compatibility: existing raw MapConfig.builder().build() sites still infer through the new MapConfig.<I>builder() defaults and the ? super I parameter; only unchecked warnings result, and no compiler config fails on warnings.
• Fail-fast: resolving/validating names in the constructor — before START checkpoint and the start plugin hook — avoids a half-open STARTED map on namer throw/invalid name (confirmed by testCaughtItemNamerValidationLeavesNoHalfOpenMap).
• Replay gap closed: small-result (cached-payload) maps markAlreadyCompleted() without executing children, so per-operation validateReplay never runs for iterations; validateIterationNamesAgainstCheckpoint() fills that gap via read-only peekOperation (no REPLAY→EXECUTION transition) and skips uncheckpointed/virtual children via the null-name guard.
• ID stability: operation IDs stay counter-derived, so custom/duplicate/null names don't affect ordering or replay matching.

Test coverage is comprehensive across config, construction, typed items, null/partial-null fallback, invalid-name rejection, duplicate names, changed-vs-stable namer on cached replay, and half-open recovery.

Residual test risk (disclosed; read-only review, no build/run):

• Could not execute mvn, so cannot confirm the suite passes or spotless formatting is clean — only that the changes are type-safe and logically consistent.
• FLAT/virtual maps get no iteration-name replay validation (children aren't checkpointed by name). By design and consistent with prior behavior, but there is no negative test asserting a changed namer under NestingType.FLAT is not rejected (MapOperation.java:863 / validateIterationNamesAgainstCheckpoint).
• The new mismatch check runs in replay() (after the map's potential fireOnOperationEnd continuation hook), later than the standard check in validateReplay(); termination there is safe, but plugin-hook balance around a mid-replay termination on the small-result path is not directly asserted.

Reviewed commit 841bb2f2cb89ab1846616626ad9ce8ce12203a9c. Workflow run