Sebuf

Phase 4: JSON - Primitive Encoding Verification Report

Phase Goal: Developers can control how int64/uint64 fields and enum fields are encoded in JSON across all generators

Verified: 2026-02-05T23:07:44Z

Status: passed

Re-verification: No — initial verification

Goal Achievement#

Observable Truths#

# Truth Status Evidence
1 A proto field annotated with int64_encoding = STRING serializes int64/uint64 values as JSON strings in go-http, go-client, ts-client, and documents as type: string in OpenAPI ✓ VERIFIED Proto annotation exists at line 98 of annotations.proto. TypeScript golden shows defaultInt64: string and stringInt64: string. OpenAPI golden shows type: string, format: int64 for STRING-encoded fields. Test TestPhase4SuccessCriteria/Criterion_1 passes.
2 A proto field annotated with int64_encoding = NUMBER serializes int64/uint64 values as JSON numbers in all generators with generation-time warning about JavaScript precision loss ✓ VERIFIED Proto annotation supports INT64_ENCODING_NUMBER enum value. Go golden contains MarshalJSON/UnmarshalJSON methods with warning comment "Values > 2^53 may lose precision". TypeScript golden shows numberInt64: number. OpenAPI golden includes description "Warning: Values > 2^53 may lose precision in JavaScript" for all NUMBER-encoded fields. Test passes.
3 A proto enum annotated with enum_encoding = STRING serializes enum values as their proto names in JSON across all generators ✓ VERIFIED Proto annotation exists at line 103. Enum Priority with STRING encoding generates TypeScript type "PRIORITY_LOW" | "PRIORITY_MEDIUM" | "PRIORITY_HIGH". OpenAPI shows string enum. Test TestPhase4SuccessCriteria/Criterion_3 passes.
4 Per-value enum_value annotations map proto enum names to custom JSON strings across all generators ✓ VERIFIED Proto annotation at line 111 supports custom enum values. Go golden contains statusToJSON and statusFromJSON maps with custom values: Status_STATUS_ACTIVE: "active". TypeScript golden shows type Status = "unknown" | "active" | "inactive". OpenAPI enum array contains custom values. Test TestPhase4SuccessCriteria/Criterion_4 passes.
5 OpenAPI schemas for int64/enum fields accurately reflect the configured encoding ✓ VERIFIED NUMBER int64 fields show type: integer, format: int64 with precision warning. STRING int64 fields show type: string, format: int64. Enum NUMBER encoding shows type: integer. Enum with custom values shows type: string, enum: ["unknown", "active", "inactive"]. Test TestPhase4SuccessCriteria/Criterion_5 passes.
6 A cross-generator consistency test confirms that go-http, go-client, ts-client, and openapiv3 produce semantically identical JSON for every encoding combination ✓ VERIFIED encoding_consistency_test.go exists with 11 test functions. TestGoGeneratorsProduceIdenticalInt64Encoding confirms byte-identical encoding code between go-http and go-client after normalization. TestGoGeneratorsProduceIdenticalEnumEncoding confirms identical enum encoding. TestTypeScriptInt64TypesMatchGoEncoding and TestTypeScriptEnumTypesMatchGoEncoding verify TypeScript matches Go. TestOpenAPIInt64SchemasMatchGoEncoding and TestOpenAPIEnumSchemasMatchGoEncoding verify OpenAPI matches Go. All tests pass.

Score: 6/6 truths verified

Required Artifacts#

