@lovrozagar/honey 0.6.5 → 0.7.0

package/src/codegen-go.ts

@@ -1,16 +1,34 @@
 /* Go SDK emitter — generates a complete Go module from an OpenAPI 3.1 spec.
- * Mirrors the TS emitter pattern (string-array + join, tab indent).
- * Static runtime files (sse.go, ws.go, etc.) are read from ./client-go/ at
- * module load time and copied verbatim into the output file map.
+ *
+ * Input is the SDK request model (codegen-sdk-model.ts), never the raw spec. Every identifier
+ * comes from a NameScope seeded with the runtime's own package-level names, and every spec string
+ * lands in source through goString / goComment (codegen-lang.ts).
+ *
+ * Static runtime files (sse.go, ws.go, etc.) are read from ./client-go/ at module load time and
+ * copied verbatim into the output file map.
  */
 
 import { spawnSync } from "node:child_process"
 import { readFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
-import { collectSDKMethods, extractOpenApiPathParams, isSSEOperation, resolveRefs } from "./codegen.ts"
-import { methodsOf, namespacesOf, toIR } from "./codegen-ir.ts"
-import type { IRNamespace, IROperation } from "./codegen-ir.ts"
-import { GO_KEYWORDS, goPascal, isStringEnum, renderTopLevel, renderUse } from "./go-type-emitter.ts"
+import type { OpenApiSpecInput } from "./codegen.ts"
+import { serviceMapOf } from "./codegen.ts"
+import { methodsOf, namespacesOf, specAuth } from "./codegen-ir.ts"
+import type { IRAuth, IRInfo, IRNamespace, IRSchema } from "./codegen-ir.ts"
+import {
+	GO_KEYWORDS,
+	GO_PREDECLARED,
+	NameScope,
+	cmpCodeUnit,
+	goComment,
+	goExported,
+	goLocal,
+	goString,
+} from "./codegen-lang.ts"
+import { buildSdkModel, valueCycleSchemas } from "./codegen-sdk-model.ts"
+import type { SdkModel, SdkOp } from "./codegen-sdk-model.ts"
+import { irRenderTopLevel, irRenderUse } from "./go-type-emitter.ts"
+import type { GoTypeNames, RenderUseCtx } from "./go-type-emitter.ts"
 
 /* ── types ── */
 
@@ -30,35 +48,29 @@ export type GeneratedGoSDK = {
 	serviceMap: Record<string, Record<string, unknown>>
 }
 
-type OpenApiSpec = {
-	components?: {
-		schemas?: Record<string, Record<string, unknown>>
-	}
-	info: { description?: string; title: string; version: string }
-	openapi: string
-	paths: Record<string, Record<string, Record<string, unknown>>>
-}
-
 /* ── runtime template loader ── */
 
 let runtimeCache: Map<string, string> | null = null
 
+const RUNTIME_FILES = [
+	"result.go",
+	"errors.go",
+	"runtime.go",
+	"invalidation.go",
+	"sse.go",
+	"ws.go",
+	"transport.go",
+	"realtime.go",
+	"export.go",
+	"nullable.go",
+]
+
 /** Reads static .go runtime files from ./client-go/ and caches them. */
 export function loadGoRuntimeTemplates(): Map<string, string> {
 	if (runtimeCache) return runtimeCache
 
-	const names = [
-		"result.go",
-		"errors.go",
-		"runtime.go",
-		"invalidation.go",
-		"sse.go",
-		"ws.go",
-		"transport.go",
-		"realtime.go",
-	]
 	const cache = new Map<string, string>()
-	for (const name of names) {
+	for (const name of RUNTIME_FILES) {
 		const filePath = fileURLToPath(new URL(`./client-go/${name}`, import.meta.url))
 		let content: string
 		try {
@@ -72,17 +84,42 @@ export function loadGoRuntimeTemplates(): Map<string, string> {
 	return cache
 }
 
+let runtimeIdentCache: Set<string> | null = null
+
+/** Every package-level identifier the runtime files declare; generated names must avoid them all. */
+export function goRuntimeIdentifiers(): Set<string> {
+	if (runtimeIdentCache) return runtimeIdentCache
+	const out = new Set<string>()
+	for (const src of loadGoRuntimeTemplates().values()) {
+		let inBlock = false
+		for (const line of src.split("\n")) {
+			const top = /^(?:func|type|var|const)\s+([A-Za-z_]\w*)/.exec(line)
+			if (top) out.add(top[1])
+			if (/^(?:var|const|type)\s*\($/.test(line)) {
+				inBlock = true
+				continue
+			}
+			if (inBlock) {
+				if (line.startsWith(")")) inBlock = false
+				else {
+					const m = /^\t([A-Za-z_]\w*)/.exec(line)
+					if (m) out.add(m[1])
+				}
+			}
+		}
+	}
+	runtimeIdentCache = out
+	return out
+}
+
 /* ── helpers ── */
 
+/** @deprecated kept for callers outside this file; use goLocal / goExported. */
 export function safeResourceName(name: string): string {
 	const lower = name.toLowerCase()
 	return GO_KEYWORDS.has(lower) ? `${name}_` : name
 }
 
-function nestedStructName(path: string[]): string {
-	return `${path.map(goPascal).join("")}Resource`
-}
-
 /**
  * Derive auth header name + prefix from OpenAPI securitySchemes.
  * Defaults to Authorization + "Bearer " when no scheme is declared, preserving
@@ -90,222 +127,98 @@ function nestedStructName(path: string[]): string {
  * embeds a "Format: <Prefix> {token}" hint (common pattern for APIs like Anyrow
  * that use `Authorization: ApiKey <token>`).
  */
-export function detectAuthScheme(spec: Record<string, unknown>): { headerName: string; prefix: string } {
-	const components = (spec.components ?? {}) as Record<string, unknown>
-	const schemes = (components.securitySchemes ?? {}) as Record<string, Record<string, unknown>>
-	const keys = Object.keys(schemes).sort()
-	if (keys.length === 0) return { headerName: "Authorization", prefix: "Bearer " }
-	const scheme = schemes[keys[0]]
-	const type = String(scheme.type ?? "")
-	if (type === "http") {
-		const httpScheme = String(scheme.scheme ?? "").toLowerCase()
-		if (httpScheme === "basic") return { headerName: "Authorization", prefix: "Basic " }
-		return { headerName: "Authorization", prefix: "Bearer " }
-	}
-	if (type === "apiKey" && scheme.in === "header") {
-		const headerName = String(scheme.name ?? "Authorization")
-		const desc = String(scheme.description ?? "")
-		const match = /Format:\s*(\S+)\s+\{/i.exec(desc)
-		if (match) return { headerName, prefix: `${match[1]} ` }
-		return { headerName, prefix: "" }
-	}
-	return { headerName: "Authorization", prefix: "Bearer " }
+/** The auth header and prefix the spec's first security scheme asks for (see `IR.auth`). */
+export function detectAuthScheme(spec: Record<string, unknown>): IRAuth {
+	return specAuth(spec as unknown as OpenApiSpecInput)
 }
 
 function goImportBlock(stdlib: string[], thirdParty: string[]): string {
 	const l: string[] = []
 	l.push(`import (`)
-	for (const p of [...stdlib].sort()) l.push(`\t"${p}"`)
+	for (const p of [...new Set(stdlib)].sort(cmpCodeUnit)) l.push(`\t"${p}"`)
 	if (thirdParty.length > 0) {
 		l.push(``)
-		for (const p of [...thirdParty].sort()) l.push(`\t"${p}"`)
+		for (const p of [...thirdParty].sort(cmpCodeUnit)) l.push(`\t"${p}"`)
 	}
 	l.push(`)`)
 	return l.join("\n")
 }
 
-/** Converts /users/{id} → string expression pieces for URL construction. */
-function pathToGoExpr(path: string): string {
-	const params = extractOpenApiPathParams(path)
-	if (params.length === 0) return JSON.stringify(path)
-	let expr = JSON.stringify(path)
-	for (const p of params) {
-		expr = expr.replace(`{${p}}`, `" + url.PathEscape(${p}) + "`)
-	}
-	/* clean up empty string concatenation at edges */
-	expr = expr.replace(/"" \+ /g, "").replace(/ \+ ""/g, "")
-	return expr
-}
-
-/** Extracts the Go response type for an operation from its 2xx responses. */
-function goResponseType(op: Record<string, unknown>): string {
-	const responses = op.responses as Record<string, Record<string, unknown>> | undefined
-	if (!responses) return "json.RawMessage"
-
-	for (const [status, response] of Object.entries(responses)) {
-		const code = Number.parseInt(status, 10)
-		if (Number.isNaN(code) || code < 200 || code >= 300) continue
-		if (code === 204) return ""
-		const content = response.content as Record<string, Record<string, unknown>> | undefined
-		if (!content) return ""
-		const jsonSchema = content["application/json"]?.schema as Record<string, unknown> | undefined
-		if (!jsonSchema) return "json.RawMessage"
-		if (jsonSchema.$ref) {
-			return goPascal((jsonSchema.$ref as string).split("/").pop() ?? "")
-		}
-		if (jsonSchema.type === "array" && jsonSchema.items) {
-			const items = jsonSchema.items as Record<string, unknown>
-			if (items.$ref) {
-				return `[]${goPascal((items.$ref as string).split("/").pop() ?? "")}`
-			}
-			return `[]${renderUse(items, { decls: new Map(), fieldName: "item", parentName: "Body" })}`
-		}
-		if (jsonSchema.type === "string") return "string"
-		if (jsonSchema.type === "integer") return "int64"
-		if (jsonSchema.type === "number") return "float64"
-		if (jsonSchema.type === "boolean") return "bool"
-		return "json.RawMessage"
-	}
-	return "json.RawMessage"
-}
-
-/** Extracts the Go input type (request body schema name) for an operation. */
-function goBodyType(op: Record<string, unknown>): string | null {
-	const requestBody = op.requestBody as Record<string, unknown> | undefined
-	if (!requestBody) return null
-	const content = requestBody.content as Record<string, Record<string, unknown>> | undefined
-	if (!content) return null
-	const jsonContent = content["application/json"]
-	if (!jsonContent?.schema) return null
-	const schema = jsonContent.schema as Record<string, unknown>
-	if (schema.$ref) {
-		return goPascal((schema.$ref as string).split("/").pop() ?? "")
-	}
-	return "json.RawMessage"
-}
+/* ── naming ── */
 
-/** True iff operation declares `application/octet-stream` request body. */
-function hasOctetStreamBody(op: Record<string, unknown>): boolean {
-	const requestBody = op.requestBody as Record<string, unknown> | undefined
-	const content = requestBody?.content as Record<string, unknown> | undefined
-	return content !== undefined && "application/octet-stream" in content
+/** Package-level names for one generated SDK. */
+export type GoNames = {
+	scope: NameScope
+	types: GoTypeNames
+	hoistedDecls: Map<string, string>
 }
 
-type QueryParam = {
-	name: string
-	required: boolean
-	schema: Record<string, unknown>
+export function buildGoNames(model: SdkModel): GoNames {
+	const scope = new NameScope([...goRuntimeIdentifiers(), ...GO_PREDECLARED, "Client", "NewClient", "serviceEntry"])
+	const schemaNames = new Map<string, string>()
+	/* schemas first: a schema keeps its own name unless the runtime owns it */
+	for (const name of model.schemaNames) {
+		const base = goExported(name)
+		schemaNames.set(name, scope.has(base) ? scope.claim(`${base}Model`) : scope.claim(base))
+	}
+	const hoistKeys = new Map<string, string>()
+	const types: GoTypeNames = {
+		claimConst: (base) => scope.claim(base),
+		cyclic: valueCycleSchemas(model.ir.schemas),
+		hoist: (key, base) => {
+			const hit = hoistKeys.get(key)
+			if (hit) return hit
+			const name = scope.claim(base)
+			hoistKeys.set(key, name)
+			return name
+		},
+		ref: (name) => schemaNames.get(name) ?? goExported(name),
+		resolve: model.resolve,
+	}
+	return { hoistedDecls: new Map(), scope, types }
 }
 
-/**
- * Produces a Go expression that converts a query-param value to `string`,
- * suitable as the 2nd argument of `url.Values.Set`. Nullable fields should
- * already be dereferenced by the caller — `varExpr` is the concrete value.
- */
-function qpStringExpr(varExpr: string, schema: Record<string, unknown>): string {
-	if (isStringEnum(schema)) return `string(${varExpr})`
-	const t = schema.type
-	if (t === "integer") return `strconv.FormatInt(${varExpr}, 10)`
-	if (t === "number") return `strconv.FormatFloat(${varExpr}, 'f', -1, 64)`
-	if (t === "boolean") return `strconv.FormatBool(${varExpr})`
-	return varExpr
-}
+/* ── buildGoTypes ── */
 
-function queryParamsNeedStrconv(methods: MethodInfo[]): boolean {
-	for (const m of methods) {
-		for (const qp of m.queryParams) {
-			const t = qp.schema.type
-			if (t === "integer" || t === "number" || t === "boolean") return true
-		}
+function buildGoTypes(model: SdkModel, names: GoNames): string {
+	const body: string[] = []
+	const decls = names.hoistedDecls
+	for (const name of model.schemaNames) {
+		const ir = model.ir.schemas[name]
+		const goName = names.types.ref(name)
+		const description = Object.hasOwn(model.ir.schemaDescriptions, name) ? model.ir.schemaDescriptions[name] : ""
+		if (description) body.push(...goComment(description))
+		body.push(irRenderTopLevel(goName, ir, decls, undefined, names.types))
+		body.push(``)
 	}
-	return false
+	return body.join("\n")
 }
 
-function getQueryParams(op: Record<string, unknown>): QueryParam[] {
-	const parameters = op.parameters as Array<Record<string, unknown>> | undefined
-	if (!parameters) return []
-	return parameters
-		.filter((p) => p.in === "query")
-		.map((p) => ({
-			name: String(p.name),
-			required: p.required === true,
-			schema: (p.schema as Record<string, unknown>) ?? { type: "string" },
-		}))
-		.sort((a, b) => a.name.localeCompare(b.name))
+function hoistedDeclsSource(decls: Map<string, string>): string {
+	const out: string[] = []
+	for (const name of [...decls.keys()].sort(cmpCodeUnit)) {
+		const decl = decls.get(name)
+		if (!decl) continue
+		out.push(decl)
+		out.push(``)
+	}
+	return out.join("\n")
 }
 
-/* ── buildGoTypes ── */
-
-/* Schema names defined in the Go runtime files — skip them to avoid redeclaration. */
-const GO_RUNTIME_TYPES = new Set([
-	"APIError",
-	"BadGatewayError",
-	"BadRequestError",
-	"Config",
-	"ConflictError",
-	"ConnectionState",
-	"ForbiddenError",
-	"GatewayTimeoutError",
-	"InternalServerError",
-	"InvalidationConfig",
-	"LongpollTransport",
-	"NotFoundError",
-	"RateLimitError",
-	"RequestMeta",
-	"ResumableConnection",
-	"SDKResult",
-	"SSEEvent",
-	"ServiceUnavailableError",
-	"SseTransport",
-	"StaleTracker",
-	"StatusError",
-	"StatusErrorMeta",
-	"Transport",
-	"TransportConn",
-	"TransportKind",
-	"TransportOpts",
-	"TypedWebSocket",
-	"UnauthorizedError",
-	"UnprocessableEntityError",
-	"WsTransport",
-])
-
-function buildGoTypes(spec: OpenApiSpec): string {
-	const schemas = spec.components?.schemas ?? {}
+/** types.go: component schemas, then every hoisted declaration (call after the client is planned). */
+function typesFile(schemaTypes: string, names: GoNames): string {
+	const body = `${schemaTypes}\n${hoistedDeclsSource(names.hoistedDecls)}`
 	const l: string[] = []
 	/* blank line after generator header detaches it from package-doc on pkg.go.dev */
 	l.push(`// Code generated by honey. DO NOT EDIT.`)
 	l.push(``)
 	l.push(`package sdk`)
 	l.push(``)
-
-	const sortedSchemas = Object.entries(schemas)
-		.filter(([name]) => !GO_RUNTIME_TYPES.has(name))
-		.sort(([a], [b]) => a.localeCompare(b))
-	const body: string[] = []
-	const decls = new Map<string, string>()
-	for (const [name, schema] of sortedSchemas) {
-		const goType = renderTopLevel(name, schema, decls)
-		body.push(goType)
-		body.push(``)
-	}
-	/* append hoisted enum decls (deduped by name) after top-level types */
-	const hoistedNames = [...decls.keys()].sort((a, b) => a.localeCompare(b))
-	for (const hname of hoistedNames) {
-		body.push(decls.get(hname) as string)
-		body.push(``)
-	}
-
-	/* emit encoding/json import only when generated type bodies actually use it
-	 * (json.RawMessage, json.Unmarshal, etc). Keeps types.go compilable whether
-	 * schemas produced additionalProperties helpers or not. */
-	const bodyStr = body.join("\n")
-	if (bodyStr.includes("json.RawMessage") || bodyStr.includes("json.Unmarshal") || bodyStr.includes("json.Marshal")) {
+	if (/\bjson\./.test(body)) {
 		l.push(`import "encoding/json"`)
 		l.push(``)
 	}
-	l.push(bodyStr)
-
+	l.push(body)
 	return l.join("\n")
 }
 
@@ -313,15 +226,14 @@ function buildGoTypes(spec: OpenApiSpec): string {
 
 function buildGoMod(modulePath?: string): string {
 	const mod = modulePath ?? "example.com/sdk"
-	return [`module ${mod}`, ``, `go 1.23`, ``, `require nhooyr.io/websocket v1.8.17`, ``].join("\n")
+	return [`module ${mod}`, ``, `go 1.24`, ``, `require nhooyr.io/websocket v1.8.17`, ``].join("\n")
 }
 
 /* ── buildGoDoc ── */
 
-function buildGoDoc(spec: OpenApiSpec): string {
-	const title = spec.info.title
-	const desc = spec.info.description
-	const descSuffix = desc ? ` ${desc}` : ""
+function buildGoDoc(info: IRInfo): string {
+	const title = info.title ?? "API"
+	const desc = info.description ?? ""
 	/* Generator directive on its own line, separated from package-doc by blank
 	 * line so pkg.go.dev does not aggregate "Code generated..." into Overview.
 	 * The `// Package sdk ...` line IS attached to `package sdk` (no blank line
@@ -329,7 +241,7 @@ function buildGoDoc(spec: OpenApiSpec): string {
 	const l: string[] = []
 	l.push(`// Code generated by honey. DO NOT EDIT.`)
 	l.push(``)
-	l.push(`// Package sdk is an auto-generated client for ${title}.${descSuffix}`)
+	l.push(...goComment(`Package sdk is an auto-generated client for ${title}.${desc ? ` ${desc}` : ""}`))
 	l.push(`package sdk`)
 	l.push(``)
 	return l.join("\n")
@@ -337,471 +249,389 @@ function buildGoDoc(spec: OpenApiSpec): string {
 
 /* ── buildGoClient ── */
 
-type MethodInfo = {
-	/* first segment of operationId — used as invalidationMap key */
-	resource: string
-	/* segments[1..] joined with "." — used as invalidationMap action key */
-	action: string
-	/* all segments except last — namespace path for struct name generation */
-	namePath: string[]
-	/* last segment of operationId — used for the Go method name */
-	methodAction: string
-	bodyIsStream: boolean
-	bodyType: string | null
-	description: string
-	httpMethod: string
-	isIdempotent: boolean
-	isRealtime: boolean
-	isSSE: boolean
-	isWS: boolean
-	op: Record<string, unknown>
-	opId: string
-	path: string
-	pathParams: string[]
-	queryParams: QueryParam[]
-	responseType: string
-	summary: string
-	/* Override for the Pascal-cased method/opts name. Set when a top-level
-	 * operation's resource name collides with an existing resource bucket,
-	 * so the emitted `Client` doesn't have a same-named field + method. */
-	methodNameOverride?: string
-}
-
-/** Build a MethodInfo from an IROperation + the raw spec op object. */
-function methodInfoFromIROp(irOp: IROperation, rawOp: Record<string, unknown>): MethodInfo {
-	const segments = irOp.id.split(".")
-	const isTopLevel = segments.length === 1
-	const resource = segments[0] ?? irOp.id
-	const action = isTopLevel ? "_call" : segments.slice(1).join(".")
-	const namePath = segments.slice(0, -1)
-	const methodAction = segments[segments.length - 1] ?? irOp.id
-	const isRealtime = rawOp["x-realtime"] === true
-	return {
-		action,
-		bodyIsStream: hasOctetStreamBody(rawOp),
-		bodyType: goBodyType(rawOp),
-		description: String(rawOp.description ?? ""),
-		httpMethod: irOp.method,
-		isIdempotent: rawOp["x-idempotency-key"] === true,
-		isRealtime,
-		isSSE: !isRealtime && isSSEOperation(rawOp),
-		isWS: !isRealtime && rawOp["x-websocket"] === true,
-		methodAction,
-		namePath,
-		op: rawOp,
-		opId: irOp.id,
-		path: irOp.path,
-		pathParams: irOp.params.path.map((p) => p.name),
-		queryParams: getQueryParams(rawOp),
-		resource,
-		responseType: goResponseType(rawOp),
-		summary: String(rawOp.summary ?? ""),
-	}
-}
-
-/** Walk the IR tree and collect all MethodInfos, pairing with raw spec ops. */
-function collectMethodsFromIR(ns: IRNamespace, spec: OpenApiSpec): MethodInfo[] {
-	const rawOpById = new Map<string, Record<string, unknown>>()
-	for (const [, pathMethods] of Object.entries(spec.paths ?? {})) {
-		for (const [, operation] of Object.entries(pathMethods)) {
-			const op = operation as Record<string, unknown>
-			const id = op.operationId as string | undefined
-			if (id) rawOpById.set(id, op)
-		}
-	}
-
-	const results: MethodInfo[] = []
-
-	function walk(cur: IRNamespace): void {
-		for (const [, entry] of methodsOf(cur)) {
-			const raw = rawOpById.get(entry.id) ?? {}
-			results.push(methodInfoFromIROp(entry, raw))
-		}
-		for (const [, childNs] of namespacesOf(cur)) {
-			walk(childNs)
-		}
-	}
-
-	walk(ns)
-	return results
+type GoOpPlan = {
+	op: SdkOp
+	methodName: string
+	optsName: string
+	/** opts struct field per query/header param */
+	optFields: Array<{ goName: string; type: string; param: { name: string }; where: "query" | "header" }>
+	/** local identifier per path param */
+	pathLocals: Array<{ local: string; name: string }>
+	bodyParam?: { local: string; type: string }
+	multipartName?: string
+	multipartFields?: Array<{
+		goName: string
+		type: string
+		key: string
+		file: boolean
+		list: boolean
+		required: boolean
+	}>
+	/** Go type returned on success, "" for none */
+	resultType: string
 }
 
-function buildGoClient(spec: OpenApiSpec, options: GoSDKOptions): string {
-	const throwOnError = options.throwOnError ?? true
-
-	/* toIR validates operationId collisions — throws before any codegen runs */
-	const ir = toIR(spec as Parameters<typeof toIR>[0])
-	const methods = collectMethodsFromIR(ir.tree, spec)
-
-	/* top-level single-segment ops (action === "_call") emit as methods on *Client */
-	const topLevel: MethodInfo[] = methods.filter((m) => m.action === "_call")
-	/* collect root namespace names to detect field/method name collision */
-	const rootNsNames = new Set(namespacesOf(ir.tree).map(([seg]) => safeResourceName(seg)))
-
-	/* top-level op whose resource name collides with a root namespace field needs a
-	 * unique method name — Go forbids struct field + method sharing a name.
-	 * Suffix with "Call": extract + extract.table → Extract field + ExtractCall method. */
-	for (const m of topLevel) {
-		if (rootNsNames.has(safeResourceName(m.resource))) {
-			m.methodNameOverride = `${goPascal(m.resource)}Call`
-		}
-	}
-
-	const hasWS = methods.some((m) => m.isWS)
-
-	/* collect invalidation data for map */
-	const serviceMap = collectSDKMethods(spec as Parameters<typeof collectSDKMethods>[0]).serviceMap
-
-	const body: string[] = []
-
-	/* serviceEntry struct */
-	body.push(`type serviceEntry struct {`)
-	body.push(`\tMethod     string`)
-	body.push(`\tPath       string`)
-	body.push(`\tParams     []string`)
-	body.push(`\tSSE        bool`)
-	body.push(`\tWS         bool`)
-	body.push(`\tInvalidate []string`)
-	body.push(`}`)
-	body.push(``)
-
-	/* invalidationMap */
-	body.push(`var invalidationMap = map[string]map[string]serviceEntry{`)
-	for (const [resource, actions] of Object.entries(serviceMap).sort(([a], [b]) => a.localeCompare(b))) {
-		body.push(`\t"${resource}": {`)
-		for (const [action, entry] of Object.entries(actions as Record<string, Record<string, unknown>>).sort(([a], [b]) =>
-			a.localeCompare(b),
-		)) {
-			const inv = entry.invalidate as string[] | undefined
-			const invStr = inv && inv.length > 0 ? `[]string{${inv.map((s) => JSON.stringify(s)).join(", ")}}` : `nil`
-			const params = entry.params as string[] | undefined
-			const paramsStr =
-				params && params.length > 0 ? `[]string{${params.map((s) => JSON.stringify(s)).join(", ")}}` : `nil`
-			body.push(
-				`\t\t"${action}": {Method: ${JSON.stringify(String(entry.method))}, Path: ${JSON.stringify(String(entry.path))}, Params: ${paramsStr}, SSE: ${entry.sse === true}, WS: ${entry.ws === true}, Invalidate: ${invStr}},`,
-			)
+const OPTS_RESERVED = [
+	"Headers",
+	"IdempotencyKey",
+	"LastEventID",
+	"ReconnectToken",
+	"Protocols",
+	"MaxReconnectAttempts",
+	"ReconnectDelayMs",
+]
+
+/** Locals every emitted method body uses. Path params must not shadow them. */
+const METHOD_LOCALS = [
+	"ctx",
+	"opts",
+	"q",
+	"path",
+	"err",
+	"result",
+	"out",
+	"resp",
+	"req",
+	"reqBody",
+	"callHeaders",
+	"pathParams",
+	"concretePath",
+	"selector",
+	"requestMeta",
+	"stale",
+	"cfg",
+	"yield",
+	"ev",
+	"conn",
+	"dialOpts",
+	"wsURL",
+	"transports",
+	"topts",
+	"parts",
+	"c",
+	"r",
+]
+
+function planOp(op: SdkOp, methodName: string, optsName: string, names: GoNames): GoOpPlan {
+	const plan: GoOpPlan = { methodName, op, optFields: [], optsName, pathLocals: [], resultType: "" }
+
+	const locals = new NameScope(METHOD_LOCALS)
+	const bodyLocal =
+		op.body && op.stream !== "ws" && op.stream !== "realtime"
+			? locals.claim(op.body.kind === "form" ? "form" : "body")
+			: ""
+	for (const p of op.pathParams) plan.pathLocals.push({ local: locals.claim(goLocal(p.name)), name: p.name })
+
+	if (op.stream !== "realtime") {
+		const fieldScope = new NameScope(OPTS_RESERVED)
+		const decls = names.hoistedDecls
+		const params: Array<[{ name: string; schema: IRSchema; required?: boolean }, "query" | "header"]> = [
+			...op.query.map((p): [typeof p, "query"] => [p, "query"]),
+			...op.headers.map((p): [typeof p, "header"] => [p, "header"]),
+		]
+		for (const [p, where] of params) {
+			if (op.stream === "sse" && where === "query" && /^last[-_]?event[-_]?id$/i.test(p.name)) continue
+			const goName = fieldScope.claim(goExported(p.name))
+			const ctx: RenderUseCtx = { decls, fieldName: goName, names: names.types, parentName: optsName }
+			const t = irRenderUse(p.schema, ctx)
+			const nilable = t.startsWith("*") || t.startsWith("[]") || t.startsWith("map[") || t === "json.RawMessage"
+			plan.optFields.push({ goName, param: p, type: p.required || nilable ? t : `*${t}`, where })
 		}
-		body.push(`\t},`)
 	}
-	body.push(`}`)
-	body.push(``)
 
-	/* ---- Client struct: cfg + stale + one field per root namespace ---- */
-	body.push(`// Client is the generated SDK client.`)
-	body.push(`type Client struct {`)
-	body.push(`\tcfg   Config`)
-	body.push(`\tstale *StaleTracker`)
-	for (const [seg] of namespacesOf(ir.tree)) {
-		const safeName = safeResourceName(seg)
-		body.push(`\t${goPascal(safeName)} *${nestedStructName([safeName])}`)
-	}
-	body.push(`}`)
-	body.push(``)
-
-	/* ---- NewClient: init + cascade nested struct init ---- */
-	const auth = detectAuthScheme(spec)
-	body.push(`// NewClient creates a new SDK client. BaseURL must be non-empty.`)
-	body.push(`func NewClient(cfg Config) *Client {`)
-	body.push(`\tif cfg.BaseURL == "" {`)
-	body.push(`\t\tpanic("honey sdk: Config.BaseURL must not be empty")`)
-	body.push(`\t}`)
-	body.push(`\tif cfg.HTTPClient == nil {`)
-	body.push(`\t\tcfg.HTTPClient = &http.Client{Timeout: 30 * time.Second}`)
-	body.push(`\t}`)
-	body.push(`\tif cfg.AuthHeaderName == "" {`)
-	body.push(`\t\tcfg.AuthHeaderName = ${JSON.stringify(auth.headerName)}`)
-	body.push(`\t}`)
-	body.push(`\tif cfg.AuthHeaderPrefix == "" {`)
-	body.push(`\t\tcfg.AuthHeaderPrefix = ${JSON.stringify(auth.prefix)}`)
-	body.push(`\t}`)
-	body.push(`\tc := &Client{cfg: cfg}`)
-	body.push(`\tc.stale = NewStaleTracker(cfg.Invalidation)`)
-	/* emit a helper fn per root namespace that inits itself + its children,
-	 * then assign: c.Checkout = newCheckoutResource(c) */
-	for (const [seg] of namespacesOf(ir.tree)) {
-		const safeName = safeResourceName(seg)
-		body.push(`\tc.${goPascal(safeName)} = new${nestedStructName([safeName])}(c)`)
-	}
-	body.push(`\treturn c`)
-	body.push(`}`)
-	body.push(``)
-
-	/* IsStale predicate */
-	body.push(`// IsStale reports whether (method, path) currently sits inside an active stale window.`)
-	body.push(`func (c *Client) IsStale(method, path string) bool {`)
-	body.push(`\tif c.stale == nil { return false }`)
-	body.push(`\treturn c.stale.IsStale(method, path)`)
-	body.push(`}`)
-	body.push(``)
-
-	/* top-level single-segment methods on *Client */
-	for (const m of topLevel.sort((a, b) => a.resource.localeCompare(b.resource))) {
-		body.push(...emitMethod(m, "c", "*Client", throwOnError))
-	}
-
-	/* ---- recursive resource struct + method emission ---- */
-	function emitResourceStructs(ns: IRNamespace, path: string[]): void {
-		const structName = nestedStructName(path)
-		const recvName = path[path.length - 1]?.[0]?.toLowerCase() ?? "r"
-
-		/* struct definition: client pointer + one field per child namespace */
-		body.push(`type ${structName} struct {`)
-		body.push(`\tclient *Client`)
-		for (const [childSeg] of namespacesOf(ns)) {
-			const safeSeg = safeResourceName(childSeg)
-			body.push(`\t${goPascal(safeSeg)} *${nestedStructName([...path, safeSeg])}`)
-		}
-		body.push(`}`)
-		body.push(``)
-
-		/* constructor helper: newXResource(c) sets client + child fields */
-		body.push(`func new${structName}(c *Client) *${structName} {`)
-		body.push(`\tr := &${structName}{client: c}`)
-		for (const [childSeg] of namespacesOf(ns)) {
-			const safeSeg = safeResourceName(childSeg)
-			body.push(`\tr.${goPascal(safeSeg)} = new${nestedStructName([...path, safeSeg])}(c)`)
-		}
-		body.push(`\treturn r`)
-		body.push(`}`)
-		body.push(``)
-
-		/* direct methods on this struct */
-		for (const [, op] of methodsOf(ns)) {
-			const raw =
-				methods.find((m) => m.opId === op.id) ??
-				(() => {
-					throw new Error(`missing MethodInfo for ${op.id}`)
-				})()
-			body.push(...emitMethod(raw, recvName, `*${structName}`, throwOnError))
-		}
-
-		/* recurse into child namespaces */
-		for (const [childSeg, childNs] of namespacesOf(ns)) {
-			emitResourceStructs(childNs, [...path, safeResourceName(childSeg)])
+	const body = op.body
+	if (body && op.stream !== "ws" && op.stream !== "realtime") {
+		const local = bodyLocal
+		switch (body.kind) {
+			case "json": {
+				const resolved = body.schema
+				let t: string
+				if (resolved.kind === "ref") t = names.types.ref(resolved.name)
+				else if (resolved.kind === "object" && resolved.fields.length > 0) {
+					const name = names.types.hoist(`${op.id}.body`, `${optsName.replace(/Opts$/, "")}Body`)
+					if (!names.hoistedDecls.has(name)) {
+						names.hoistedDecls.set(name, "")
+						names.hoistedDecls.set(name, irRenderTopLevel(name, resolved, names.hoistedDecls, undefined, names.types))
+					}
+					t = name
+				} else {
+					t = irRenderUse(resolved, {
+						decls: names.hoistedDecls,
+						fieldName: "Body",
+						names: names.types,
+						parentName: optsName.replace(/Opts$/, ""),
+					})
+				}
+				plan.bodyParam = { local, type: t }
+				break
+			}
+			case "form":
+				plan.bodyParam = { local, type: "url.Values" }
+				break
+			case "binary":
+				plan.bodyParam = { local, type: "io.Reader" }
+				break
+			case "text":
+				plan.bodyParam = { local, type: "string" }
+				break
+			case "multipart": {
+				const name = names.types.hoist(`${op.id}.multipart`, `${optsName.replace(/Opts$/, "")}Body`)
+				const fieldScope = new NameScope()
+				plan.multipartName = name
+				plan.multipartFields = body.parts.map((part) => {
+					const goName = fieldScope.claim(goExported(part.name))
+					const schema = part.schema ? names.types.resolve(part.schema) : { kind: "unknown" as const }
+					const list = schema.kind === "array"
+					if (part.type === "file") {
+						return { file: true, goName, key: part.name, list, required: true, type: list ? "[]FilePart" : "FilePart" }
+					}
+					const item = list && schema.kind === "array" ? schema.items : schema
+					let t = "string"
+					if (item.kind === "scalar") {
+						t =
+							item.type === "integer"
+								? "int64"
+								: item.type === "number"
+									? "float64"
+									: item.type === "boolean"
+										? "bool"
+										: "string"
+					}
+					return { file: false, goName, key: part.name, list, required: false, type: list ? `[]${t}` : `*${t}` }
+				})
+				plan.bodyParam = { local, type: name }
+				break
+			}
 		}
 	}
 
-	for (const [seg, ns] of namespacesOf(ir.tree)) {
-		emitResourceStructs(ns, [safeResourceName(seg)])
-	}
-
-	/* opts structs — emit once per unique opts name, sorted by opId */
-	const optsEmitted = new Set<string>()
-	for (const m of methods.sort((a, b) => a.opId.localeCompare(b.opId))) {
-		const optsName = optsStructName(m)
-		if (optsEmitted.has(optsName)) continue
-		optsEmitted.add(optsName)
-		body.push(...emitOptsStruct(m))
-	}
-
-	const bodyStr = body.join("\n")
-
-	const hasSSE = methods.some((m) => m.isSSE)
-	const stdlib = ["context", "encoding/json", "fmt", "io", "net/http", "net/url", "strings", "sync", "time"]
-	if (hasSSE) stdlib.push("iter")
-	if (queryParamsNeedStrconv(methods)) stdlib.push("strconv")
-	const thirdParty = hasWS ? ["nhooyr.io/websocket"] : []
-
-	/* emit a `var _ = <symbol>` suppression only for stdlib imports the body
-	 * does not already reference, so unused-import compile errors are avoided
-	 * without polluting generated code with dead suppressions. */
-	const suppressions: { line: string; symbol: string }[] = [
-		{ line: `var _ json.RawMessage`, symbol: "json." },
-		{ line: `var _ = fmt.Sprintf`, symbol: "fmt." },
-		{ line: `var _ = io.Discard`, symbol: "io." },
-		{ line: `var _ *url.URL`, symbol: "url." },
-		{ line: `var _ = strings.NewReader`, symbol: "strings." },
-		{ line: `var _ = sync.Mutex{}`, symbol: "sync." },
-		{ line: `var _ = time.Second`, symbol: "time." },
-	]
-	const suppressionLines = suppressions.filter((s) => !bodyStr.includes(s.symbol)).map((s) => s.line)
-
-	const out: string[] = []
-	/* blank line after generator header detaches it from package-doc on pkg.go.dev */
-	out.push(`// Code generated by honey. DO NOT EDIT.`)
-	out.push(``)
-	out.push(`package sdk`)
-	out.push(``)
-	out.push(goImportBlock([...new Set(stdlib)].sort(), thirdParty))
-	out.push(``)
-	if (suppressionLines.length > 0) {
-		out.push(...suppressionLines)
-		out.push(``)
+	if (op.stream === null) {
+		const s = op.success
+		if (s.kind === "json") {
+			if (!s.schema) plan.resultType = "json.RawMessage"
+			else if (s.schema.kind === "ref") plan.resultType = names.types.ref(s.schema.name)
+			else if (s.schema.kind === "object" && s.schema.fields.length > 0) {
+				const name = names.types.hoist(`${op.id}.response`, `${optsName.replace(/Opts$/, "")}Response`)
+				if (!names.hoistedDecls.has(name)) {
+					names.hoistedDecls.set(name, "")
+					names.hoistedDecls.set(name, irRenderTopLevel(name, s.schema, names.hoistedDecls, undefined, names.types))
+				}
+				plan.resultType = name
+			} else {
+				const t = irRenderUse(s.schema, {
+					decls: names.hoistedDecls,
+					fieldName: "Response",
+					names: names.types,
+					parentName: optsName.replace(/Opts$/, ""),
+				})
+				plan.resultType = t.startsWith("*") ? t.slice(1) : t
+			}
+		} else if (s.kind === "text") plan.resultType = "string"
+		else if (s.kind === "binary") plan.resultType = "[]byte"
 	}
-	out.push(bodyStr)
-	return out.join("\n")
-}
-
-function optsStructName(m: MethodInfo): string {
-	if (m.methodNameOverride) return `${m.methodNameOverride}Opts`
-	/* For top-level single-segment ops: namePath=[], methodAction=opId → e.g. GetUserOpts
-	 * For multi-segment: namePath=[checkout,sessions], methodAction=create → CheckoutSessionsCreateOpts */
-	const prefix = m.namePath.map(goPascal).join("")
-	const suffix = goPascal(m.methodAction)
-	return `${prefix}${suffix}Opts`
+	return plan
 }
 
-function emitOptsStruct(m: MethodInfo): string[] {
+function emitOptsStruct(plan: GoOpPlan): string[] {
 	const l: string[] = []
-	const optsName = optsStructName(m)
-	if (m.isRealtime) {
-		/* realtime ops get a fixed opts shape — no generated query fields;
-		 * transports receive ReconnectToken / LastEventID via TransportOpts. */
+	const { op, optsName } = plan
+	l.push(`// ${optsName} holds the optional inputs of ${plan.methodName}.`)
+	if (op.stream === "realtime") {
+		/* realtime ops get a fixed opts shape — transports receive
+		 * ReconnectToken / LastEventID via TransportOpts. */
 		l.push(`type ${optsName} struct {`)
 		l.push(`\tReconnectToken string`)
 		l.push(`\tLastEventID string`)
 		l.push(`\tProtocols []string`)
+		l.push(`\t// MaxReconnectAttempts caps reconnects after a drop. Zero means 5; negative means unlimited.`)
 		l.push(`\tMaxReconnectAttempts int`)
+		l.push(`\t// ReconnectDelayMs is the first backoff delay. Zero means 1000.`)
 		l.push(`\tReconnectDelayMs int`)
 		l.push(`\tHeaders map[string]string`)
 		l.push(`}`)
 		l.push(``)
 		return l
 	}
-	const decls = new Map<string, string>()
-	const fields: string[] = []
-	for (const qp of m.queryParams) {
-		const fieldName = goPascal(qp.name)
-		const goType = renderUse(qp.schema, {
-			decls,
-			fieldName: qp.name,
-			parentName: optsName,
-		})
-		const ptr = qp.required ? goType : `*${goType}`
-		fields.push(`\t${fieldName} ${ptr}`)
-	}
-	/* hoisted query-param enums emit before the opts struct so refs resolve */
-	for (const decl of decls.values()) {
-		l.push(decl)
-		l.push(``)
-	}
 	l.push(`type ${optsName} struct {`)
-	l.push(...fields)
-	if (m.isSSE) {
-		l.push(`\tLastEventID string`)
-	}
-	if (m.isWS) {
+	for (const f of plan.optFields) l.push(`\t${f.goName} ${f.type}`)
+	if (op.stream === "sse") l.push(`\tLastEventID string`)
+	if (op.stream === "ws") {
 		l.push(`\tReconnectToken string`)
 		l.push(`\tProtocols []string`)
 	}
-	if (m.isIdempotent && !m.isRealtime && !m.isSSE && !m.isWS) {
-		l.push(`\tIdempotencyKey string`)
-	}
+	if (op.idempotent && op.stream === null) l.push(`\tIdempotencyKey string`)
 	l.push(`\tHeaders map[string]string`)
 	l.push(`}`)
 	l.push(``)
 	return l
 }
 
-function emitMethod(m: MethodInfo, recv: string, recvType: string, throwOnError: boolean): string[] {
+function emitMultipartStruct(plan: GoOpPlan): string[] {
+	if (!plan.multipartName || !plan.multipartFields) return []
 	const l: string[] = []
-	/* top-level single-segment ops (action === "_call") use resource as the method name */
-	const actionPascal = m.methodNameOverride ?? goPascal(m.action === "_call" ? m.resource : m.methodAction)
-	const optsName = optsStructName(m)
-	const httpMethod = m.httpMethod
-	const pathStr = m.path
-
-	/* godoc */
-	if (m.summary) {
-		l.push(`// ${actionPascal} — ${m.summary}`)
-		if (m.description) l.push(`// ${m.description}`)
+	l.push(`// ${plan.multipartName} is the multipart/form-data body of ${plan.methodName}.`)
+	l.push(`type ${plan.multipartName} struct {`)
+	for (const f of plan.multipartFields) l.push(`\t${f.goName} ${f.type}`)
+	l.push(`}`)
+	l.push(``)
+	return l
+}
+
+function pathExpr(plan: GoOpPlan): string {
+	if (plan.pathLocals.length === 0) return ""
+	return `map[string]string{${plan.pathLocals.map((p) => `${goString(p.name)}: ${p.local}`).join(", ")}}`
+}
+
+/** Lines that compute `path` (and return on error through `fail`). */
+function emitPath(plan: GoOpPlan, fail: string, indent: string): string[] {
+	const l: string[] = []
+	if (plan.pathLocals.length === 0) {
+		l.push(`${indent}path := ${goString(plan.op.path)}`)
+		return l
 	}
+	l.push(`${indent}path, err := expandPath(${goString(plan.op.path)}, ${pathExpr(plan)})`)
+	l.push(`${indent}if err != nil {`)
+	l.push(`${indent}\t${fail}`)
+	l.push(`${indent}}`)
+	return l
+}
 
-	/* signature */
-	const params: string[] = [`ctx context.Context`]
-	for (const pp of m.pathParams) params.push(`${pp} string`)
-	if (m.bodyIsStream) params.push(`body io.Reader`)
-	else if (m.bodyType) params.push(`body ${m.bodyType}`)
+/** Lines that build `q` and `callHeaders` from opts. */
+function emitQueryAndHeaders(plan: GoOpPlan, indent: string, baseHeaders: string): string[] {
+	const l: string[] = []
+	l.push(`${indent}var q queryList`)
+	l.push(`${indent}callHeaders := ${baseHeaders}`)
+	l.push(`${indent}if opts != nil {`)
+	for (const f of plan.optFields) {
+		if (f.where === "query") l.push(`${indent}\tq.set(${goString(f.param.name)}, opts.${f.goName})`)
+	}
+	l.push(`${indent}\tfor k, v := range opts.Headers {`)
+	l.push(`${indent}\t\tcallHeaders[k] = v`)
+	l.push(`${indent}\t}`)
+	for (const f of plan.optFields) {
+		if (f.where === "header")
+			l.push(`${indent}\tsetHeaderValue(callHeaders, ${goString(f.param.name)}, opts.${f.goName})`)
+	}
+	l.push(`${indent}}`)
+	return l
+}
 
-	let ret: string
-	if (m.isRealtime) {
-		params.push(`opts *${optsName}`)
-		ret = `*ResumableConnection`
-	} else if (m.isSSE) {
-		params.push(`opts *${optsName}`)
-		ret = `iter.Seq2[SSEEvent, error]`
-	} else if (m.isWS) {
-		params.push(`opts *${optsName}`)
-		ret = `(*TypedWebSocket, error)`
-	} else if (throwOnError) {
-		params.push(`opts *${optsName}`)
-		ret = m.responseType !== "" ? `(*${m.responseType}, error)` : `error`
-	} else {
-		params.push(`opts *${optsName}`)
-		ret = m.responseType !== "" ? `(SDKResult[${m.responseType}], error)` : `error`
+/** Expression for the request body, plus setup lines. */
+function emitBody(plan: GoOpPlan, fail: string, indent: string): { lines: string[]; expr: string } {
+	const body = plan.op.body
+	const local = plan.bodyParam?.local
+	if (!body || !local) return { expr: "noBody()", lines: [] }
+	switch (body.kind) {
+		case "json":
+			return { expr: `jsonBody(${local})`, lines: [] }
+		case "form":
+			return { expr: `formBody(${local})`, lines: [] }
+		case "text":
+			return { expr: `rawBody([]byte(${local}), ${goString(body.contentType)})`, lines: [] }
+		case "binary":
+			return { expr: `readerBody(${local}, ${goString(body.contentType)})`, lines: [] }
+		case "multipart": {
+			const l: string[] = []
+			l.push(`${indent}var parts []multipartField`)
+			for (const f of plan.multipartFields ?? []) {
+				if (f.file) {
+					if (f.list) {
+						l.push(`${indent}for _, file := range ${local}.${f.goName} {`)
+						l.push(`${indent}\tparts = append(parts, fileField(${goString(f.key)}, file))`)
+						l.push(`${indent}}`)
+					} else {
+						l.push(`${indent}parts = append(parts, fileField(${goString(f.key)}, ${local}.${f.goName}))`)
+					}
+				} else if (f.list) {
+					l.push(`${indent}for _, v := range ${local}.${f.goName} {`)
+					l.push(`${indent}\tparts = append(parts, textField(${goString(f.key)}, v))`)
+					l.push(`${indent}}`)
+				} else {
+					l.push(`${indent}if ${local}.${f.goName} != nil {`)
+					l.push(`${indent}\tparts = append(parts, textField(${goString(f.key)}, *${local}.${f.goName}))`)
+					l.push(`${indent}}`)
+				}
+			}
+			l.push(`${indent}reqBody, err := multipartBody(parts)`)
+			l.push(`${indent}if err != nil {`)
+			l.push(`${indent}\t${fail}`)
+			l.push(`${indent}}`)
+			return { expr: "reqBody", lines: l }
+		}
+	}
+}
+
+function emitDoc(plan: GoOpPlan): string[] {
+	const l: string[] = []
+	const { op } = plan
+	const text = [op.summary, op.description].filter((s) => s !== "").join("\n")
+	if (text) l.push(...goComment(`${plan.methodName} — ${text}`))
+	if (op.deprecated) {
+		if (text) l.push(`//`)
+		l.push(`// Deprecated: the API marks this operation deprecated.`)
 	}
+	return l
+}
 
-	l.push(`func (${recv} ${recvType}) ${actionPascal}(${params.join(", ")}) ${ret} {`)
+function emitMethod(plan: GoOpPlan, recv: string, recvType: string, throwOnError: boolean): string[] {
+	const l: string[] = []
+	const { op, optsName } = plan
+	const cfg = recvType === "*Client" ? `${recv}.cfg` : `${recv}.client.cfg`
+	const stale = recvType === "*Client" ? `${recv}.stale` : `${recv}.client.stale`
 
-	const httpMethodStr = httpMethod.toUpperCase()
+	l.push(...emitDoc(plan))
 
-	/* client accessor */
-	const cfgAccess = recvType === "*Client" ? `${recv}.cfg` : `${recv}.client.cfg`
-	const staleAccess = recvType === "*Client" ? `${recv}.stale` : `${recv}.client.stale`
+	const params: string[] = [`ctx context.Context`]
+	for (const p of plan.pathLocals) params.push(`${p.local} string`)
+	if (plan.bodyParam) params.push(`${plan.bodyParam.local} ${plan.bodyParam.type}`)
+	params.push(`opts *${optsName}`)
 
-	if (m.isRealtime) {
-		const urlExpr = pathToGoExpr(pathStr)
-		/* ctx is accepted for API symmetry with sibling methods but not used
-		 * here — consumer binds a ctx at ResumableConnection.Connect(ctx) time. */
+	if (op.stream === "realtime") {
+		l.push(`func (${recv} ${recvType}) ${plan.methodName}(${params.join(", ")}) (*ResumableConnection, error) {`)
+		/* ctx bounds nothing here: ResumableConnection.Connect(ctx) takes its own */
 		l.push(`\t_ = ctx`)
-		l.push(`\ttransports := []Transport{&WsTransport{}, &SseTransport{}, &LongpollTransport{}}`)
-		l.push(`\ttopts := &TransportOpts{}`)
+		l.push(...emitPath(plan, "return nil, err", "\t"))
+		l.push(`\trtURL, err := buildURL(${cfg}.BaseURL, path, nil)`)
+		l.push(`\tif err != nil {`)
+		l.push(`\t\treturn nil, err`)
+		l.push(`\t}`)
+		l.push(`\tvar extra map[string]string`)
+		l.push(`\ttopts := &TransportOpts{HTTPClient: streamClient(${cfg})}`)
 		l.push(`\tif opts != nil {`)
+		l.push(`\t\textra = opts.Headers`)
 		l.push(`\t\ttopts.ReconnectToken = opts.ReconnectToken`)
 		l.push(`\t\ttopts.LastEventID = opts.LastEventID`)
 		l.push(`\t\ttopts.Protocols = opts.Protocols`)
 		l.push(`\t\ttopts.MaxReconnectAttempts = opts.MaxReconnectAttempts`)
 		l.push(`\t\ttopts.ReconnectDelayMs = opts.ReconnectDelayMs`)
-		l.push(`\t\tif len(opts.Headers) > 0 {`)
-		l.push(`\t\t\ttopts.Headers = http.Header{}`)
-		l.push(`\t\t\tfor k, v := range opts.Headers { topts.Headers.Set(k, v) }`)
-		l.push(`\t\t}`)
 		l.push(`\t}`)
-		l.push(`\treturn NewResumableConnection(${cfgAccess}.BaseURL + ${urlExpr}, transports, topts)`)
+		l.push(`\ttopts.Headers = authHeaders(${cfg}, extra)`)
+		l.push(`\ttransports := []Transport{&WsTransport{}, &SseTransport{}, &LongpollTransport{}}`)
+		l.push(`\treturn NewResumableConnection(rtURL, transports, topts), nil`)
 		l.push(`}`)
 		l.push(``)
 		return l
 	}
 
-	if (m.isSSE) {
-		const sseQueryParams = m.queryParams.filter((qp) => qp.name !== "last-event-id")
+	if (op.stream === "sse") {
+		l.push(`func (${recv} ${recvType}) ${plan.methodName}(${params.join(", ")}) iter.Seq2[SSEEvent, error] {`)
 		l.push(`\treturn func(yield func(SSEEvent, error) bool) {`)
-		if (sseQueryParams.length > 0) {
-			l.push(`\t\tq := url.Values{}`)
-			for (const qp of sseQueryParams) {
-				const fieldName = goPascal(qp.name)
-				if (qp.required) {
-					l.push(
-						`\t\tif opts != nil { q.Set(${JSON.stringify(qp.name)}, ${qpStringExpr(`opts.${fieldName}`, qp.schema)}) }`,
-					)
-				} else {
-					l.push(
-						`\t\tif opts != nil && opts.${fieldName} != nil { q.Set(${JSON.stringify(qp.name)}, ${qpStringExpr(`*opts.${fieldName}`, qp.schema)}) }`,
-					)
-				}
-			}
-		}
-		const urlExpr = pathToGoExpr(pathStr)
-		const sseURLExpr =
-			sseQueryParams.length > 0 ? `${cfgAccess}.BaseURL+${urlExpr}+"?"+q.Encode()` : `${cfgAccess}.BaseURL+${urlExpr}`
-		l.push(`\t\tcallHeaders := map[string]string{"Accept": "text/event-stream"}`)
+		l.push(...emitPath(plan, "yield(SSEEvent{}, err)\n\t\t\treturn", "\t\t"))
+		l.push(...emitQueryAndHeaders(plan, "\t\t", `map[string]string{"Accept": "text/event-stream"}`))
 		l.push(`\t\tif opts != nil && opts.LastEventID != "" {`)
 		l.push(`\t\t\tcallHeaders["Last-Event-ID"] = opts.LastEventID`)
 		l.push(`\t\t}`)
-		l.push(`\t\tif opts != nil {`)
-		l.push(`\t\t\tfor k, v := range opts.Headers { callHeaders[k] = v }`)
+		const body = emitBody(plan, "yield(SSEEvent{}, err)\n\t\t\treturn", "\t\t")
+		l.push(...body.lines)
+		l.push(`\t\tresp, err := openStream(ctx, ${cfg}, ${goString(op.method)}, path, q, ${body.expr}, callHeaders)`)
+		l.push(`\t\tif err != nil {`)
+		l.push(`\t\t\tyield(SSEEvent{}, err)`)
+		l.push(`\t\t\treturn`)
 		l.push(`\t\t}`)
-		l.push(`\t\treq, err := http.NewRequestWithContext(ctx, "GET", ${sseURLExpr}, nil)`)
-		l.push(`\t\tif err != nil { yield(SSEEvent{}, err); return }`)
-		l.push(`\t\tfor k, v := range ${cfgAccess}.Headers { req.Header.Set(k, v) }`)
-		l.push(`\t\tfor k, v := range callHeaders { req.Header.Set(k, v) }`)
-		l.push(
-			`\t\tif ${cfgAccess}.BearerToken != "" { req.Header.Set(${cfgAccess}.AuthHeaderName, ${cfgAccess}.AuthHeaderPrefix+${cfgAccess}.BearerToken) }`,
-		)
-		l.push(`\t\tresp, err := ${cfgAccess}.HTTPClient.Do(req)`)
-		l.push(`\t\tif err != nil { yield(SSEEvent{}, err); return }`)
 		l.push(`\t\tfor ev, err := range parseSSEStream(ctx, resp) {`)
-		l.push(`\t\t\tif !yield(ev, err) { return }`)
+		l.push(`\t\t\tif !yield(ev, err) {`)
+		l.push(`\t\t\t\treturn`)
+		l.push(`\t\t\t}`)
 		l.push(`\t\t}`)
 		l.push(`\t}`)
 		l.push(`}`)
@@ -809,180 +639,290 @@ function emitMethod(m: MethodInfo, recv: string, recvType: string, throwOnError:
 		return l
 	}
 
-	if (m.isWS) {
-		const urlExpr = pathToGoExpr(pathStr)
-		l.push(`\tq := url.Values{}`)
-		for (const qp of m.queryParams) {
-			if (qp.name === "reconnect_token") continue
-			const fieldName = goPascal(qp.name)
-			if (qp.required) {
-				l.push(
-					`\tif opts != nil { q.Set(${JSON.stringify(qp.name)}, ${qpStringExpr(`opts.${fieldName}`, qp.schema)}) }`,
-				)
-			} else {
-				l.push(
-					`\tif opts != nil && opts.${fieldName} != nil { q.Set(${JSON.stringify(qp.name)}, ${qpStringExpr(`*opts.${fieldName}`, qp.schema)}) }`,
-				)
-			}
-		}
-		l.push(`\tif opts != nil && opts.ReconnectToken != "" { q.Set("reconnect_token", opts.ReconnectToken) }`)
-		l.push(`\twsURL := ${cfgAccess}.BaseURL + ${urlExpr}`)
-		l.push(`\tif len(q) > 0 { wsURL += "?" + q.Encode() }`)
-		l.push(`\tdialOpts := &websocket.DialOptions{}`)
-		l.push(`\tif opts != nil && len(opts.Protocols) > 0 { dialOpts.Subprotocols = opts.Protocols }`)
-		l.push(`\tif opts != nil && len(opts.Headers) > 0 {`)
-		l.push(`\t\tdialOpts.HTTPHeader = http.Header{}`)
-		l.push(`\t\tfor k, v := range opts.Headers { dialOpts.HTTPHeader.Set(k, v) }`)
+	if (op.stream === "ws") {
+		l.push(`func (${recv} ${recvType}) ${plan.methodName}(${params.join(", ")}) (*TypedWebSocket, error) {`)
+		l.push(...emitPath(plan, "return nil, err", "\t"))
+		l.push(...emitQueryAndHeaders(plan, "\t", "map[string]string{}"))
+		l.push(`\tif opts != nil && opts.ReconnectToken != "" {`)
+		l.push(`\t\tq.set("reconnect_token", opts.ReconnectToken)`)
+		l.push(`\t}`)
+		l.push(`\twsURL, err := buildURL(${cfg}.BaseURL, path, q)`)
+		l.push(`\tif err != nil {`)
+		l.push(`\t\treturn nil, err`)
+		l.push(`\t}`)
+		l.push(
+			`\tdialOpts := &websocket.DialOptions{HTTPClient: streamClient(${cfg}), HTTPHeader: authHeaders(${cfg}, callHeaders)}`,
+		)
+		l.push(`\tif opts != nil && len(opts.Protocols) > 0 {`)
+		l.push(`\t\tdialOpts.Subprotocols = opts.Protocols`)
+		l.push(`\t}`)
+		l.push(`\tconn, _, err := websocket.Dial(ctx, toWsURL(wsURL), dialOpts)`)
+		l.push(`\tif err != nil {`)
+		l.push(`\t\treturn nil, err`)
 		l.push(`\t}`)
-		l.push(`\tconn, _, err := websocket.Dial(ctx, wsURL, dialOpts)`)
-		l.push(`\tif err != nil { return nil, err }`)
 		l.push(`\treturn newTypedWebSocket(conn), nil`)
 		l.push(`}`)
 		l.push(``)
 		return l
 	}
 
-	/* HTTP method */
-	l.push(`\tq := url.Values{}`)
-	for (const qp of m.queryParams) {
-		const fieldName = goPascal(qp.name)
-		if (qp.required) {
-			l.push(`\tif opts != nil { q.Set(${JSON.stringify(qp.name)}, ${qpStringExpr(`opts.${fieldName}`, qp.schema)}) }`)
-		} else {
-			l.push(
-				`\tif opts != nil && opts.${fieldName} != nil { q.Set(${JSON.stringify(qp.name)}, ${qpStringExpr(`*opts.${fieldName}`, qp.schema)}) }`,
-			)
-		}
-	}
-
-	const urlExpr = pathToGoExpr(pathStr)
-	const bodyArg = !m.bodyIsStream && m.bodyType ? "body" : "nil"
-	const bodyReaderArg = m.bodyIsStream ? "body" : "nil"
-	const contentTypeArg = m.bodyIsStream ? `"application/octet-stream"` : `""`
-
-	l.push(`\tvar callHeaders map[string]string`)
-	l.push(`\tif opts != nil { callHeaders = opts.Headers }`)
-
-	/* idempotency-key auto-injection: case-insensitive existing-header check
-	 * matches caller's intent if they supplied any casing. opts==nil branch
-	 * still emits a key so the contract holds (every dispatch carries a key
-	 * for ops marked x-idempotency-key). */
-	if (m.isIdempotent && !m.isRealtime && !m.isSSE && !m.isWS) {
-		l.push(`\tif opts != nil {`)
-		l.push(`\t\t_idemExisting := ""`)
-		l.push(`\t\tfor _k, _v := range callHeaders {`)
-		l.push(`\t\t\tif strings.EqualFold(_k, "Idempotency-Key") { _idemExisting = _v; break }`)
-		l.push(`\t\t}`)
-		l.push(`\t\tif _idemExisting == "" {`)
-		l.push(`\t\t\tif callHeaders == nil { callHeaders = map[string]string{} }`)
-		l.push(`\t\t\tif opts.IdempotencyKey != "" {`)
-		l.push(`\t\t\t\tcallHeaders["Idempotency-Key"] = opts.IdempotencyKey`)
-		l.push(`\t\t\t} else {`)
-		l.push(`\t\t\t\tcallHeaders["Idempotency-Key"] = newUUIDv4()`)
-		l.push(`\t\t\t}`)
+	const resultType = plan.resultType
+	let ret: string
+	let failRet: string
+	if (resultType === "") {
+		ret = "error"
+		failRet = "return err"
+	} else if (throwOnError) {
+		ret = `(*${resultType}, error)`
+		failRet = "return nil, err"
+	} else {
+		ret = `(SDKResult[${resultType}], error)`
+		failRet = `return SDKResult[${resultType}]{}, err`
+	}
+	l.push(`func (${recv} ${recvType}) ${plan.methodName}(${params.join(", ")}) ${ret} {`)
+	l.push(`\tvar err error`)
+	l.push(...emitPath(plan, failRet, "\t"))
+	l.push(...emitQueryAndHeaders(plan, "\t", "map[string]string{}"))
+
+	/* idempotency-key auto-injection: an explicit header (any casing) wins, then
+	 * opts.IdempotencyKey, then a fresh UUID — every dispatch carries a key. */
+	if (op.idempotent) {
+		l.push(`\tif !hasHeader(callHeaders, "Idempotency-Key") {`)
+		l.push(`\t\tkey := newUUIDv4()`)
+		l.push(`\t\tif opts != nil && opts.IdempotencyKey != "" {`)
+		l.push(`\t\t\tkey = opts.IdempotencyKey`)
 		l.push(`\t\t}`)
-		l.push(`\t} else {`)
-		l.push(`\t\tcallHeaders = map[string]string{"Idempotency-Key": newUUIDv4()}`)
+		l.push(`\t\tcallHeaders["Idempotency-Key"] = key`)
 		l.push(`\t}`)
 	}
 
-	/* invalidation pre-flight — build path-params map, interpolate to concrete
-	 * selector, snapshot RequestMeta from the tracker. Emitted unconditionally
-	 * so consumer can flip cfg.Invalidation on/off without regen; tracker's
-	 * BuildRequestMeta short-circuits to nil when disabled. */
-	const hasInvalidate = Array.isArray(m.op["x-invalidate"]) && (m.op["x-invalidate"] as unknown[]).length > 0
-	const pathParamsMapExpr =
-		m.pathParams.length > 0
-			? `map[string]string{${m.pathParams.map((p) => `${JSON.stringify(p)}: ${p}`).join(", ")}}`
-			: `map[string]string(nil)`
-	if (hasInvalidate) {
-		l.push(`\t_pathParamsMap := ${pathParamsMapExpr}`)
-		l.push(`\t_concretePath, _ := interpolatePath(${JSON.stringify(pathStr)}, _pathParamsMap)`)
-		l.push(`\t_concreteSelector := ${JSON.stringify(`${httpMethodStr} `)} + _concretePath`)
-		l.push(`\tvar _requestMeta *RequestMeta`)
-		l.push(
-			`\tif ${staleAccess} != nil { _requestMeta = ${staleAccess}.BuildRequestMeta(_concreteSelector, _concretePath, ${JSON.stringify(httpMethodStr)}) }`,
-		)
-	}
+	const body = emitBody(plan, failRet, "\t")
+	l.push(...body.lines)
+
+	/* invalidation pre-flight for every call: reads see and clear staleness too */
+	const pathParamsExpr = plan.pathLocals.length > 0 ? pathExpr(plan) : "map[string]string(nil)"
+	l.push(`\tpathParams := ${pathParamsExpr}`)
+	l.push(`\tselector := ${goString(`${op.method} `)} + path`)
+	l.push(`\tvar requestMeta *RequestMeta`)
+	l.push(`\tif ${stale} != nil {`)
+	l.push(`\t\trequestMeta = ${stale}.BuildRequestMeta(selector, path, ${goString(op.method)})`)
+	l.push(`\t}`)
 
-	const resultBind = m.responseType === "" ? "_, err" : "result, err"
-	const operationStr = JSON.stringify(`${httpMethodStr} ${pathStr}`)
-	const requestMetaArg = hasInvalidate ? "_requestMeta" : "nil"
+	const resultBind = resultType === "" ? "_, err =" : "result, err :="
 	l.push(
-		`\t${resultBind} := doRequest(ctx, ${cfgAccess}, "${httpMethodStr}", ${urlExpr}, q, ${bodyArg}, ${bodyReaderArg}, ${contentTypeArg}, callHeaders, ${operationStr}, ${requestMetaArg})`,
+		`\t${resultBind} doRequest(ctx, ${cfg}, ${goString(op.method)}, path, q, ${body.expr}, callHeaders, ${goString(`${op.method} ${op.path}`)}, requestMeta)`,
 	)
 	l.push(`\tif err != nil {`)
-
-	if (throwOnError) {
-		if (m.responseType !== "") {
-			l.push(`\t\treturn nil, err`)
-		} else {
-			l.push(`\t\treturn err`)
-		}
+	if (resultType !== "" && !throwOnError) {
+		l.push(`\t\tvar apiErr APIError`)
+		l.push(`\t\tif errors.As(err, &apiErr) {`)
+		l.push(`\t\t\treturn SDKResult[${resultType}]{Err: apiErr, Status: apiErr.Status()}, nil`)
+		l.push(`\t\t}`)
+		l.push(`\t\treturn SDKResult[${resultType}]{}, err`)
 	} else {
-		if (m.responseType !== "") {
-			/* unwrap typed APIError if doRequest produced one, else synthesize
-			 * a StatusError so callers always see a typed Err without panicking
-			 * on ctx cancel / network errors. */
-			l.push(`\t\tif apiErr, ok := err.(APIError); ok {`)
-			l.push(`\t\t\treturn SDKResult[${m.responseType}]{Err: apiErr, Status: 0, Response: nil}, nil`)
-			l.push(`\t\t}`)
-			l.push(
-				`\t\treturn SDKResult[${m.responseType}]{Err: &StatusError{StatusCode: 0, Message: err.Error()}, Status: 0, Response: nil}, nil`,
-			)
-		} else {
-			l.push(`\t\treturn err`)
-		}
+		l.push(`\t\t${failRet}`)
 	}
 	l.push(`\t}`)
 
-	/* invalidation post-flight — expand templated x-invalidate targets with the
-	 * call's concrete params (TS parity: GET /users/{id} → GET /users/abc),
-	 * mark them stale, then clear keys that were already stale before this
-	 * mutation completed (seq-bounded to avoid clobbering newer invalidations). */
-	if (hasInvalidate) {
-		l.push(`\tif ${staleAccess} != nil {`)
-		l.push(
-			`\t\t${staleAccess}.MarkStale(invalidationMap["${m.resource}"]["${m.action}"].Invalidate, _pathParamsMap, _concreteSelector)`,
-		)
-		l.push(`\t\tif _requestMeta != nil && _requestMeta.IsStale {`)
-		l.push(
-			`\t\t\t${staleAccess}.ClearStale(_concreteSelector, _concretePath, ${JSON.stringify(httpMethodStr)}, _requestMeta.SeqSnapshot)`,
-		)
-		l.push(`\t\t}`)
-		l.push(`\t}`)
+	/* invalidation post-flight: mark declared targets stale (templated ones expanded
+	 * with this call's params), then clear this key if the call read through a stale window */
+	l.push(`\tif ${stale} != nil {`)
+	if (op.invalidates.length > 0) {
+		l.push(`\t\t${stale}.MarkStale([]string{${op.invalidates.map(goString).join(", ")}}, pathParams, selector)`)
+	} else {
+		l.push(`\t\t_ = pathParams`)
 	}
+	l.push(`\t\tif requestMeta != nil && requestMeta.IsStale {`)
+	l.push(`\t\t\t${stale}.ClearStale(selector, path, ${goString(op.method)}, requestMeta.SeqSnapshot)`)
+	l.push(`\t\t}`)
+	l.push(`\t}`)
 
-	if (m.responseType === "") {
+	if (resultType === "") {
 		l.push(`\treturn nil`)
 		l.push(`}`)
 		l.push(``)
 		return l
 	}
 
-	if (throwOnError) {
-		l.push(`\tvar out ${m.responseType}`)
-		l.push(`\tif len(result.body) > 0 {`)
-		l.push(`\t\tif err := json.Unmarshal(result.body, &out); err != nil { return nil, err }`)
-		l.push(`\t}`)
-		l.push(`\treturn &out, nil`)
+	l.push(`\tvar out ${resultType}`)
+	if (op.success.kind === "text") {
+		l.push(`\tout = string(result.body)`)
+	} else if (op.success.kind === "binary") {
+		l.push(`\tout = result.body`)
 	} else {
-		l.push(`\tvar out ${m.responseType}`)
 		l.push(`\tif len(result.body) > 0 {`)
 		l.push(`\t\tif err := json.Unmarshal(result.body, &out); err != nil {`)
-		l.push(
-			`\t\t\treturn SDKResult[${m.responseType}]{Err: &StatusError{StatusCode: result.status, Body: result.body, Response: result.resp, Message: err.Error()}, Status: result.status, Response: result.resp}, nil`,
-		)
+		if (throwOnError) {
+			l.push(`\t\t\treturn nil, fmt.Errorf("honey: decode response: %w", err)`)
+		} else {
+			l.push(
+				`\t\t\treturn SDKResult[${resultType}]{Err: &StatusError{StatusCode: result.status, Body: result.body, Response: result.resp, Message: err.Error()}, Status: result.status, Response: result.resp}, nil`,
+			)
+		}
 		l.push(`\t\t}`)
 		l.push(`\t}`)
-		l.push(`\treturn SDKResult[${m.responseType}]{Data: &out, Status: result.status, Response: result.resp}, nil`)
 	}
-
+	if (throwOnError) l.push(`\treturn &out, nil`)
+	else l.push(`\treturn SDKResult[${resultType}]{Data: &out, Status: result.status, Response: result.resp}, nil`)
 	l.push(`}`)
 	l.push(``)
 	return l
 }
 
+type ResourceNode = {
+	structName: string
+	ns: IRNamespace
+	path: string[]
+	children: Array<{ field: string; node: ResourceNode }>
+	methods: GoOpPlan[]
+}
+
+function buildGoClient(
+	model: SdkModel,
+	names: GoNames,
+	options: GoSDKOptions,
+	auth: { headerName: string; prefix: string },
+): string {
+	const throwOnError = options.throwOnError ?? true
+
+	/* plan resources top-down so names are claimed in a stable order */
+	const allPlans: GoOpPlan[] = []
+	function planNs(
+		ns: IRNamespace,
+		path: string[],
+		reserved: string[],
+	): { children: ResourceNode["children"]; methods: GoOpPlan[] } {
+		const members = new NameScope(reserved)
+		const children: ResourceNode["children"] = []
+		for (const [seg, childNs] of namespacesOf(ns)) {
+			const field = members.claim(goExported(seg))
+			const childPath = [...path, seg]
+			const structName = names.scope.claim(`${childPath.map(goExported).join("")}Resource`)
+			children.push({ field, node: { children: [], methods: [], ns: childNs, path: childPath, structName } })
+		}
+		const methods: GoOpPlan[] = []
+		for (const [seg, irOp] of methodsOf(ns)) {
+			const op = model.opsById.get(irOp.id)
+			if (!op) continue
+			const base = goExported(seg)
+			/* Go forbids a field and a method with one name: `extract` + `extract.table` → ExtractCall */
+			const methodName = members.has(base) ? members.claim(`${base}Call`) : members.claim(base)
+			const optsName = names.scope.claim(`${[...path, seg].map(goExported).join("")}Opts`)
+			const plan = planOp(op, methodName, optsName, names)
+			methods.push(plan)
+			allPlans.push(plan)
+		}
+		for (const child of children) {
+			const sub = planNs(child.node.ns, child.node.path, ["client"])
+			child.node.children = sub.children
+			child.node.methods = sub.methods
+		}
+		return { children, methods }
+	}
+	const root = planNs(model.ir.tree, [], ["cfg", "stale", "IsStale"])
+
+	const body: string[] = []
+	/* ---- Client struct: cfg + stale + one field per root namespace ---- */
+	body.push(`// Client is the generated SDK client.`)
+	body.push(`type Client struct {`)
+	body.push(`\tcfg   Config`)
+	body.push(`\tstale *StaleTracker`)
+	for (const child of root.children) body.push(`\t${child.field} *${child.node.structName}`)
+	body.push(`}`)
+	body.push(``)
+	body.push(emitClientBody(root, allPlans, throwOnError, auth))
+	return body.join("\n")
+}
+
+function emitClientBody(
+	root: { children: ResourceNode["children"]; methods: GoOpPlan[] },
+	allPlans: GoOpPlan[],
+	throwOnError: boolean,
+	auth: { headerName: string; prefix: string },
+): string {
+	const body: string[] = []
+	/* ---- NewClient: init + cascade nested struct init ---- */
+	body.push(`// NewClient creates a new SDK client. BaseURL must be non-empty.`)
+	body.push(`func NewClient(cfg Config) *Client {`)
+	body.push(`\tif cfg.BaseURL == "" {`)
+	body.push(`\t\tpanic("honey sdk: Config.BaseURL must not be empty")`)
+	body.push(`\t}`)
+	body.push(`\tif cfg.AuthHeaderName == "" {`)
+	body.push(`\t\tcfg.AuthHeaderName = ${goString(auth.headerName)}`)
+	body.push(`\t}`)
+	body.push(`\tif cfg.AuthHeaderPrefix == "" {`)
+	body.push(`\t\tcfg.AuthHeaderPrefix = ${goString(auth.prefix)}`)
+	body.push(`\t}`)
+	body.push(`\tcfg = prepareConfig(cfg)`)
+	body.push(`\tc := &Client{cfg: cfg}`)
+	body.push(`\tc.stale = NewStaleTracker(cfg.Invalidation)`)
+	for (const child of root.children) body.push(`\tc.${child.field} = new${child.node.structName}(c)`)
+	body.push(`\treturn c`)
+	body.push(`}`)
+	body.push(``)
+
+	/* IsStale predicate */
+	body.push(`// IsStale reports whether (method, path) currently sits inside an active stale window.`)
+	body.push(`func (c *Client) IsStale(method, path string) bool {`)
+	body.push(`\tif c.stale == nil {`)
+	body.push(`\t\treturn false`)
+	body.push(`\t}`)
+	body.push(`\treturn c.stale.IsStale(method, path)`)
+	body.push(`}`)
+	body.push(``)
+
+	for (const plan of root.methods) body.push(...emitMethod(plan, "c", "*Client", throwOnError))
+
+	function emitResource(node: ResourceNode): void {
+		body.push(`// ${node.structName} groups the ${goString(node.path.join("."))} operations.`)
+		body.push(`type ${node.structName} struct {`)
+		body.push(`\tclient *Client`)
+		for (const child of node.children) body.push(`\t${child.field} *${child.node.structName}`)
+		body.push(`}`)
+		body.push(``)
+		body.push(`func new${node.structName}(c *Client) *${node.structName} {`)
+		body.push(`\tr := &${node.structName}{client: c}`)
+		for (const child of node.children) body.push(`\tr.${child.field} = new${child.node.structName}(c)`)
+		body.push(`\treturn r`)
+		body.push(`}`)
+		body.push(``)
+		for (const plan of node.methods) body.push(...emitMethod(plan, "r", `*${node.structName}`, throwOnError))
+		for (const child of node.children) emitResource(child.node)
+	}
+	for (const child of root.children) emitResource(child.node)
+
+	for (const plan of [...allPlans].sort((a, b) => cmpCodeUnit(a.optsName, b.optsName))) {
+		body.push(...emitMultipartStruct(plan))
+		body.push(...emitOptsStruct(plan))
+	}
+	return body.join("\n")
+}
+
+function clientFile(model: SdkModel, names: GoNames, options: GoSDKOptions): string {
+	const bodyStr = buildGoClient(model, names, options, model.ir.auth)
+
+	const stdlib = ["context"]
+	const uses = (re: RegExp) => re.test(bodyStr)
+	if (uses(/\bjson\./)) stdlib.push("encoding/json")
+	if (uses(/\berrors\./)) stdlib.push("errors")
+	if (uses(/\bfmt\./)) stdlib.push("fmt")
+	if (uses(/\bio\./)) stdlib.push("io")
+	if (uses(/\biter\./)) stdlib.push("iter")
+	if (uses(/\burl\./)) stdlib.push("net/url")
+	const thirdParty = uses(/\bwebsocket\./) ? ["nhooyr.io/websocket"] : []
+
+	const out: string[] = []
+	/* blank line after generator header detaches it from package-doc on pkg.go.dev */
+	out.push(`// Code generated by honey. DO NOT EDIT.`)
+	out.push(``)
+	out.push(`package sdk`)
+	out.push(``)
+	out.push(goImportBlock(stdlib, thirdParty))
+	out.push(``)
+	out.push(bodyStr)
+	return out.join("\n")
+}
+
 /* ── public entrypoint ── */
 
 /**
@@ -990,9 +930,10 @@ function emitMethod(m: MethodInfo, recv: string, recvType: string, throwOnError:
  * Returns a file map (filename → content) ready to write to disk as a Go module.
  */
 export function generateGoSDK(spec: Record<string, unknown>, options: GoSDKOptions = {}): GeneratedGoSDK {
-	const resolved = resolveRefs(spec as Parameters<typeof resolveRefs>[0]) as unknown as OpenApiSpec
-
-	const { serviceMap } = collectSDKMethods(spec as Parameters<typeof resolveRefs>[0])
+	const input = spec as unknown as OpenApiSpecInput
+	const model = buildSdkModel(input)
+	const names = buildGoNames(model)
+	const serviceMap = serviceMapOf(model.ir)
 
 	const files: Record<string, string> = {}
 
@@ -1001,13 +942,12 @@ export function generateGoSDK(spec: Record<string, unknown>, options: GoSDKOptio
 		files[name] = content
 	}
 
-	/* types.go uses unresolved spec because resolveRefs strips components.schemas. */
-	files["types.go"] = buildGoTypes(spec as unknown as OpenApiSpec)
-	/* client uses unresolved spec so request/response $refs survive for type
-	 * resolution into named Go types (resolveRefs inlines and drops names). */
-	files["client.go"] = buildGoClient(spec as unknown as OpenApiSpec, options)
+	/* schema types claim their names first; the client then hoists into the same table */
+	const schemaTypes = buildGoTypes(model, names)
+	files["client.go"] = clientFile(model, names, options)
+	files["types.go"] = typesFile(schemaTypes, names)
 	files["go.mod"] = buildGoMod(options.modulePath)
-	files["doc.go"] = buildGoDoc(resolved)
+	files["doc.go"] = buildGoDoc(model.ir.info)
 
 	/* Opt-in post-process. Consumers publishing to pkg.go.dev pass `gofmt: true`
 	 * so struct fields align and single-line `if` blocks expand. No-op when