Repository navigation
design(codec): define exact bigint transport and generated integer types #337
Description
Explore exact Python integer transport beyond the JavaScript safe range. This is separate from the 0.11 rejection fix in #331.
Returning bigint under an unchanged Promise would create a type mismatch. Cover generation and both request and response codecs.
Acceptance criteria:
- Choose and document the default or opt-in policy for safe numbers and arbitrary-size integers.
- Specify a versioned wire representation and behavior with older clients and bridges.
- Define matching generated types and return validators.
- A bounded prototype round-trips positive and negative integers beyond 64 bits through nested values.
- Cover large JavaScript bigint inputs, malformed envelopes, payload limits, and mixed-version rejection.
- Preserve Arrow int64 semantics and distinguish integer policy from float policy.
- Record an independent design verdict and migration cost before scheduling implementation.
This is exploratory work outside 0.11.
Architectural approach:
Extend the semantic value rules in #343 and the resolved contract in #335. The proposal must demonstrate how types, encoding, and validation change together. Coordinate through #345.
Activity
bbopen commentedon Sep 20, 2026
The bounded exact-integer design is complete. Its opt-in revision 3 prototype uses a versioned decimal envelope and explicit peer capability. Generated types and validators agree for nested positive and negative bigint values beyond 64 bits. Tests cover inputs, malformed envelopes, and depth and byte/digit limits. Missing peer capability rejects before dispatch. Wrong-version response envelopes reject after dispatch. Default revision 2 safe-number behavior and Arrow int64 remain separate.
Independent review accepted the design and measured costs. Default production bigint transport is not included in 0.11.0.
Evidence:
docs/maintainers/value-contracts.v3.json,docs/maintainers/value-contract-prototypes.md,test/value_extensions_generated_integer.test.ts, anddocs/maintainers/architecture-decision-0.11.md.Verified release evidence:
0861ebeand mergef6f811dhave identical trees.The architecture decision records the accepted scope and prototype limits.
Closing as complete within the issue's bounded design scope.