Artifact Expected Status Details
proto/sebuf/http/annotations.proto Int64Encoding enum, EnumEncoding enum, field extensions ✓ VERIFIED Lines 60-78: Int64Encoding enum with UNSPECIFIED/STRING/NUMBER. Lines 70-78: EnumEncoding enum. Lines 98, 103: int64_encoding and enum_encoding field extensions (50010, 50011). Line 111: enum_value extension (50012). All exist and compile.
internal/annotations/int64_encoding.go GetInt64Encoding function ✓ VERIFIED Lines 14-36: GetInt64Encoding function exists, returns http.Int64Encoding enum. Lines 40-42: IsInt64NumberEncoding helper exists. Follows established pattern from unwrap.go. Properly exported.
internal/annotations/enum_encoding.go GetEnumEncoding, GetEnumValueMapping functions ✓ VERIFIED Lines 14-36: GetEnumEncoding exists. Lines 40-62: GetEnumValueMapping exists. Lines 65-72: HasAnyEnumValueMapping helper. Lines 76-87: HasConflictingEnumAnnotations validation. All properly exported.
internal/httpgen/encoding.go int64 NUMBER encoding implementation ✓ VERIFIED Used by httpgen (verified via grep). Generates MarshalJSON/UnmarshalJSON in golden files. Warning comment present in generated code.
internal/httpgen/enum_encoding.go enum encoding implementation ✓ VERIFIED Used by httpgen (verified via grep). Generates statusToJSON/statusFromJSON maps and MarshalJSON/UnmarshalJSON methods in golden files.
internal/clientgen/encoding.go Go client int64 encoding ✓ VERIFIED Exists and used (grep confirms). Golden file int64_encoding_encoding.pb.go byte-identical to httpgen after normalization.
internal/clientgen/enum_encoding.go Go client enum encoding ✓ VERIFIED Exists and used (grep confirms). Golden file enum_encoding_enum_encoding.pb.go byte-identical to httpgen after normalization.
internal/tsclientgen/types.go TypeScript int64/enum type mapping ✓ VERIFIED Uses GetInt64Encoding and GetEnumValueMapping (grep confirms). Golden files show correct types: number for NUMBER, string for STRING int64. Custom enum values: "active" instead of "STATUS_ACTIVE".
internal/openapiv3/types.go OpenAPI int64/enum schema generation ✓ VERIFIED Uses GetInt64Encoding and GetEnumEncoding (grep confirms). Golden YAML shows type: integer for NUMBER, type: string for STRING. Precision warnings in descriptions. Custom enum values in enum arrays.
internal/httpgen/testdata/proto/int64_encoding.proto Test proto with int64 encoding combinations ✓ VERIFIED Comprehensive test cases: default (no annotation), explicit STRING, NUMBER encoding. Covers int64, uint64, sint64, sfixed64, fixed64. Repeated and optional fields. Service endpoint for testing.
internal/httpgen/testdata/proto/enum_encoding.proto Test proto with enum encoding combinations ✓ VERIFIED Status enum with custom values via enum_value annotation. Priority enum without custom values. Tests STRING and NUMBER encoding. Repeated and optional enum fields. Service endpoint.
internal/httpgen/encoding_consistency_test.go Cross-generator consistency tests ✓ VERIFIED 11 test functions covering all generators. TestGoGeneratorsProduceIdenticalInt64Encoding and TestGoGeneratorsProduceIdenticalEnumEncoding for Go. TestTypeScriptInt64TypesMatchGoEncoding and TestTypeScriptEnumTypesMatchGoEncoding for TS. TestOpenAPIInt64SchemasMatchGoEncoding and TestOpenAPIEnumSchemasMatchGoEncoding for OpenAPI. TestPhase4SuccessCriteria with 6 subtests. TestBackwardCompatibility. All pass.
From To Via Status Details
internal/annotations/int64_encoding.go proto/sebuf/http/annotations.proto proto.GetExtension with http.E_Int64Encoding ✓ WIRED Line 25: proto.GetExtension(fieldOptions, http.E_Int64Encoding). Import exists. Extension used correctly.
internal/annotations/enum_encoding.go proto/sebuf/http/annotations.proto proto.GetExtension with http.E_EnumEncoding, http.E_EnumValue ✓ WIRED Line 25: E_EnumEncoding. Line 51: E_EnumValue. Both extensions used correctly. Import exists.
internal/httpgen/encoding.go internal/annotations/int64_encoding.go GetInt64Encoding function call ✓ WIRED Grep confirms usage in httpgen. Golden file contains generated MarshalJSON with NUMBER handling.
internal/httpgen/enum_encoding.go internal/annotations/enum_encoding.go GetEnumEncoding, GetEnumValueMapping function calls ✓ WIRED Grep confirms usage. Golden file contains statusToJSON map with custom values.
internal/clientgen/encoding.go internal/annotations/int64_encoding.go GetInt64Encoding function call ✓ WIRED Grep confirms usage. Byte-identical output to httpgen confirms same logic.
internal/clientgen/enum_encoding.go internal/annotations/enum_encoding.go GetEnumEncoding, GetEnumValueMapping function calls ✓ WIRED Grep confirms usage. Byte-identical output to httpgen confirms same logic.
internal/tsclientgen/types.go internal/annotations GetInt64Encoding, GetEnumValueMapping calls ✓ WIRED Grep confirms usage. TypeScript golden shows correct type mapping: number vs string based on encoding.
internal/openapiv3/types.go internal/annotations GetInt64Encoding, GetEnumEncoding, GetEnumValueMapping calls ✓ WIRED Grep confirms usage. OpenAPI YAML shows correct schemas: integer vs string, custom enum values, precision warnings.
Test proto files Generated golden files protoc execution ✓ WIRED int64_encoding.proto and enum_encoding.proto used in golden file tests. All golden tests pass (httpgen, clientgen, tsclientgen, openapiv3).
Cross-generator tests All 4 generator golden files File comparison ✓ WIRED TestGoGeneratorsProduceIdenticalInt64Encoding compares httpgen and clientgen golden files. TestTypeScriptInt64TypesMatchGoEncoding reads TS golden. TestOpenAPIInt64SchemasMatchGoEncoding reads OpenAPI golden. All pass.

