Phase 3: Existing Client Review - Context

Consistency standard#

• Semantic JSON identity: All 4 generators (go-http, go-client, ts-client, openapiv3) must produce semantically identical JSON for the same proto definition. Key order and whitespace can differ; parsed JSON must match.
• Both content types: Audit must verify both JSON and protobuf binary request/response paths for both clients.
• Query parameters must match exactly: Both clients must produce identical query strings for the same input (same encoding for repeated fields, bools, etc.).
• Path parameters must be URL-encoded: Both clients must properly URL-encode path parameter values. Encoding must be correct and consistent.
• Follow protojson spec: Default values follow protojson behavior (omitted unless explicitly set). This is the source of truth for JSON serialization behavior.
• Unwrap thoroughly verified: All unwrap variants (root repeated, root map, map-value, combined root+value) must be verified across both clients and the server.
• OpenAPI must match everything: OpenAPI specs must document exactly what the server produces and clients expect. Schemas, paths, parameters, error responses must all be consistent with actual behavior.
• TS int64 as string: TypeScript client must represent int64/uint64 as string to preserve precision, matching the proto3 JSON spec for 64-bit integers.

Handling findings#

• Fix everything immediately: Every inconsistency found gets fixed in this phase. No deferring, no "document for later." The whole point is to make these solid.
• Update golden files + add new cases: When a fix changes generated output, update existing golden files AND add new golden file test cases that specifically cover the inconsistency found. Prevent regression.
• Fix the server too: If the Go server deviates from protojson spec, fix the server. Protojson spec is the source of truth for correctness; server behavior is the source of truth for "what clients should expect" only when it's correct.
• Docs must be 500% consistent: All clients + server + OpenAPI docs must be fully consistent. Any documentation that doesn't match actual behavior is a bug.

Review coverage#

• Exhaustive: Every RPC in the exhaustive test proto, every annotation combination. Leave no stone unturned.
• Include OpenAPI in audit: OpenAPI spec is audited in this phase, not deferred to Phase 11. Schemas, paths, parameters, error responses must match actual server/client behavior.
• Expand test proto if needed: If the exhaustive test proto is missing annotation combinations, add them. The audit must cover everything the generators support.
• Mandatory cross-generator check: For each service in the test proto, all 4 generator outputs must be semantically consistent with each other.

Quality baseline#

• Correctness + idiomatic code: Generated code must be correct AND idiomatic. Go client should look like hand-written Go, TS client should look like hand-written TypeScript.
• All edge cases: Empty responses (204), large/deeply nested payloads, special characters in path/query/header params, unicode, URL-unsafe characters.
• Audit generated docs: GoDoc and JSDoc in generated code must accurately describe parameters, return types, and error conditions.
• Review Go functional options completeness: Audit the functional options API for completeness, naming consistency, and ergonomics. Identify missing options users would expect.

Claude's Discretion#

• Exact order of audit (which generator to start with)
• How to structure the cross-generator comparison (tooling vs manual)
• Grouping of fixes into plans/commits
• Whether to create automated consistency test infrastructure or rely on golden files