v8-understanding

# V8 Understanding Strategy Use this skill to explore V8 concepts, components, or optimization logic deeply. This focuses on the *methodology* of understanding, assuming orchestration is handled globally by the framework. ## Core Methodology: Hypothesis Testing To understand complex V8 behavior, follow a scientific approach: 1. **Formulate Hypotheses**: Based on initial reading or symptoms, hypothesize how a feature works or why a bug occurs. 2. **Design Experiments**: Create small, isolated JavaScript repros or use specific `d8` flags to test the hypothesis. 3. **Analyze Results**: Use tools like GDB, Turbolizer, or profile logs to verify if the behavior matches the hypothesis. 4. **Iterate**: Refine the hypothesis based on data. ## Key Areas of Understanding 1. **Performance**: - Understand execution tiers (Ignition, Maglev, TurboFan). - Trace how optimizations are applied and why deoptimizations happen. 2. **Memory**: - Understand object layout (Hidden Classes/Maps). - Trace garbage collection behavior and allocation patterns. 3. **Architecture & Detailed Interaction**: - Focus on the detailed interaction between components (e.g., how the Parser feeds the AST, which feeds Ignition). - Understand how optimizations interact with core features. Avoid treating components in isolation. ## Documentation Resources - **Local Documentation**: Refer to the `docs/` directory in the V8 root for documentation. It contains content from `v8.dev`, so there is no need to access the external website or use browser tools. Use local search and file reading to access it. - **High-Level & Cross-Cutting Concepts**: Many important design principles, API designs, and cross-cutting features (e.g., sandboxing, embedding, debugging, profiling, security) are documented in files directly at the root of the `docs/` directory (e.g., `docs/embed.md`, `docs/gdb.md`, `docs/untrusted-code-mitigations.md`). Always scan the root `docs/` folder. - **Subsystem Docs**: When investigating a specific subsystem, check if there is a corresponding subdirectory in `docs/` (e.g., `docs/compiler/`, `docs/heap/`). Do not assume a strict 1:1 directory mapping between `src/` and `docs/`. - **Global Docs Search**: As a first step, always run a local search (e.g. `grep` or find tools) across the entire `docs/` directory to find all files mentioning the key classes, APIs, or optimization concepts you are investigating (e.g. search for `BytecodeGenerator` in all `.md` files). ## Workflow 1. **Static Research**: - Identify the main concepts, subsystems, and classes being investigated. - **Search globally** in the `docs/` directory for these concepts/classes to locate relevant design files, whether they live at the root of `docs/` or in a subsystem subfolder. - Read the discovered documentation files to build a high-level mental model *before* reading complex C++ code. - Read code in `src/` to fill in details. 2. **Dynamic Verification**: Use small tests and tracing flags to confirm the model. 3. **Red/Blue Team Analysis**: Have one agent/subagent propose an explanation (Blue) and another try to find counter-examples or flaws in it (Red).