Skip to content

Phase 7.8: clazel-js, the embedding API implemented (first part) - #287

Open
atiernan wants to merge 11 commits into
claude/js-builtinsfrom
claude/js-api-impl
Open

atiernan wants to merge 11 commits into
claude/js-builtinsfrom
claude/js-api-impl

Conversation

@atiernan

Copy link
Copy Markdown
Member

Based on #269 (claude/js-builtins), and merges #223 (claude/js-api-contract, the clazel-js contract). Tier 0, no proofs. The contract's signatures are unchanged; what the VM lacks returns Error::NotImplemented.

What works

Runtime::new (VM, built-ins, host), scope, run_jobs, terminator, limits, heap_used (an estimate); primitives and strings (UTF-16 exact), kind and the as_*/to_*/is_* conversions, strict_equals, same_value, instance_of; new_object, get, set, has_property, define_property (data properties), get_prototype_of, set_prototype_of, get_method, call, construct; function, define_method, Args, new_host_object with host_data, get_prototype_from_constructor, host_mut, check_terminated; errors, new_exception, throw_error, throw, report, Error::Thrown; create_realm (once), global, realm and script host data; compile_script, run_script, eval_script; Handle, Weak, Member; gc and clear_kept_objects as no-ops. Integration tests use the public API only (tests/api.rs, 34 tests), plus doctests.

What returns NotImplemented, and why

Each because the VM lacks the feature: arrays (new_array*), promises, iterate, symbols (new_symbol, well_known_symbol), BigInt, ArrayBuffer, delete_property (the heap cannot remove a property), accessor descriptors in define_property, modules and synthetic modules (no module goal in the compiler, no module records in the runtime), a second realm and RealmOptions::global, construct with a new_target other than the constructor, instance_of of a bound function, ErrorKind::EvalError and UriError.

Deviations (also in the README)

  • No completion value: run_script/eval_script return undefined; the compiler produces none.
  • Error::Busy on re-entrance: closures are stored in the VM's embedder slot and taken out while they run, so a closure re-entered while running gets Busy.
  • Nothing rooted: there is no collector in this tree. Local/Handle/Weak/Member are checked but root nothing, Weak::upgrade is always Some, trace hooks are never called. The API needs no signature change for a collector to start rooting.
  • No host hooks called: the VM has no promises, modules, Date, string eval or FinalizationRegistry to call them; run_jobs returns 0. HostObject's exotic hooks are not called either.
  • Estimated limits: heap_bytes and value_stack_bytes map to the arena's cell limit and frame slots; the heap limit gives OutOfMemory, not RangeError; native_depth counts only closures made by Scope::function.
  • No source positions: ErrorReport::stack is empty, Source::start_line unused.

Proposed contract changes (README open questions 14-16; not made here)

  1. Add Sync to the Scope::function closure bound (Fn + Send + Sync), so re-entrance works instead of Busy.
  2. Make bigint_from_*, new_symbol and well_known_symbol return Result (today the error is held for the next fallible call); string/string_utf16 could do the same for OutOfMemory.
  3. A doc note that run_script's completion value is not produced until the compiler does.

Commits

  • Phase 7.8: an embedder slot in the VM, and DefinePropertyOrThrow public (no change to spec.rs, ops.rs, lemmas.rs or mutations.json)
  • Phase 7.8: clazel-js, the embedding API implemented (first part)
  • clazel-js: limits_are_the_embedders split into three tests, the heap-limit one with a smaller heap under Miri (it took 599 s there, over CI's 300 s limit)

Command results

  • cargo fmt --check: clean
  • cargo clippy -p clazel-js --all-targets -- -D warnings: clean
  • cargo xtask check: STATIC CHECKS PASSED
  • cargo test -p clazel-js: unit 6, api 34, doctests 27, further 2: all pass
  • Miri (cargo +nightly-2026-08-21 miri test -p clazel-js --test api): an earlier full run passed 32/32 api tests. After the split, 34/34 pass; the three tests that replace limits_are_the_embedders (heap too small, heap limit, value-stack limit) took 42.85 s together (previously 599 s for the one test).

CI's full verification has not run on this PR (cargo xtask verify --changed was not run either; only the checks above).

🤖 Generated with Claude Code

atiernan and others added 11 commits November 21, 2026 17:16
phase-7.md's boundary says engine crates depend on no browser crate and that
cargo xtask check enforces it through an ENGINE list next to PLACES. The list
did not exist. It names the clazel-js crates, rejects any path (direct or
through another crate) to a browser crate, and fails on a clazel-js* crate
missing from the list. clazel-js is placed in the Renderer component.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The public types, traits and signatures of the engine's embedding API, with a
README stating the rules and doc examples that compile (no_run). Every
operation that needs the engine returns Error::NotImplemented; the Terminator,
DefaultHost and Limits are real because they are small. Tier 0, no
dependencies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolves Cargo.lock (main's, plus clazel-js), and adds clazel-js-heap,
merged into main by #207, to the ENGINE list, which every clazel-js* crate
must be on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…domness)

Miri's isolation refuses clock_gettime(REALTIME), so default_host_answers_for_the_world
failed the 'crates without proofs' Miri job. The normal test job still runs it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
It used clazel-js-heap, which is now on the list (merged by #207), so the
test failed. A made-up name keeps it independent of which crates exist.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both are on main now (#213, #212), and the check requires every clazel-js*
crate on the list. phase-7.md counts clazel-json as an engine crate too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tins in ENGINE

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Vm::set_embedder, embedder and embedder_mut keep the embedding API's state
inside the VM, where a plain-fn-pointer native can find it again. The
built-ins' Descriptor and define_property_or_throw become pub so clazel-js
can define properties by the same algorithm. No change to spec.rs, ops.rs,
lemmas.rs or mutations.json.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Runtime, Scope, values and handles, native functions, host objects, errors,
scripts and the terminator over clazel-js-vm and clazel-js-builtins, without
changing a signature of the contract. What the VM lacks returns
NotImplemented; the README's "What is implemented" lists each item.
Integration tests use the public API only, and the doctests run where the
feature exists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…i (untimed WIP)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@atiernan

Copy link
Copy Markdown
Member Author

Included in #286, which verifies all open phase 7 pull requests together; this merges with it.

This branch has not been deployed

No deployments
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