debugger: translate the emitted names in variables of a native session (step 4b of #42)

orion commented

2026-11-13 04:45:24 +00:00

Collaborator

Context

Step 4b of the epic #42 (debug native programs, DEBUGGER.md section 4). Step 4a (#720, PR #723) landed: torb debug with native: true builds the program with --debug, starts lldb-dap or gdb --interpreter=dap, and relays the session as it is (compiler/src/debugger/adapter.trb, readNative; compiler/src/debugger/native.trb). The names in the variables an editor reads are still C's (s12_count); section 4 and section 20 list translating them as open. The values are already formatted by the printers of steps 2 and 3 (tools/gdb/torb_printers.py, tools/lldb/torb_formatters.py, SLOT_NAME = ^s[0-9]+_(.+)$), which do the same for bt full, the machine interface and torb-locals.

Goal

An editor that reads the variables of a native session sees a binding by its source name (count, not s12_count), as it does in a VM session.

Requirements

R1. When the relay passes a variables response of the native debugger to the editor, the system shall replace each variable name that has the form s<digits>_<name> with <name>; any other name (a C temporary, torb_-prefixed runtime variables, a register, a name without the prefix) stays as it is.
R2. The relay shall not change value, type, variablesReference, evaluateName or the order of the variables, and shall not touch any other response or event; evaluateName stays the C expression, so that a later evaluate or setVariable still reaches the native debugger.
R3. When two variables of one response would get the same source name (shadowing in different blocks), the system shall keep the C name of the outer one and translate only the innermost (first listed), so that no two entries of a response show the same name. If that cannot be decided from the response alone, keep all colliding names as C names. The choice is recorded in section 4.
R4. The translation is a pure function in compiler/src/debugger/native.trb (sourceNameOf(cName): String, the same rule as the printers' SLOT_NAME), unit-tested in compiler/tests/debugger.test.trb without a debugger.
R5. A session of tests/debug-native/ shall read the scopes and variables of the top frame after the breakpoint, and print the variable names with their formatted values; tests/debug-native/session.expected pins them for lldb and gdb alike (the fixture gains a binding or a parameter when the current one has none in sight; the breakpoint line stays the one that ends in // break).

Acceptance criteria

sourceNameOf maps s12_count to count, s3_a_b to a_b, s_x, x, torb_tmp, s12_ and the empty text to themselves; tests in compiler/tests/debugger.test.trb pass.
The variables response of a stop in tests/debug-native/ shows source names for the program's bindings under both TORB_DEBUG_NATIVE=lldb and TORB_DEBUG_NATIVE=gdb; no s<digits>_ name remains in it.
tools/debug-native.sh is green on the forge CI (tier B, DEBUG_NATIVE_REQUIRE=lldb) with the extended session; the gdb run is checked where gdb 14+ is installed and skips with a message otherwise, as 4a does.
evaluateName and value of the variables are as the native debugger wrote them (shown in the session or in a compiler test of the relay function).
DEBUGGER.md section 4 (the sentence "Names are still C's ... translating the names is open"), section 18 (a row 11, Done) and section 20 (the "Native programs" item) are updated; section 16 needs no change.

Design record and size

Implements DEBUGGER.md section 4 (torb debug ... "translating names (s12_count to count) in variables") and section 20 "Native programs". One PR of two Conventional Commits: (1) sourceNameOf, the relay rewrite of variables responses, unit tests; (2) the extended session, session.expected, the design-record update.

Measure in the PR, do not ask: if one debugger's DAP already answers with source names through the printers' frame filter, the rewrite stays idempotent (a name without prefix is unchanged), and the session pins that.

Seed impact

None. TorbScript in compiler/src/debugger/ and a test fixture only: no syntax, native, driver flag or std name the compiler looks up by string.

Out of scope

Translating names in evaluate expressions, setVariable and output; breakpoint conditions in source names; the user docs (torb-debug.md, the editor guide) and the VS Code launch for a native program, which are step 5 of #42.

Dependencies

Parent: #42. Follows #720 (landed). #719 (step 2b of #41) is independent; both touch DEBUGGER.md sections 18 and 20, rebase after whichever lands first.

## Context Step 4b of the epic #42 (debug native programs, [DEBUGGER.md section 4](https://git.torb.dev/torbscript/language/src/branch/main/docs/design/DEBUGGER.md)). Step 4a (#720, PR #723) landed: `torb debug` with `native: true` builds the program with `--debug`, starts `lldb-dap` or `gdb --interpreter=dap`, and relays the session as it is (`compiler/src/debugger/adapter.trb`, `readNative`; `compiler/src/debugger/native.trb`). The names in the `variables` an editor reads are still C's (`s12_count`); section 4 and section 20 list translating them as open. The values are already formatted by the printers of steps 2 and 3 (`tools/gdb/torb_printers.py`, `tools/lldb/torb_formatters.py`, `SLOT_NAME = ^s[0-9]+_(.+)$`), which do the same for `bt full`, the machine interface and `torb-locals`. ## Goal An editor that reads the `variables` of a native session sees a binding by its source name (`count`, not `s12_count`), as it does in a VM session. ## Requirements - R1. When the relay passes a `variables` response of the native debugger to the editor, the system shall replace each variable `name` that has the form `s<digits>_<name>` with `<name>`; any other name (a C temporary, `torb_`-prefixed runtime variables, a register, a name without the prefix) stays as it is. - R2. The relay shall not change `value`, `type`, `variablesReference`, `evaluateName` or the order of the variables, and shall not touch any other response or event; `evaluateName` stays the C expression, so that a later `evaluate` or `setVariable` still reaches the native debugger. - R3. When two variables of one response would get the same source name (shadowing in different blocks), the system shall keep the C name of the outer one and translate only the innermost (first listed), so that no two entries of a response show the same name. If that cannot be decided from the response alone, keep all colliding names as C names. The choice is recorded in section 4. - R4. The translation is a pure function in `compiler/src/debugger/native.trb` (`sourceNameOf(cName): String`, the same rule as the printers' `SLOT_NAME`), unit-tested in `compiler/tests/debugger.test.trb` without a debugger. - R5. A session of `tests/debug-native/` shall read the scopes and variables of the top frame after the breakpoint, and print the variable names with their formatted values; `tests/debug-native/session.expected` pins them for lldb and gdb alike (the fixture gains a binding or a parameter when the current one has none in sight; the breakpoint line stays the one that ends in `// break`). ## Acceptance criteria - [ ] `sourceNameOf` maps `s12_count` to `count`, `s3_a_b` to `a_b`, `s_x`, `x`, `torb_tmp`, `s12_` and the empty text to themselves; tests in `compiler/tests/debugger.test.trb` pass. - [ ] The `variables` response of a stop in `tests/debug-native/` shows source names for the program's bindings under both `TORB_DEBUG_NATIVE=lldb` and `TORB_DEBUG_NATIVE=gdb`; no `s<digits>_` name remains in it. - [ ] `tools/debug-native.sh` is green on the forge CI (tier B, `DEBUG_NATIVE_REQUIRE=lldb`) with the extended session; the gdb run is checked where gdb 14+ is installed and skips with a message otherwise, as 4a does. - [ ] `evaluateName` and `value` of the variables are as the native debugger wrote them (shown in the session or in a compiler test of the relay function). - [ ] DEBUGGER.md section 4 (the sentence "Names are still C's ... translating the names is open"), section 18 (a row 11, Done) and section 20 (the "Native programs" item) are updated; section 16 needs no change. ## Design record and size Implements DEBUGGER.md section 4 (`torb debug` ... "translating names (`s12_count` to `count`) in `variables`") and section 20 "Native programs". One PR of two Conventional Commits: (1) `sourceNameOf`, the relay rewrite of `variables` responses, unit tests; (2) the extended session, `session.expected`, the design-record update. Measure in the PR, do not ask: if one debugger's DAP already answers with source names through the printers' frame filter, the rewrite stays idempotent (a name without prefix is unchanged), and the session pins that. ## Seed impact None. TorbScript in `compiler/src/debugger/` and a test fixture only: no syntax, native, driver flag or std name the compiler looks up by string. ## Out of scope Translating names in `evaluate` expressions, `setVariable` and `output`; breakpoint conditions in source names; the user docs (`torb-debug.md`, the editor guide) and the VS Code launch for a native program, which are step 5 of #42. ## Dependencies Parent: #42. Follows #720 (landed). #719 (step 2b of #41) is independent; both touch DEBUGGER.md sections 18 and 20, rebase after whichever lands first.

orion added the

loop

ready

labels

2026-11-13 04:45:24 +00:00

orion referenced this issue

2026-11-13 04:45:29 +00:00

debugger: debug native programs #42

orion referenced this issue

2026-11-13 04:45:30 +00:00

debugger: debug native programs #42

orion commented

2026-11-13 04:54:53 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261113 until 2026-11-13T10:54:52Z

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

2026-11-13 04:57:17 +00:00

feat(debugger): translate the emitted names in variables of a native session #732

orion referenced this issue

2026-11-13 05:56:27 +00:00

debugger: debug native programs #42

orion commented

2026-11-13 05:56:41 +00:00

Author

Collaborator

[loop:torbscript] claim review by session:loop-torbscript-20261113 until 2026-11-13T08:56:41Z
PR #732: job 'bootstrap (linux-x64)' is red; fix round on the same branch.

[loop:torbscript] claim review by session:loop-torbscript-20261113 until 2026-11-13T08:56:41Z PR #732: job 'bootstrap (linux-x64)' is red; fix round on the same branch.

orion commented

2026-11-13 07:42:29 +00:00

Author

Collaborator

[loop:torbscript] claim review by session:loop-torbscript-20261113 until 2026-11-13T10:42:00Z

orion commented

2026-11-13 08:06:50 +00:00

Author

Collaborator

[loop:torbscript] release review: fix worker hit the anthropic:notahumanmate weekly limit (reset 2026-11-15T20:00Z) without a report; it pushed 9764e55 to PR #732 first, CI running, PR not mergeable (conflict with main). next: fix round on the same branch with a rebase onto main when a worker slot on another profile is free

[loop:torbscript] release review: fix worker hit the anthropic:notahumanmate weekly limit (reset 2026-11-15T20:00Z) without a report; it pushed 9764e55 to PR #732 first, CI running, PR not mergeable (conflict with main). next: fix round on the same branch with a rebase onto main when a worker slot on another profile is free

orion commented

2026-11-13 08:16:53 +00:00

Author

Collaborator

[loop:torbscript] claim review by session:loop-torbscript-20261113 until 2026-11-13T11:20:00Z

orion commented

2026-11-13 08:47:56 +00:00

Author

Collaborator

[loop:torbscript] review: rebased loop/731-native-variable-names onto current main (one conflict in docs/design/DEBUGGER.md section 20, resolved by keeping both the worker-pool and the native-programs bullets) and folded the two fix commits into their parents, so PR #732 is two Conventional Commits again (tools/check-commits.sh clean, tree identical to the previous head 9764e55f). Force-pushed with lease to the loop/* branch, new head 62383f9c. CI on it after 30 min: bootstrap (linux-x64) (red before), cross-compiles, commit messages and pdisc green; gates, tier A and tier B still pending, no red job yet. Nothing run locally (no toolchain). Worker usage: roughly 0.1M tokens (sonnet). next: waiting (CI)

[loop:torbscript] review: rebased `loop/731-native-variable-names` onto current `main` (one conflict in `docs/design/DEBUGGER.md` section 20, resolved by keeping both the worker-pool and the native-programs bullets) and folded the two fix commits into their parents, so PR #732 is two Conventional Commits again (`tools/check-commits.sh` clean, tree identical to the previous head 9764e55f). Force-pushed with lease to the `loop/*` branch, new head 62383f9c. CI on it after 30 min: `bootstrap (linux-x64)` (red before), cross-compiles, commit messages and pdisc green; `gates`, tier A and tier B still pending, no red job yet. Nothing run locally (no toolchain). Worker usage: roughly 0.1M tokens (sonnet). next: waiting (CI)

argus closed this issue

2026-11-13 09:34:28 +00:00

orion commented

2026-11-13 09:34:54 +00:00

Author

Collaborator

Merged as PR #732 (merge commit 7dbb3fa53b). Verified after merge: no 'After merge' section; the repo has no x.y.z tag yet (only nightly tags; project.trb is 0.1.0). Release cadence (docs/design/RELEASE.md section 3): the next minor is cut on the first Tuesday of the month, its release candidate the Tuesday before, so the change ships with the 0.2.0 line on the calendar (rc Tue 2026-11-24, minor Tue 2026-12-01), not as an off-cadence release. Next step: include it in that rc/minor; nothing else is open on this task.

Merged as PR #732 (merge commit 7dbb3fa53b). Verified after merge: no 'After merge' section; the repo has no x.y.z tag yet (only nightly tags; project.trb is 0.1.0). Release cadence (docs/design/RELEASE.md section 3): the next minor is cut on the first Tuesday of the month, its release candidate the Tuesday before, so the change ships with the 0.2.0 line on the calendar (rc Tue 2026-11-24, minor Tue 2026-12-01), not as an off-cadence release. Next step: include it in that rc/minor; nothing else is open on this task.

orion referenced this issue

2026-11-13 10:00:57 +00:00

debugger: debug native programs #42

Rows
Columns

debugger: translate the emitted names in variables of a native session (step 4b of #42) #731

Context

Goal

Requirements

Acceptance criteria

Design record and size

Seed impact

Out of scope

Dependencies