chore: import upstream snapshot with attribution

examples/stories/refund_desk/README.md

@@ -0,0 +1,88 @@
+# refund-desk
+
+Resolver dependency injection: a tool parameter annotated `Annotated[T,
+Resolve(fn)]` is filled by running the resolver `fn` before the tool body,
+instead of from the LLM-supplied arguments. Here `refund_order(order_id,
+reason)` refunds what the order record says — `cents` is resolver-computed and
+does not appear in the input schema at all, so the model cannot supply or
+inflate the amount. Resolvers form a DAG (`load_order` → `refund_scope` →
+`refund_amount` / `ask_restock`), may return `Elicit[...]` to ask the human,
+and ask each question at most once per call. A resolver's own plain
+parameters are filled from the tool's arguments by name —
+`load_order(order_id)` receives the `order_id` the model passed to
+`refund_order`.
+
+## Run it
+
+```bash
+# stdio (default — the client spawns the server as a subprocess)
+uv run python -m stories.refund_desk.client
+
+# HTTP — the client self-hosts the server on a free port, runs, then tears it
+# down (2026 protocol: the questions ride embedded input_required round-trips;
+# add --legacy to ride synchronous push elicitation instead)
+uv run python -m stories.refund_desk.client --http
+```
+
+## What to look at
+
+- `server.py` `refund_order` — the signature is the whole story: `order_id` and
+  `reason` are model-facing; `cents` and `restock` carry `Resolve(...)` markers
+  and never reach the input schema. `client.py` asserts `properties` and
+  `required` are exactly `{order_id, reason}`. At 2026 the resolver's elicited
+  answers ride between rounds inside a `requestState` the SDK seals by default;
+  see `mrtr/` for the full security walk-through.
+- `server.py` `refund_scope` — the no-round-trip fast path: a one-line order
+  returns `Scope(full=True)` directly; only a multi-line order returns
+  `Elicit(...)`. The ORD-7001 call completes with zero elicitations.
+- `server.py` `_scoped` — the elicited SKU is human-typed free text; it is
+  validated against the order (`ToolError` on a miss) before any amount is
+  computed.
+- The decline contrast: `refund_amount` takes `scope` **unwrapped**, so
+  declining the scope question aborts the whole `cents` chain with an error
+  containing the framework's
+  `Resolver for parameter 'scope' could not resolve: elicitation was decline`
+  (the client sees it behind the usual `Error executing tool refund_order:`
+  prefix); `restock` keeps the `ElicitationResult` union, so declining restock
+  still refunds — just with `restocked: false`.
+- `client.py` — the scope counter proves memoization from outside: one call
+  consumes `refund_scope` from two resolvers but the question fires once.
+
+## Caveats
+
+- **Transport per era.** The framework picks the elicitation transport from
+  the negotiated protocol: at >= 2026-07-28 the questions ride embedded
+  `input_required` round-trips (a resolver that depends on another's answer is
+  asked in a later round); at <= 2025-11-25 each is a synchronous
+  `elicitation/create` push request mid-call. Author code is identical on
+  both — this client runs unchanged on either era.
+- **Decline order.** A declined unwrapped dependency aborts resolution in
+  tool-signature order — `cents` resolves before `restock`, so `ask_restock`
+  never runs. Don't rely on a later resolver's side effects after an earlier
+  consumer can abort.
+- **Memoization scope.** Each question is asked at most once per call, and
+  within a round each resolver runs at most once, keyed by function identity.
+  Across 2026 rounds only *elicited* outcomes persist (in `requestState`); any
+  resolver's body may run again on each round the call passes through. A
+  recorded answer is consulted only when the resolver asks its question again:
+  it satisfies the question without re-prompting the user, and it never stands
+  in for a value the resolver computes itself.
+  An answer is matched back to its question when the call resumes, so an
+  eliciting resolver must derive its question deterministically from the
+  tool's arguments and earlier answers; a per-call generated value (a
+  `default_factory` id, a timestamp) is re-derived each round and must not
+  appear in a question the answer is meant to bind to. Nothing is cached
+  across calls or connections.
+- **Validate elicited values.** Elicited answers are human-typed; check them
+  against your records (as `_scoped` does) before acting on them.
+
+## Spec
+
+[Elicitation — client features](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation),
+[Input required tool results — server features](https://modelcontextprotocol.io/specification/draft/server/tools#input-required-tool-results)
+
+## See also
+
+`mrtr/` (the 2026 `input_required` carrier these questions ride at
+>= 2026-07-28), `legacy_elicitation/` (the push mechanism they ride on
+handshake-era connections).