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

orion commented

2026-10-23 06:27:41 +00:00

Collaborator

Context

Step 1 of #62 (split off just in time). Section 3 of JAVASCRIPT-AND-PHP.md lists three open questions. Two of them are technical design choices the loop decides with research: how an exact 64-bit Int is represented in JavaScript, and which capabilities are real, simulated or a compile error in the browser. The third (oldest supported PHP) stays on #62 as an owner decision. This step unblocks #63 and the browser half of #65.

Goal

A docs-only change to docs/design/JAVASCRIPT-AND-PHP.md that answers open questions 1 and 3 with their research and moves them from section 3 ("Open") into section 2 ("What is decided").

Acceptance criteria

Question 1: the record names one representation of an exact 64-bit Int inside generated JavaScript and one rule for the boundary to JavaScript code (what crosses as number, BigInt or a checked value, and what happens when a value does not fit 53 bits). At least three options (BigInt everywhere; a number pair or BigInt64Array-style split; exact arithmetic on number with overflow checks in the range that fits) are compared on exactness, panic-on-overflow semantics (identical to the C and VM back ends), speed and interop with .d.ts output, with numbers from public benchmarks or a small measurement run in forge CI, not a guess. Int32 and smaller types are covered in one sentence.
Question 3: the record has a table, one row per capability package of std/ (fs, os, process, net, time, random, crypto, and whichever others exist on main), with the browser column set to real, simulation or compile error at the import, and one line of reasoning per row (File System Access API or origin private file system for std/fs, empty environment for std/os, std/process a compile error). The PHP column stays empty or marked "follows #62"; the table is the input for #65, not its implementation.
Section 3 keeps only the PHP question (pointing to #62); the status line and ROADMAP.md milestone 9 text stay true.
Touches the seed: no. No syntax change, no new native, no driver flag, no std name looked up by the compiler.
One Conventional Commit docs(design): ...; docs checks and skills/ regeneration as CLAUDE.md asks; frontmatter/links of the record intact.

Scope

docs/design/JAVASCRIPT-AND-PHP.md (and skills/ if the docs generator requires it).

Out of scope

The oldest supported PHP version (owner decision on #62), the PHP column of the capability table.
Any code: no JavaScript back end (#63), no checker rule for unsupported imports (#65), no packages (#66).
Seed, releases, ROADMAP.md milestones as a whole.

Dependencies

None. Blocks #63; blocks the browser part of #65. Parent: #62.

## Context Step 1 of #62 (split off just in time). Section 3 of [JAVASCRIPT-AND-PHP.md](https://git.torb.dev/torbscript/language/src/branch/main/docs/design/JAVASCRIPT-AND-PHP.md) lists three open questions. Two of them are technical design choices the loop decides with research: how an exact 64-bit `Int` is represented in JavaScript, and which capabilities are real, simulated or a compile error in the browser. The third (oldest supported PHP) stays on #62 as an owner decision. This step unblocks #63 and the browser half of #65. ## Goal A docs-only change to `docs/design/JAVASCRIPT-AND-PHP.md` that answers open questions 1 and 3 with their research and moves them from section 3 ("Open") into section 2 ("What is decided"). ## Acceptance criteria - [ ] Question 1: the record names one representation of an exact 64-bit `Int` inside generated JavaScript and one rule for the boundary to JavaScript code (what crosses as `number`, `BigInt` or a checked value, and what happens when a value does not fit 53 bits). At least three options (`BigInt` everywhere; a `number` pair or `BigInt64Array`-style split; exact arithmetic on `number` with overflow checks in the range that fits) are compared on exactness, panic-on-overflow semantics (identical to the C and VM back ends), speed and interop with `.d.ts` output, with numbers from public benchmarks or a small measurement run in forge CI, not a guess. `Int32` and smaller types are covered in one sentence. - [ ] Question 3: the record has a table, one row per capability package of `std/` (`fs`, `os`, `process`, `net`, `time`, `random`, `crypto`, and whichever others exist on `main`), with the browser column set to real, simulation or compile error at the import, and one line of reasoning per row (File System Access API or origin private file system for `std/fs`, empty environment for `std/os`, `std/process` a compile error). The PHP column stays empty or marked "follows #62"; the table is the input for #65, not its implementation. - [ ] Section 3 keeps only the PHP question (pointing to #62); the status line and `ROADMAP.md` milestone 9 text stay true. - [ ] Touches the seed: no. No syntax change, no new native, no driver flag, no std name looked up by the compiler. - [ ] One Conventional Commit `docs(design): ...`; docs checks and `skills/` regeneration as `CLAUDE.md` asks; frontmatter/links of the record intact. ## Scope - `docs/design/JAVASCRIPT-AND-PHP.md` (and `skills/` if the docs generator requires it). ## Out of scope - The oldest supported PHP version (owner decision on #62), the PHP column of the capability table. - Any code: no JavaScript back end (#63), no checker rule for unsupported imports (#65), no packages (#66). - Seed, releases, `ROADMAP.md` milestones as a whole. ## Dependencies None. Blocks #63; blocks the browser part of #65. Parent: #62.

orion added the

loop

ready

labels

2026-10-23 06:27:41 +00:00

orion referenced this issue

2026-10-23 06:27:49 +00:00

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

orion referenced this issue

2026-10-23 06:28:01 +00:00

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

orion commented

2026-10-23 06:37:40 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261023 until 2026-10-23T12:37:00Z

orion referenced this issue from a pull request that will close it,

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

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

orion commented

2026-10-23 07:23:26 +00:00

Author

Collaborator

[loop:torbscript] implement: PR #418 (docs only, docs/design/JAVASCRIPT-AND-PHP.md plus one ROADMAP sentence), next: review by the merge gate (argus).

Records the canonical hybrid 64-bit Int for JS (number up to ±(2^53−1), bigint beyond, never a bigint inside), the checked boundary rule (RangeError / TypeError, no truncation), and the per-std-package capability table for the browser. Open questions 1 and 3 moved into section 2; section 3 keeps only the PHP question.
The benchmark numbers come from a local micro benchmark (one variant per process), not from forge CI; the program is embedded in the record so #63 can rerun it. No public benchmark was found to cite.
The capability table diverges from compiler/src/project/capability.trb in three places, flagged for #65: std/dns (pure, so real), and std/sandbox / std/machine (compile error for a JS program, real in the playground that hosts the VM).
CI on head 119cd8f6: commit messages, change detection and pdisc are green. The remaining jobs (tier A/B, gates, bootstrap, cross builds) were still queued when I stopped waiting after 30 minutes. The runner pool is busy with other PRs, and nothing has failed. This change touches no code.
Worker usage: implement inline, no sub-worker.

[loop:torbscript] implement: PR https://git.torb.dev/torbscript/language/pulls/418 (docs only, `docs/design/JAVASCRIPT-AND-PHP.md` plus one ROADMAP sentence), next: review by the merge gate (argus). - Records the canonical hybrid 64-bit `Int` for JS (`number` up to ±(2^53−1), `bigint` beyond, never a `bigint` inside), the checked boundary rule (`RangeError` / `TypeError`, no truncation), and the per-`std`-package capability table for the browser. Open questions 1 and 3 moved into section 2; section 3 keeps only the PHP question. - The benchmark numbers come from a local micro benchmark (one variant per process), not from forge CI; the program is embedded in the record so #63 can rerun it. No public benchmark was found to cite. - The capability table diverges from `compiler/src/project/capability.trb` in three places, flagged for #65: `std/dns` (pure, so real), and `std/sandbox` / `std/machine` (compile error for a JS program, real in the playground that hosts the VM). - CI on head 119cd8f6: commit messages, change detection and pdisc are green. The remaining jobs (tier A/B, gates, bootstrap, cross builds) were still queued when I stopped waiting after 30 minutes. The runner pool is busy with other PRs, and nothing has failed. This change touches no code. - Worker usage: implement inline, no sub-worker.