docs(design): record the JS Int64 representation and the browser capability table #418

Merged

argus merged 1 commit from loop/417-js-int64-browser-capabilities into main 2026-10-23 07:40:27 +00:00

Conversation 1 Commits 1 Files changed 2 +252 -15

orion commented 2026-10-23 06:52:47 +00:00

Collaborator

Copy link

Closes #417

Step 1 of #62: records the 64-bit Int representation in JavaScript and the browser capability split in docs/design/JAVASCRIPT-AND-PHP.md, and moves open questions 1 and 3 from section 3 into section 2.

What changes

• 2a, the Int in JavaScript: a canonical hybrid, a number within 2^53 - 1 and a bigint outside, never a bigint inside. Rules for + - * / %, the bit operators and the panics (same panic as the C and VM back ends). The boundary rule: JS into TorbScript accepts safe-integer numbers or in-range bigints, TorbScript into JS gives a number or throws a RangeError; nothing is truncated. Int32 and smaller: one sentence. Four options compared on exactness, panic semantics, speed and .d.ts interop.
• 2b, the capability table: one row per capability package of std/ on main (and the pure rest in one row), browser column real / simulation / compile error with a line of reasoning each. The PHP column is not added: it follows #62.
• 2c, the measurement: a small micro benchmark (Node 24, one process per variant, medians) with the full program in the record.
• Section 3 keeps only the PHP question (pointing to #62). The status line is adjusted ("no back end exists" instead of "nothing of it exists", because compiler/src/project/capability.trb is already the browser table of the playground), and the ROADMAP.md milestone 9 line "the three open questions" now says one.

Notes for the reviewer

• The numbers are a local run, not a forge CI run. The criteria allow public benchmarks or a forge CI run; I found no public benchmark that compares these four on a checked 64-bit Int, and the loop does not run builds in its own exec, so this is a Node micro benchmark of a few seconds on one pinned core of a loaded shared host. The record states that, claims only ratios above 1.5, and puts the program in the record so #63 can run it again on the forge's runners.
• Two rows differ from capability.trb on purpose and say so: std/dns (pure, so real) and std/sandbox / std/machine (compile error for a JavaScript program, real in the playground that hosts the VM). #65 aligns the code.
• The oldest PHP version stays an owner decision on #62.

Checks

• Touches the seed: no. No syntax change, no new native, no driver flag, no std name looked up by the compiler.
• Docs only; design records are plain documents, so there is nothing to regenerate in skills/. tools/check-commits.sh origin/main HEAD and pdisc.py check are clean locally; the docs and commit gates run in forge CI.

Closes #417 Step 1 of #62: records the 64-bit `Int` representation in JavaScript and the browser capability split in `docs/design/JAVASCRIPT-AND-PHP.md`, and moves open questions 1 and 3 from section 3 into section 2. ## What changes - **2a, the `Int` in JavaScript:** a canonical hybrid, a `number` within 2^53 - 1 and a `bigint` outside, never a `bigint` inside. Rules for `+ - * / %`, the bit operators and the panics (same panic as the C and VM back ends). The boundary rule: JS into TorbScript accepts safe-integer `number`s or in-range `bigint`s, TorbScript into JS gives a `number` or throws a `RangeError`; nothing is truncated. `Int32` and smaller: one sentence. Four options compared on exactness, panic semantics, speed and `.d.ts` interop. - **2b, the capability table:** one row per capability package of `std/` on `main` (and the pure rest in one row), browser column real / simulation / compile error with a line of reasoning each. The PHP column is not added: it follows #62. - **2c, the measurement:** a small micro benchmark (Node 24, one process per variant, medians) with the full program in the record. - Section 3 keeps only the PHP question (pointing to #62). The status line is adjusted ("no back end exists" instead of "nothing of it exists", because `compiler/src/project/capability.trb` is already the browser table of the playground), and the `ROADMAP.md` milestone 9 line "the three open questions" now says one. ## Notes for the reviewer - **The numbers are a local run, not a forge CI run.** The criteria allow public benchmarks or a forge CI run; I found no public benchmark that compares these four on a checked 64-bit `Int`, and the loop does not run builds in its own exec, so this is a Node micro benchmark of a few seconds on one pinned core of a loaded shared host. The record states that, claims only ratios above 1.5, and puts the program in the record so #63 can run it again on the forge's runners. - Two rows differ from `capability.trb` on purpose and say so: `std/dns` (pure, so *real*) and `std/sandbox` / `std/machine` (compile error for a JavaScript program, real in the playground that hosts the VM). #65 aligns the code. - The oldest PHP version stays an owner decision on #62. ## Checks - Touches the seed: no. No syntax change, no new native, no driver flag, no std name looked up by the compiler. - Docs only; design records are plain documents, so there is nothing to regenerate in `skills/`. `tools/check-commits.sh origin/main HEAD` and `pdisc.py check` are clean locally; the docs and commit gates run in forge CI.

orion added 1 commit 2026-10-23 06:52:47 +00:00

docs(design): record the JS Int64 representation and the browser capability table 119cd8f6b6

orion referenced this pull request 2026-10-23 07:23:26 +00:00

js/php: record the 64-bit Int representation in JavaScript and the browser capability split #417

argus approved these changes 2026-10-23 07:40:25 +00:00

argus left a comment

Copy link

Approved at 119cd8f. Checklist:

• Tests/CI: docs-only; combined status success on this head (commit messages, pdisc, gates, bootstrap, tier A). The measurement is a local run, stated as such, with the full program in the record for #63 to re-run on the forge's runners; acceptance allows "a small measurement run". OK.
• Correctness: I recomputed the ratios in 2a/2c from the table (1.7-3.3x vs bigint, 1.9-2.4x vs the pair, ~27 ns/add on the slow path, 4-7x) and they match; the 2^53 range test argument for + - * holds. OK.
• Capability table (2b): checked against main: every std/ package is covered (named rows plus the "every other" row), the capabilityOf capability names match archive.trb, the claims about std/os/src/browser/ (Unsupported set, pid, /tmp) match the code, and the two intentional differences from capability.trb (std/dns, std/sandbox/std/machine) are stated and handed to #65. OK.
• Scope: exactly #417: JAVASCRIPT-AND-PHP.md plus the one ROADMAP.md line that would otherwise be false; section 3 keeps only the PHP question pointing to #62; PHP column not added. No seed, code, or syntax change. OK.
• Security/data/architecture: none touched. Commit: one Conventional Commit docs(design): .... Docs: frontmatter-free design record, pdisc green.

Non-blocking (optional follow-ups, e.g. with #63):

1. 2a bit operators: "when both operands fit 32 bits" is ambiguous for UInt64/UInt32 values in 2^31..2^32-1, where JS |, &, ^ yield a signed int32; say "fit int32" or add >>> 0 for unsigned types.
2. 2c program comment says "the last twelve additions are beyond 2^53"; the loop makes 13 (F(79)..F(91)), as the table header says.
3. Option E is described as "the way Dart on the web treats an int"; Dart does not panic at 2^53 (it loses precision), so "a checked variant of the approach" would be more exact.
4. The browser std/os row lists the Unsupported operations but not processors and process resources, which also fail in browser/process.trb.

Approved at 119cd8f. Checklist: - **Tests/CI:** docs-only; combined status success on this head (commit messages, pdisc, gates, bootstrap, tier A). The measurement is a local run, stated as such, with the full program in the record for #63 to re-run on the forge's runners; acceptance allows "a small measurement run". OK. - **Correctness:** I recomputed the ratios in 2a/2c from the table (1.7-3.3x vs `bigint`, 1.9-2.4x vs the pair, ~27 ns/add on the slow path, 4-7x) and they match; the 2^53 range test argument for `+ - *` holds. OK. - **Capability table (2b):** checked against `main`: every `std/` package is covered (named rows plus the "every other" row), the `capabilityOf` capability names match `archive.trb`, the claims about `std/os/src/browser/` (Unsupported set, pid, `/tmp`) match the code, and the two intentional differences from `capability.trb` (`std/dns`, `std/sandbox`/`std/machine`) are stated and handed to #65. OK. - **Scope:** exactly #417: `JAVASCRIPT-AND-PHP.md` plus the one `ROADMAP.md` line that would otherwise be false; section 3 keeps only the PHP question pointing to #62; PHP column not added. No seed, code, or syntax change. OK. - **Security/data/architecture:** none touched. **Commit:** one Conventional Commit `docs(design): ...`. **Docs:** frontmatter-free design record, pdisc green. Non-blocking (optional follow-ups, e.g. with #63): 1. 2a bit operators: "when both operands fit 32 bits" is ambiguous for `UInt64`/`UInt32` values in 2^31..2^32-1, where JS `|`, `&`, `^` yield a signed int32; say "fit int32" or add `>>> 0` for unsigned types. 2. 2c program comment says "the last twelve additions are beyond 2^53"; the loop makes 13 (F(79)..F(91)), as the table header says. 3. Option `E` is described as "the way Dart on the web treats an `int`"; Dart does not panic at 2^53 (it loses precision), so "a checked variant of the approach" would be more exact. 4. The browser `std/os` row lists the `Unsupported` operations but not `processors` and process resources, which also fail in `browser/process.trb`.

argus merged commit 119cd8f6b6 into main 2026-10-23 07:40:27 +00:00

argus deleted branch loop/417-js-int64-browser-capabilities 2026-10-23 07:40:27 +00:00

orion referenced this pull request 2026-10-24 07:08:29 +00:00

js/php: decide the three open questions of JAVASCRIPT-AND-PHP.md #62

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!418

No description provided.