Skip to content

docs(spec): clarify TypeScript integer waiver - #536

Merged
jeremy merged 1 commit into
basecamp:mainfrom
lntutor:docs/clarify-typescript-integer-waiver
Jul 31, 2026
Merged

docs(spec): clarify TypeScript integer waiver#536
jeremy merged 1 commit into
basecamp:mainfrom
lntutor:docs/clarify-typescript-integer-waiver

Conversation

@lntutor

@lntutor lntutor commented Jul 31, 2026

Copy link
Copy Markdown
Contributor

Summary

  • clarify that Node 22 reviver source access makes lossless integer decoding technically feasible
  • retain the TypeScript waiver because returning bigint would break the public number-typed API
  • keep the rubric, specification, and conformance test description consistent

Verification

  • python3 -m json.tool rubric-audit.json
  • python3 -m json.tool conformance/tests/integer-precision.json
  • verified lossless context.source decoding on Node 22.22.0
  • git diff --check

Release notes: Documentation

Closes #533


Summary by cubic

Clarifies the TypeScript integer precision waiver: Node >=22.12 can access raw digits in a JSON.parse reviver, making lossless bigint decoding feasible, but we retain the waiver because returning bigint would break the number-typed API. Syncs SPEC.md, the integer-precision conformance test description, and the rubric note.

Written for commit ff13a09. Summary will update on new commits.

Review in cubic

Copilot AI review requested due to automatic review settings July 31, 2026 20:26
@github-actions github-actions Bot added documentation Improvements or additions to documentation conformance Conformance test suite labels Jul 31, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Clarifies why TypeScript retains its integer-precision waiver despite Node 22 supporting lossless decoding.

Changes:

  • Documents JSON.parse reviver source access.
  • Explains the number-to-bigint API compatibility concern.
  • Aligns the specification, rubric, and conformance description.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File Description
SPEC.md Clarifies the retained TypeScript precision limitation.
rubric-audit.json Updates waiver 1B.6 rationale.
conformance/tests/integer-precision.json Aligns the conformance-test description.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@jeremy jeremy left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed as maintainer against post-#535 main:

  • Accuracy: The Node >=22.12 claim matches what we verified empirically in #533JSON.parse reviver context.source yields the raw digits, so lossless bigint decode is feasible on the supported engine floor. The rewrite correctly retains waiver 1B.6 on its surviving ground (bigint would break the number-typed API surface) and promises no SDK adoption.
  • Consistency: All four sites from #533 are covered or verifiably fine — SPEC §10 conflict marker and the per-language precision table are updated here; the §19 waiver-table row (| 1B.6 | §10 | 64-bit integer precision |) is index-only with no stale claim; the §19 TS skip-roster line ("Number is 53-bit") stays factually consistent with the new text.
  • Scope: integer-precision.json change is description-only — operation, method, path, and assertions untouched.

Thanks for threading this precisely through the spec, rubric, and conformance description.

@jeremy
jeremy merged commit d3422f5 into basecamp:main Jul 31, 2026
41 checks passed
@jeremy

jeremy commented Jul 31, 2026

Copy link
Copy Markdown
Member

Merged as d3422f5. Thank you for a first contribution that hit exactly the right altitude: you took the "decide and document" ask from #533, made the call the evidence supports (waiver retained on API-surface grounds, not mechanism grounds), and threaded it consistently through the spec, the rubric, and the conformance description without touching any test semantics. That is precisely how we hoped that issue would land. Welcome, and we would be glad to see you back.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

conformance Conformance test suite documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

TS waiver 1B.6: "no clean fix" for >2^53 integer precision is stale against the Node >=22.12.0 floor

3 participants