feat(plugin): propagate chained invoke trace context in START checkpoints

[zhongkechen]

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Issue Link, if available

Refs #764. Coordinated PRs: JS #957 and Python #755.

Description

New invoke START checkpoints can carry the calling operation's X-Ray context in the optional typed ChainedInvokeOptions.XAmznTraceId field. This updates the AWS SDK BOM to the official 2.56.0 model. Collection happens after the operation-start hook and payload serialization; batched invokes retain distinct operation parents, and request sizing includes the encoded options. Function, tenant, payload, operation identity and recorded outcomes retain their behavior.

The collector uses immutable SDK-owned input/contribution types and the first supported nonblank value. Conflicting contributions produce diagnostics without logging the header. Exception and LinkageError failures in an optional plugin are isolated so later plugins and the invoke START can proceed; other Error types retain their original propagation and identity.

The OTel sampling boundary is explicit. Invocation view uses an already-started operation span's real context. Execution view defers that span until completion, so it sends metadata only with a visible provider using DurableSampler. It abstains for replacement samplers and opaque provider/agent facades whose effective policy cannot be verified. Invocation view applies the same restriction to a planned context before an actual span is available. These cases retain the backend's omitted-header fallback; this PR does not promise new invoke-parent linkage through an unverifiable Execution-view provider. The fix does not query the sampler again, create an early span, change the configured sampling policy or inspect private provider internals.

The String-only producer overload avoids a dependency on the new metadata DTO classes in bundled plugin layers. It does not remove their existing same-thread invocation-hook capability requirement: cores lacking it, including released 2.2.1, are rejected at construction. Metadata collection additionally requires a core that implements the new hook.

Recorded START and terminal replay do not recollect metadata or resend START. A failed uncommitted START may recollect on retry. No new durable export acknowledgement, reflective model fallback, raw HTTP field injection or serializer replacement is introduced.

Validation

• The official Lambda 2.56.0 JAR was resolved in an isolated Maven repository; its loaded origin and SHA-256 were checked. A direct generated-marshaller probe verifies typed setter/getter and model-copy behavior, Sampled=1 and Sampled=0 values, omission of an absent header, and preservation of START/function/tenant/payload fields. It sends no backend request.
• The final sampling/propagation selection passes 107 tests on each of JDK17 and25, including public invoke/replay, known-sampler sampled/unsampled controls, replacement/opaque providers, and cross-class-loader sampling. Four Execution-view regressions fail before the guard while four observed Invocation-view controls pass. A separate four-case regression covers planned Invocation contexts before a span exists. Full Spotless passes.
• The linkage fix passes 83 focused tests on each JDK17/25. Two linkage cases fail before the fix while five ordinary/fatal controls pass; after it, later metadata collection and the public invoke START continue, with fatal identity/no-checkpoint controls retained.
• The prior 7e7afaf4 head passed Build, E2E and its existing OTel cloud suites. New-head CI for 664d477f is pending. These existing suites do not qualify the new cross-execution parent contract.

Cloud coverage and scope

The requested first-START/completed-replay and actual child Root/Parent/Sampled checks are implemented in shared conformance PR #131, strengthening its existing case11. Its current composed-reference cloud run reports 108 passes and four case11 Parent/ancestry failures across the two views and two backends. This is not a qualified Java backend-topology result. Additional wire diagnostics failed before deployment at OIDC role assumption; SDK-versus-service attribution remains unresolved. Runtime observations and complete X-Ray ancestry are separate from the client model/wire checks above.

This PR remains ready for review; no package, tag or release is published. The #782 factory/lifetime migration and distributed-map propagation remain separate. Java's current map/parallel APIs use CONTEXT operations and do not expose a distributed-map START path here.

Latest base validation

Current head 4aaeabf9 integrates main 2b2f930a, including upstream checkpoint-token revocation handling and OpenTelemetry 1.67.0. This ordinary base merge preserves the PR's feature changes; the incoming source/tests are retained. Java17 Core, testing, integration and OTel suite reports cover 2,795 passed, with zero failures or errors; full Spotless passes. Validation combines preserved reports from this integration with fresh reruns of the remaining suites after the local environment reset. New-head CI is tracked separately. The Lambda BOM remains 2.56.0 and the sampling capability boundary is unchanged. The PR remains ready for review.

[zhongkechen]

/ai review

Please review the current draft head, including the actual START wiring, replay/serialization coverage, and compatibility. The typed XAmznTraceId API intentionally assumes the pending generated Lambda model/backend update; the documented public-model compile failure is an accepted external dependency, and the real typed setter must remain.

[zhongkechen]

/ai review

Please review current draft head b744341 including the new real-marshaller checkpoint batch-boundary regressions and encoded option sizing. The typed XAmznTraceId setter/getter intentionally assume the pending generated Lambda model and backend rollout; the public-model compiler failure remains an explicitly accepted external dependency. Do not remove or gate the real typed field to make CI green.

[github-actions]

Codex AI review

No actionable findings in the PR changes. Tests were inspected but not executed. Residual risk: the supplied local tests do not establish deployed parent/child trace linkage.

Reviewed commit 4aaeabf9a3c62d3a32871ccba6d423dfd6d984ac. Workflow run