[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

Related to aws/aws-durable-execution-docs#295.
Shared guide: aws/aws-durable-execution-docs#304. Merge the guide first so the common supported-sampling link resolves.

Description

The sampling documentation describes decision reuse without clearly separating supported local policies from policies that can change across reinvocations. Clarify that an authoritative upstream Sampled=0/1 takes precedence; without that decision, local sampling must be deterministic for a stable canonical trace ID and unchanged configuration. Document constant and fixed-ratio policies, and explain that the process-local cache does not make changing policies supported or persist decisions across execution environments.

Preserve Java's same-trace ambient precedence and its provider-specific limitations. No runtime behavior, public API, or tests change.

Demo/Screenshots

Not applicable. Rendered the updated Markdown and inspected the sampling section and links.

Design

• Design note: not needed; documentation clarification only.
• Simpler options: no runtime mechanism or new configuration is added.
• Root cause: the previous reuse and replacement-sampler caveats could imply support for locally changing decisions.
• Net change: README +42/-27 lines; source and public API members unchanged.

Assumptions

Existing precedence and delegation are verified against OtelPluginSupport.resolveSamplingResult, DurableSampler.shouldSample, and the explicit-sampling tests in DurableSamplerTest. The shared guide anchor is introduced by the linked guide PR.

Decisions not covered by the issue or the design note

Keep provider compatibility caveats separate from policy support: plain replacements do not provide SDK-wide sampling guarantees, without declaring those configurations unsupported.

Checklist

• I have filled out every section of the PR template
• I have thoroughly tested this change (documentation checks below)
• Every new branch has a test that fails without it (not applicable: no code branches)
• Regression test requirement (not applicable: documentation only)
• Every edited test expectation is listed (none)

Testing

git diff --check passed. Markdown rendering confirmed four precedence entries and the shared-guide link. Repository-wide mvn -o -B -q spotless:check --file pom.xml passed with JDK 17.

Unit Tests

Not added or run; documentation only.

Integration Tests

Not added or run; documentation only.

Examples

Documented supported Java sampler choices and explicit upstream overrides; no executable examples added.