Skip to content

feat(runtime): add a Web global surface that hides the Node names - #502

Merged
x-ror merged 1 commit into
masterfrom
feat/global-surface-web
Nov 18, 2026
Merged

x-ror merged 1 commit into
masterfrom
feat/global-surface-web

Conversation

@x-ror

@x-ror x-ror commented Nov 18, 2026

Copy link
Copy Markdown
Owner

What changed

eval takes a trailing surface: Global_Surface = .Node.

  • .Node is what every context got before. It stays the default, and run_file and the CLI never select anything else.
  • .Web exposes the web-platform subset only. Not reachable: process, require, module, exports, __filename, __dirname, Buffer, global, setImmediate/clearImmediate, and every __lava* hook.

This is the seam Larva needs for page contexts (x-ror/larva#5). It lands here so that globals.odin and runtime.odin do not diverge downstream; Larva will only select the surface.

How .Web gets there (the contract comment on Global_Surface in runtime.odin has the full version):

  1. Never injected: the CommonJS entry bindings (setup_module_environment).
  2. Not installed: install_stdio. internal/stdio and the node-streams stack are never compiled; console writes through its own native writer.
  3. Installed for the bootstrap, then removed as the last step before user code: process, Buffer, setImmediate, clearImmediate, global.
  4. An .mjs source name is Invalid_Input (exit 2), and no top-level nextTick drain is appended.

The one change on the default path

__lavaDrainNextTicks and __lava_tl_drain are now defined from install_microtasks instead of microtasks.js, on .Node only. They are non-configurable, so a .Web context could not have deleted them. The attributes are the same as before. Top-level nextTick → promise → queueMicrotask order is unchanged against node 26 (nt,p,qm on both), and event-loop oracle cases 09 and 10 pass.

What .Web does not promise

The names are gone, nothing more. Web APIs still hand out Buffer-backed bytes and ERR_* codes, so Buffer stays reachable through a value's .constructor. That is the "browser-shaped errors and bytes" part of x-ror/larva#5. No CLI flag selects the surface.

Reuse verdict (§2)

No new low-level code: a parameter, a five-name loop over JSObjectDeleteProperty, and two JSObjectSetProperty calls that replace two Object.defineProperty calls.

Node parity

  • .Node: unchanged. Every oracle suite passes unedited.
  • .Web: a Lava-only surface (node has one global surface), a declared §1 deviation. Pinned by cmd/lava/global_surface_test.odin: every hidden name by typeof and in, every kept API exercised rather than merely present, .mjs refused, stdio never compiled, and Node/Web/Node alternating on one thread.

Tests and mutations

Four tests in cmd/lava/global_surface_test.odin. Seven mutations recorded in tests/mutation-manifest.json:

  • Buffer dropped from the removal list
  • .Web falls through to the CommonJS entry bindings
  • install_stdio runs on .Web
  • eval stops refusing .mjs on .Web
  • install_microtasks defines the drain hooks on .Web
  • eval appends the top-level drain on .Web
  • eval's default surface is not .Node

make test-mutation CHANGED=1: 53/53 died as recorded (the seven above plus the 46 existing entries this diff can affect).

Gates

Run locally on this commit's tree, Node 26.13.1, 16 cores. All passed:

  • make check (incl. windows and darwin front-ends), make check-js, make check-md, make check-actions, make build
  • make test: 140 Odin tests; node-compat (91 cases), sqlite, fs and event-loop oracles
  • make test-odin-serial, make test-eventloop-odin, make test-lava-nohostfn, make test-stdio, make test-property
  • smokes: fetch, net, http, https, multicore, zerocopy
  • make bench-gate
  • make test-mutation CHANGED=1

Not done: /pr-gate has not been run on this branch. CI has 4 cores, so the concurrency-sensitive gates above are not proof of a pass there.

No perf claim. make bench-gate passes with startup at 1.37x against its 3x cap.

Open for review

  • Deleting properties from the global object may push it into JSC's dictionary mode on .Web contexts. Not measured here; it will be measured on Larva's bench/pages once pages select .Web.
  • Noticed and left alone: __lava_precache is an enumerable global on .Node today (Object.keys(globalThis) shows it; node shows nothing of the kind).

🤖 Generated with Claude Code

eval takes a trailing `surface: Global_Surface = .Node`. `.Node` is what every
context got before and stays the default; `run_file` and the CLI never select
anything else. `.Web` exposes the web-platform subset only: no `process`,
`require`, `module`, `exports`, `__filename`, `__dirname`, `Buffer`, `global`,
`setImmediate`/`clearImmediate`, and no `__lava*` hook.

How `.Web` gets there:
- the CommonJS entry bindings are never injected;
- install_stdio does not run, so internal/stdio and the node-streams stack are
  never compiled (console writes through its own native writer);
- `process`, `Buffer`, `setImmediate`, `clearImmediate` and `global` are
  installed for the bootstrap and removed as the last step before user code;
- an `.mjs` source name is Invalid_Input, and no top-level nextTick drain is
  appended.

The one change on the default path: `__lavaDrainNextTicks` and
`__lava_tl_drain` are now defined from install_microtasks instead of
microtasks.js, with the same attributes. They are non-configurable, so a `.Web`
context could not have deleted them.

`.Web` promises that the names are gone, nothing more: web APIs still hand out
Buffer-backed bytes and `ERR_*` codes (x-ror/larva#5).

Pinned by cmd/lava/global_surface_test.odin; seven mutations recorded in
tests/mutation-manifest.json.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@x-ror
x-ror merged commit f54b283 into master Nov 18, 2026
8 checks passed
@x-ror
x-ror deleted the feat/global-surface-web branch November 18, 2026 21:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant