add CacheableResult from protocol 2026-07-28

[Yusufihsangorgel]

Next 2026-07-28 core-protocol slice tracked in #162, following #565 and kept separate from the HTTP transport work.

Adds the CacheableResult "mixin" extension type and the CacheScope enum, modeling the caching hints from modelcontextprotocol/modelcontextprotocol#2549:

• CacheableResult.ttlMs reads the TTL hint as an int. The spec requires servers to send ttlMs >= 0 and tells clients to treat both an absent value and a negative one as 0 (https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/draft/server/utilities/caching.mdx; servers on earlier protocol versions never send the field), so the getter reads 0 for both. Same fold Result.resultType does with complete.
• CacheableResult.cacheScope reads the scope as a nullable CacheScope. The schema types the field as a closed "public" | "private" union with no absent-value default, so the getter is an enum like the package's other closed unions (Role, LoggingLevel) but resolves the way Schema.type does: an absent or unrecognized value reads as null instead of throwing, which keeps results from older servers readable and leaves room for the still-draft schema to grow the union before the RC.
• The type mirrors PaginatedResult: no public constructor, "mixed in" by other extension types. The schema attaches it to the four list results, ReadResourceResult, and the new DiscoverResult; the five that already exist in this package now implement it, so the hints are readable on the results the client API already returns. DiscoverResult itself and server-side emission of the hints (factory parameters) are follow-up slices.

Tests

• ttlMs reads 0 on an empty result and for a negative value, cacheScope reads null when absent, both parse when present, an unrecognized scope string reads as null, and a ListToolsResult carrying the fields exposes both.
• dart test -p chrome,vm -c dart2wasm,dart2js,kernel,exe passes (220 tests in each of the four configurations).
• dart analyze --fatal-infos is clean here and in mcp_examples resolved against this branch.

Part of #162.

[gemini-code-assist]

Code Review

This pull request introduces the CacheableResult extension type and the CacheScope enum to support caching hints (ttlMs and cacheScope) defined in the 2026-07-28 draft schema. Multiple result types have been updated to implement CacheableResult, and corresponding unit tests have been added. Feedback suggests optimizing the cacheScope getter by checking for a null value before iterating over the enum values to avoid unnecessary overhead.

[jakemac53]

@Yusufihsangorgel note that I will be out of office until Thursday, so I won't be able to review additional PRs until then. If they are relatively unrelated though you can stack up multiple at once and I will review them all when I get back.

[Yusufihsangorgel]

Thanks for landing this one. I'll line up the next transport slices so they're ready when you're back. Enjoy the time off.