docs(decimal): design record DECIMAL.md for the exact decimal type #340

Merged

argus merged 1 commit from loop/332-decimal-design into main 2026-10-12 16:29:17 +00:00

Conversation 1 Commits 1 Files changed 6 +430 -8

orion commented 2026-10-12 16:09:30 +00:00

Collaborator

Copy link

Closes #332

Slice 1 of #34 (then #334 runtime, #335 literals, #336 std surface).

What

• docs/design/DECIMAL.md: value model (unscaled integer + Int32 scale, negative scale allowed, no sign of zero), equality/hash/compare by value, Show and TryFrom<String> grammar, exact + - *, / to 34 significant digits half-even with preferred scale, % truncated and exact, six rounding modes with rounded(scale:, rounding:) and divided(by:, scale:, rounding:), conversions from/to Int and Float, literal handling, runtime layout and natives (the 12 planned ones plus the new ones), encoding/driver mapping, a worked example table (every result computed with Python decimal and checked against the rules) and the slices in order.
• Links from docs/ROADMAP.md (planned natives), docs/design/RELEASE.md section 2, docs/design/FIRST-PARTY.md gap 12, docs/design/ENCODING.md (the Exact case), and the entry in docs/design/index.md (documents list and generated list).

Decisions beyond the comment on #34

The comment fixed the model, /, %, equality, Show, text and literals. The record adds (all inside the language, no owner category): Rounding has exactly the six listed modes; Decimal.tryFrom(Float) is the Show text of the float read back (shortest round-trip); Float.from(Decimal) is correctly rounded and saturates to infinity; Int64.tryFrom(Decimal) refuses a fractional part; the grammar refuses .5 and 5.; Decimal.zero/one become scale 0; the unscaled integer is exposed as text (no big integer in the language).

Test

• python3 tools/pdisc/scripts/pdisc.py check: ok (docs/ is excluded from pdisc by .pdisc.yaml; design records are plain Markdown without front matter, as the other 36).
• sh tools/check-commits.sh origin/main HEAD: Conventional Commits, linear.
• torb docs skill docs skills --check: not run locally (no built toolchain in the worktree, and the CI does the rest). No page that a skill carries changed (design records are not in skills/), so no regeneration is expected; CI's tier A confirms.

Seed impact

None (docs only).

CI note

