docs: patterns

Replace best-practices.md with a structured Best practices section under
Patterns. Each page covers one topic, carries TypeScript, Python, and Java
examples, and uses inline admonitions (tip/warning/danger/info) in place of
a trailing "Common mistakes" list.

Pages
- determinism.md              Determinism during replay
- idempotency.md              Idempotency and retries
- state.md                    Manage state
- step-design.md              Step design
- pause-resume.md             Pause and resume (waits, callbacks, polling)
- code-organization.md        Code organization

All code examples are --8<-- transclusions of files under
examples/{typescript,python,java}/patterns/<topic>/. Every SDK claim was
verified against the TS, Python, and Java SDK sources; notes live at
.kiro/specs/patterns-rewrite/verification.md.

Structure
- Add a Best practices subsection under Patterns with its own index.
- Drop best-practices.md.
- Drop examples/{typescript,python,java}/best-practices/ (all three were
  either placeholders or are now inlined into the new pages).
- Expand the Patterns nav block in zensical.toml.

Notable corrections to prior best-practices content
- StepConfig field is semantics, not executionMode.
- Python context.wait takes a Duration (Duration.from_hours(24)), not a
  raw int.
- Drop the invented UnrecoverableError pattern; show the real retry-
  strategy error-filtering API per language.
- Document the SDK's automatic ReplayChildren behavior for large
  BatchResults (>256 KB) and the per-item checkpoint consequences.
- Handler input is stored once and read from execution state on every
  replay (not re-passed by the invoker).

Closes #14
Closes #33
Closes #51
Closes #69

Author: yaythomas

docs/patterns/best-practices.md

@@ -0,0 +1,121 @@
+# Code organization
+
+Organize your code so that your workflows are composable and testable.
+
+## Separate orchestration from business logic
+
+Business logic is the work a step performs. Orchestration is when and in what order
+steps run.
+
+Put your logic in its own testable functions that the durable operation calls, rather
+than inline in the operation. Keep `DurableContext` out of your domain logic.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/patterns/code-organization/separate-logic.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/patterns/code-organization/separate-logic.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/patterns/code-organization/separate-logic.java"
+    ```
+
+!!! tip
+
+    Simplify your unit testing by not referencing `DurableContext` in your domain logic
+    functions. Cover orchestration separately with the
+    [durable function testing framework](../../testing/index.md).
+
+## Group operations with child contexts
+
+A child context is a named scope that groups operations in the execution history. Inside
+a child context you can call any durable operation, including nested child contexts.
+
+Use a child context when a block of work is one logical unit that is composed of several
+operations.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/patterns/code-organization/child-context.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/patterns/code-organization/child-context.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/patterns/code-organization/child-context.java"
+    ```
+
+## Group related configuration
+
+When several steps share the same retry strategy, timeout, or serdes, define the
+configuration once and reuse it. Use the name of a configuration object to make its
+intent clear.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/patterns/code-organization/group-config.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/patterns/code-organization/group-config.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/patterns/code-organization/group-config.java"
+    ```
+
+## Run independent work concurrently
+
+Use `parallel` for a fixed number of named branches and `map` to iterate over a
+variable-length list. Both are durable so each branch checkpoints independently and
+survives Lambda timeouts or sandbox crashes, unlike language-specific constructs such as
+`Promise.all`, `asyncio.gather`, or `CompletableFuture`.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/patterns/code-organization/parallelism.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/patterns/code-organization/parallelism.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/patterns/code-organization/parallelism.java"
+    ```
+
+See the [parallel](../../sdk-reference/operations/parallel.md) and
+[map](../../sdk-reference/operations/map.md) references for completion policies,
+concurrency limits, and per-item configuration.
+
+## See also
+
+- [Step design](step-design.md)
+- [Child context operation](../../sdk-reference/operations/child-context.md)
+- [Parallel operation](../../sdk-reference/operations/parallel.md)
+- [Map operation](../../sdk-reference/operations/map.md)

docs/patterns/best-practices/code-organization.md

