docs(engine): add spec references for bytecode internals

core/engine/src/bytecompiler/expression/mod.rs

@@ -1,3 +1,12 @@
+//! Lowering for ECMAScript expressions.
+//!
+//! The functions in this module implement the bytecompiler side of expression evaluation. They
+//! preserve the source language evaluation order while translating AST nodes into opcode sequences
+//! that the VM can execute later. See the ECMAScript expression grammar and runtime semantics in
+//! the [specification][spec].
+//!
+//! [spec]: https://tc39.es/ecma262/#sec-ecmascript-language-expressions
+
 mod assign;
 mod binary;
 mod object_literal;

core/engine/src/bytecompiler/mod.rs

@@ -7,6 +7,18 @@
 //! producing code blocks that are later executed by the VM.
 //!
 //! This module provides the necessary functionality to compile JavaScript code into bytecode.
+//! Conceptually, it is the bridge between the spec's runtime semantics and Boa's opcode-based VM.
+//! When the ECMAScript algorithms use the `!` prefix for an abstract operation, Boa treats the
+//! corresponding assumption as an internal compiler or bytecode invariant, and documents that
+//! mapping near the assertion sites that rely on it.
+//!
+//! Relevant specification entry points include [script evaluation][script],
+//! [module evaluation][module], and the expression and statement [runtime semantics][evaluation]
+//! that eventually feed into those top-level algorithms.
+//!
+//! [script]: https://tc39.es/ecma262/#sec-runtime-semantics-scriptevaluation
+//! [module]: https://tc39.es/ecma262/#sec-moduleevaluation
+//! [evaluation]: https://tc39.es/ecma262/#sec-runtime-semantics-evaluation
 
 mod class;
 mod declaration;

core/engine/src/vm/opcode/args.rs

@@ -1,3 +1,9 @@
+//! Encoding and decoding helpers for opcode operands.
+//!
+//! The VM only decodes bytecode emitted and patched by Boa. Because of that, these helpers rely on
+//! internal invariants instead of returning recoverable errors for malformed operand layouts. If
+//! decoding fails, it points to a compiler or bytecode management bug.
+
 use thin_vec::ThinVec;
 
 use super::{Address, IndexOperand, RegisterOperand};
@@ -38,6 +44,8 @@ unsafe impl Readable for (u32, u32, u32, u32, u32) {}
 pub(super) fn read<T: Readable>(bytes: &[u8], offset: usize) -> (T, usize) {
     let new_offset = offset + size_of::<T>();
 
+    // The VM only executes bytecode emitted and patched by Boa, so a short operand stream means an
+    // internal invariant was broken earlier in compilation or patching.
     assert!(bytes.len() >= new_offset, "buffer too small to read type T");
 
     // Safety: The assertion above ensures that the slice is large enough to read T.

core/engine/src/vm/opcode/mod.rs

@@ -1,5 +1,18 @@
 #![allow(clippy::inline_always)]
 #![allow(clippy::doc_markdown)]
+//! Boa's VM opcode definitions and bytecode dispatch.
+//!
+//! The bytecompiler lowers ECMAScript runtime semantics into these opcode families, which are then
+//! executed by the virtual machine. Most opcode submodules mirror a part of the specification,
+//! such as function calls, environment records, iteration, property access, or class evaluation.
+//! See the general runtime semantics overview in the [specification][spec].
+//!
+//! When the specification marks an abstract operation as infallible with `!`, Boa treats the
+//! corresponding condition as an internal bytecode invariant. In those cases, malformed
+//! bytecode is treated as an engine bug and may trip an assertion instead of returning a
+//! recoverable JavaScript exception.
+//!
+//! [spec]: https://tc39.es/ecma262/#sec-runtime-semantics-evaluation
 use crate::{
     Context,
     vm::{completion_record::CompletionRecord, completion_record::IntoCompletionRecord},