docs: design specs for the generated service/operation layer - #139

Summary

Adds design specifications under docs/codegen/ for the typed service/operation layer that the future code generator will emit on top of sdk-core. These are specs only — no generator, no KotlinPoet, no generated source enters the repo. Every Kotlin/Java snippet is illustrative target output, anchored to real sdk-core types so the design stays grounded in the runtime that ships today.

A new docs/codegen/README.md indexes the specs and explains how they compose into one cohesive generated layer.

What's included

• service-method-tiers.md — Two-tier raw/cooked operations. The raw tier returns a lazy ParsedResponse<T> (read status/headers without parsing, or call value() to parse exactly once); the cooked tier delegates into the raw tier and returns the typed body. Error-mapping and deserialization compose as a single Response -> T ResponseHandler at the service layer, so the HTTP pipeline stays transport-pure and keeps returning a raw Response. Closeable + use {} + KDoc, no @MustBeClosed lint.

• typed-page-classes.md — List-operation page types whose nextPage() rebuilds a typed params object (params.toBuilder().<cursor>(…).build()) and re-invokes the operation, instead of splicing a URL. A generated PaginationStrategy bridges the typed page onto the existing stateless Paginator/Page contract; the runtime's RequestRebuilder is kept as the bring-your-own URL-splice path.

• operation-overloads.md — Curation rules capping each operation at one canonical params-object method plus a small fixed convenience set, leaning on Kotlin default arguments and Tristate<T> rather than a parameter cross-product. Avoids a permanent explicit-API + apiCheck binary-compat tax. Six deterministic rules so the generator stays mechanical.

• sub-service-tree.md — Lazily-instantiated sub-service accessor tree (client.foo().bar()) using by lazy at the root and every interior node. The root reuses the raw-response impl so the cooked tier is derived rather than duplicated, halving the generated type count. Includes a by lazy vs. memoized-supplier note for a possible future Java target.

Cross-cutting dependencies (tracked separately)

The specs note two prerequisites not yet in the tree: the OperationParams SPI (typed builder-backed params with toBuilder() / toRequest()) and the generator itself (per docs/refs-comparison.md).

Closes #55
Closes #56
Closes #58
Closes #59