@@ -0,0 +1,144 @@
+# Determinism during replay
+
+The Durable Execution SDK checkpoints your code so that it can terminate the current
+invocation and not consume compute while it waits for a timed duration or processing
+result to be ready. The AWS Lambda backend re-invokes the function when it is ready to
+resume processing.
+
+Durable functions run your handler from the top on every invocation. A step that
+completed in an earlier invocation returns its checkpointed result on replay without
+re-executing the code inside the step. Anything outside a step or other durable
+operation runs every time the function replays.
+
+For replay to follow the same path, the code that runs every time has to produce the
+same values. That is determinism. Non-deterministic code inside your handler body can
+send control flow down a different branch on replay, so a downstream step runs with the
+wrong inputs.
+
+## Handler code must be deterministic
+
+Any code that is not inside a durable operation must be a pure function of the handler
+inputs and the results of completed operations. Anything that depends on wall-clock
+time, a random source, an external service, the local file system, or mutable global
+state is non-deterministic and must run inside a durable operation.
+
+Concrete examples of code that is not deterministic:
+
+- **Time and identity** `Date.now()`, `time.time()`, `Instant.now()`, `UUID` generation,
+    or anything that returns a different value each call.
+- **External I/O** HTTP calls, database reads, AWS SDK calls, reading files.
+- **Random numbers** `Math.random()`, `random.random()`, `Random`.
+
+## Non-deterministic code must be in a durable operation
+
+A step checkpoints its return value. On replay the step returns the checkpointed value
+instead of running the underlying code. Wrapping a non-deterministic call in a step
+means the value will always be the result of the first successful completion of that
+code.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/patterns/determinism/non-deterministic-in-step.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/patterns/determinism/non-deterministic-in-step.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/patterns/determinism/non-deterministic-in-step.java"
+    ```
+
+Because the SDK checkpoints the result of `generate-transaction-id`, every replay sees
+the same `transactionId` and the charge step receives the same argument. Without the
+wrapper, `UUID.randomUUID()` would produce a new value on every replay and the
+downstream step would either double-charge or hit an idempotency error from the payment
+service.
+
+!!! tip
+
+    Wrap every non-deterministic call inside a step.
+
+## Pass data through return values, not closures
+
+State outside a step resets to its initial value on replay. Steps return their cached
+results, but assignments, mutations, and pushes that happen outside steps run again on
+every invocation. Although this pattern looks like it works on the first invocation, it
+breaks as soon as the workflow replays after a crash or a wait.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/patterns/determinism/return-value-passing.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/patterns/determinism/return-value-passing.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/patterns/determinism/return-value-passing.java"
+    ```
+
+For processing a list of independent items,
+[map](/durable-execution/sdk-reference/operations/map/) is a simpler choice than an
+explicit loop. It runs the per-item operation in parallel, checkpoints each result, and
+returns a `BatchResult` you can reduce. Use an explicit loop when items depend on each
+other, such as a running total or chained transformations. Keep the loop deterministic.
+Each step must produce the same result on replay.
+
+!!! danger
+
+    Mutating state outside a step fails silently. The first invocation looks correct. Replay
+    resets the mutation while steps return their cached results.
+
+## Keep branches stable across replay
+
+Control flow decisions made outside steps must depend only on deterministic inputs. If
+an `if` or `switch` depends on something non-deterministic, replay can walk a different
+branch and attempt to return results from operations that never ran. Wrap the
+non-deterministic decision into a step and branch on the step's return value.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/patterns/determinism/stable-branches.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/patterns/determinism/stable-branches.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/patterns/determinism/stable-branches.java"
+    ```
+
+The same rule applies to reading from external services. Fetching a flag from a database
+outside a step risks replaying against a changed value. Fetch inside a step, branch on
+the returned value.
+
+!!! warning
+
+    Feature flags, environment variables read at runtime, and configuration pulled from a
+    remote store could all change between the first invocation and a replay. Capture the
+    value inside a step so the evaluation criteria are stable.
+
+## See also
+
+- [Idempotency and retries](idempotency.md) How retry behavior interacts with
+    determinism.
+- [Step design](step-design.md) Naming, granularity, and the step boundary.
+- [Step operation reference](../../sdk-reference/operations/step.md)

docs/patterns/best-practices/determinism.md

@@ -0,0 +1,120 @@
+# Idempotency and retries
+
+Replay and retry can each run the same operation more than once. An operation with a
+side effect repeats the side effect on every run. Idempotency describes operations where
+the effect remains the same regardless of how many times they run.
+
+## At-most-once vs at-least-once
+
+A step has an execution semantic that controls what happens when an attempt fails to
+complete, for example when the Lambda sandbox dies, the network drops or the runtime
+hits the invocation timeout mid-invocation.
+
+- **At-least-once per retry (default).** The SDK initiates a `START` checkpoint and then
+    immediately runs the code inside the step without waiting for the checkpoint
+    response. If the attempt does not complete due to an interruption, the step runs
+    again on replay. This is safe only for idempotent operations.
+- **At-most-once per retry.** The SDK waits for confirmation that the `START` checkpoint
+    committed before running the code inside the step. If the attempt does not complete
+    due to an interruption, the SDK marks the step as interrupted on replay and raises a
+    `StepInterrupted` error instead of re-executing.
+
+Both semantics are per retry attempt. Neither guarantees the step runs exactly once
+across the entire workflow. A retry strategy that retries on failure will run the step
+again even under at-most-once per retry. To limit a step to a single execution attempt
+end-to-end, combine at-most-once with a no-retry strategy.
+
+!!! tip
+
+    At-least-once is the default. Any interruption re-runs the step on replay, so the code
+    inside must be safe to run more than once.
+
+## Match the semantic with the side effect
+
+- **At-least-once** is for idempotent operations, such as reads that do not mutate,
+    writes to an upsert-capable store, calls that accept an idempotency key and anything
+    safe to re-run.
+- **At-most-once** is for operations with external side effects such as charging a
+    payment card, sending a one-shot SMS or a POST to a non-idempotent API.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/patterns/idempotency/choose-semantics.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/patterns/idempotency/choose-semantics.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/patterns/idempotency/choose-semantics.java"
+    ```
+
+!!! warning
+
+    At-most-once applies per attempt, not per workflow. Combine it with a no-retry strategy
+    to guarantee the step runs exactly once end-to-end.
+
+## Idempotency tokens
+
+For external services that support an idempotency key, such as most modern payment APIs,
+generate a key inside a step once and pass it to every attempt of the side-effecting
+step. The external service deduplicates repeated requests with the same key, so even
+at-least-once retries are safe.
+
+!!! warning
+
+    Generate the key *inside* a step. A key generated outside a step changes on replay,
+    which defeats deduplication and doubles up on retry.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/patterns/idempotency/idempotency-tokens.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/patterns/idempotency/idempotency-tokens.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/patterns/idempotency/idempotency-tokens.java"
+    ```
+
+The same pattern applies to any operation that writes to an external store. Include the
+key in the write and rely on the store's deduplication.
+
+!!! tip
+
+    When an idempotency-enabled API returns a duplicate-request error on retry, it usually
+    means the first attempt already succeeded. Handle that error as success, not failure.
+
+## Database retry patterns
+
+When you own the database, you can make writes idempotent without tokens.
+
+- **Conditional writes.** DynamoDB `PutItem` with `attribute_not_exists`, SQL
+    `INSERT ... ON CONFLICT DO NOTHING`, or upserts keyed by a stable ID.
+- **Check then write in a single transaction.** Use a transaction that reads the current
+    state and writes the new state atomically.
+- **Append-only logs.** Write events with a deterministic event ID. Readers deduplicate
+    on ID.
+
+Avoid `INSERT` without a uniqueness constraint, and avoid counter increments without a
+conditional check if a retry could apply them twice.
+
+## See also
+
+- [Determinism and replay](determinism.md) Why operations can run more than once to
+    begin with.
+- [Step design](step-design.md) Retry strategy and the boundary between steps.
+- [Errors and retries](../../sdk-reference/error-handling/errors.md)