Requirements Coverage#

Requirement Status Blocking Issue
JSON-02: int64/uint64 as string encoding ✓ SATISFIED None. Annotation exists, all generators implement STRING encoding (default), NUMBER encoding supported with precision warnings.
JSON-03: Enum string encoding with custom values ✓ SATISFIED None. enum_encoding annotation exists with STRING/NUMBER options. enum_value annotation maps proto names to custom JSON strings. All generators implement correctly.

Anti-Patterns Found#

None. Code is clean and follows established patterns.

Scan Results:

  • Zero TODO/FIXME comments in new encoding files
  • Zero placeholder content
  • Zero empty implementations
  • No console.log-only implementations
  • All functions substantive with real logic
  • Generated code includes comprehensive error handling
  • Warnings appropriately placed for precision risks

Human Verification Required#

None required for this phase. All verification completed programmatically via:

  1. Golden file tests confirming generated code structure
  2. Cross-generator consistency tests confirming semantic equivalence
  3. Direct file inspection confirming correct types and schemas
  4. Full test suite execution confirming zero regressions

Summary#

Phase 4 goal ACHIEVED.

All 6 success criteria from ROADMAP.md verified:

  1. ✓ int64_encoding=STRING produces JSON strings in all 4 generators
  2. ✓ int64_encoding=NUMBER produces JSON numbers with precision warning
  3. ✓ enum_encoding=STRING produces proto name strings
  4. ✓ enum_value annotations produce custom JSON strings
  5. ✓ OpenAPI schemas accurately reflect configured encoding
  6. ✓ Cross-generator consistency verified for every encoding combination

Evidence:

  • Proto annotations defined and compile successfully
  • Shared annotation parsing functions exist in internal/annotations
  • All 4 generators (go-http, go-client, ts-client, openapiv3) use shared functions
  • Generated code confirmed in golden files:
    • Go: MarshalJSON/UnmarshalJSON with NUMBER handling
    • Go: statusToJSON/statusFromJSON with custom enum values
    • TypeScript: number vs string types match encoding
    • TypeScript: Custom enum values like "active" instead of "STATUS_ACTIVE"
    • OpenAPI: type: integer vs type: string match encoding
    • OpenAPI: Precision warnings in descriptions for NUMBER encoding
  • 11 cross-generator consistency tests all pass
  • Full test suite passes (6/6 packages)
  • Coverage maintained >= 85% threshold
  • All binaries build successfully
  • Backward compatibility verified (protos without annotations unchanged)
  • Zero regressions

Artifacts Created:

  • proto/sebuf/http/annotations.proto (modified, 3 new enums/extensions)
  • internal/annotations/int64_encoding.go (created, 43 lines)
  • internal/annotations/enum_encoding.go (created, 88 lines)
  • internal/httpgen/encoding.go (wired to annotations)
  • internal/httpgen/enum_encoding.go (wired to annotations)
  • internal/clientgen/encoding.go (wired to annotations)
  • internal/clientgen/enum_encoding.go (wired to annotations)
  • internal/tsclientgen/types.go (updated to use annotations)
  • internal/openapiv3/types.go (updated to use annotations)
  • internal/httpgen/testdata/proto/int64_encoding.proto (test fixture, 67 lines)
  • internal/httpgen/testdata/proto/enum_encoding.proto (test fixture, 65 lines)
  • internal/httpgen/encoding_consistency_test.go (verification tests, 11 functions)
  • Golden files for all 4 generators updated with encoding output

Plans Executed:

  • 04-01: Define annotations and shared parsing functions ✓
  • 04-02: Implement int64 encoding in Go generators ✓
  • 04-03: Implement int64 encoding in ts-client and openapiv3 ✓
  • 04-04: Implement enum encoding across all 4 generators ✓
  • 04-05: Cross-generator consistency validation ✓

Phase 4 is complete and ready to proceed to Phase 5.

Verified: 2026-02-05T23:07:44Z Verifier: Claude (gsd-verifier)