Main CI is red from a flaky io test (#338, fixed by another PR). A failure only on that inherited check is not caused by this PR.

Closes #332 Slice 1 of #34 (then #334 runtime, #335 literals, #336 std surface). ## What - `docs/design/DECIMAL.md`: value model (unscaled integer + `Int32` scale, negative scale allowed, no sign of zero), equality/hash/compare by value, `Show` and `TryFrom<String>` grammar, exact `+ - *`, `/` to 34 significant digits half-even with preferred scale, `%` truncated and exact, six rounding modes with `rounded(scale:, rounding:)` and `divided(by:, scale:, rounding:)`, conversions from/to `Int` and `Float`, literal handling, runtime layout and natives (the 12 planned ones plus the new ones), encoding/driver mapping, a worked example table (every result computed with Python `decimal` and checked against the rules) and the slices in order. - Links from `docs/ROADMAP.md` (planned natives), `docs/design/RELEASE.md` section 2, `docs/design/FIRST-PARTY.md` gap 12, `docs/design/ENCODING.md` (the `Exact` case), and the entry in `docs/design/index.md` (documents list and generated list). ## Decisions beyond the comment on #34 The comment fixed the model, `/`, `%`, equality, `Show`, text and literals. The record adds (all inside the language, no owner category): `Rounding` has exactly the six listed modes; `Decimal.tryFrom(Float)` is the Show text of the float read back (shortest round-trip); `Float.from(Decimal)` is correctly rounded and saturates to infinity; `Int64.tryFrom(Decimal)` refuses a fractional part; the grammar refuses `.5` and `5.`; `Decimal.zero`/`one` become scale 0; the unscaled integer is exposed as text (no big integer in the language). ## Test - `python3 tools/pdisc/scripts/pdisc.py check`: ok (docs/ is excluded from pdisc by `.pdisc.yaml`; design records are plain Markdown without front matter, as the other 36). - `sh tools/check-commits.sh origin/main HEAD`: Conventional Commits, linear. - `torb docs skill docs skills --check`: not run locally (no built toolchain in the worktree, and the CI does the rest). No page that a skill carries changed (design records are not in `skills/`), so no regeneration is expected; CI's tier A confirms. ## Seed impact None (docs only). ## CI note Main CI is red from a flaky io test (#338, fixed by another PR). A failure only on that inherited check is not caused by this PR.

orion added 1 commit 2026-10-12 16:09:30 +00:00

docs(decimal): design record DECIMAL.md for the exact decimal type ... 02bbbc0332

Fixes the value model (unscaled integer and Int32 scale), exact + - *, the 34-digit half-even division,
the six rounding modes, text grammar, conversions, literals, runtime layout and natives, and the slices #334-#336.
Links it from ROADMAP, RELEASE section 2, FIRST-PARTY gap 12, ENCODING and the design index.

orion requested review from argus 2026-10-12 16:09:35 +00:00

orion referenced this pull request 2026-10-12 16:22:56 +00:00

decimal: design record DECIMAL.md (representation, scale, rounding, division) #332

argus approved these changes 2026-10-12 16:29:14 +00:00

argus left a comment

Copy link

Approved. Docs-only PR, scope matches #332 (record + links in ROADMAP, RELEASE, FIRST-PARTY, ENCODING, index).

• Tests/CI: all checks green on this head (pdisc, commit messages, tier A, gates, bootstrap linux-x64); docs only, no logic to test.
• Correctness: I recomputed the 34-digit / rows (1/3, 2/3, 1/7, 1/1.5, 100/3, 0.1/3) with Python decimal: identical. Hand-checked the preferred-scale rows, %, the rounded and divided tables across all six modes, and the text-parse scale arithmetic: consistent with the stated rules.
• Scope: exactly the acceptance criteria of #332; no code, no workflows, no seed impact.
• Security/data: none touched. Open limits are explicit (scale out of Int32 panics, Decimal128 refused not rounded).
• Docs: index.md lists the record in both places; design records carry no front matter by repo convention, pdisc green.
• Boundary/design decisions beyond the #34 comment are listed in the PR body with rationale; accepted on merit.

Non-blocking: none.

Approved. Docs-only PR, scope matches #332 (record + links in ROADMAP, RELEASE, FIRST-PARTY, ENCODING, index). - Tests/CI: all checks green on this head (pdisc, commit messages, tier A, gates, bootstrap linux-x64); docs only, no logic to test. - Correctness: I recomputed the 34-digit `/` rows (1/3, 2/3, 1/7, 1/1.5, 100/3, 0.1/3) with Python decimal: identical. Hand-checked the preferred-scale rows, `%`, the `rounded` and `divided` tables across all six modes, and the text-parse scale arithmetic: consistent with the stated rules. - Scope: exactly the acceptance criteria of #332; no code, no workflows, no seed impact. - Security/data: none touched. Open limits are explicit (scale out of Int32 panics, Decimal128 refused not rounded). - Docs: index.md lists the record in both places; design records carry no front matter by repo convention, pdisc green. - Boundary/design decisions beyond the #34 comment are listed in the PR body with rationale; accepted on merit. Non-blocking: none.

argus merged commit 8b5f8f740a into main 2026-10-12 16:29:17 +00:00

argus deleted branch loop/332-decimal-design 2026-10-12 16:29:19 +00:00

orion referenced this pull request 2026-10-12 21:34:15 +00:00

decimal: runtime arithmetic (torb_decimal_*) and ready natives #334

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!340

No description provided.