add include/AGENTS.md

AGENTS.md

@@ -11,6 +11,7 @@ otherwise have to enforce by hand -- read it before submitting any change.
 Then read the directory guide for the area you are editing:
 
 - [src/AGENTS.md](src/AGENTS.md) -- compiler C++ sources: AST, visitors, passes, parser, style
+- [include/AGENTS.md](include/AGENTS.md) -- runtime library (`verilated*`): C++14, MT-safety, fixed-width types
 - [test_regress/AGENTS.md](test_regress/AGENTS.md) -- regression tests: harness, drivers, golden files
 - [docs/AGENTS.md](docs/AGENTS.md) -- documentation (`*.rst`)
 

include/AGENTS.md

@@ -0,0 +1,60 @@
+<!-- DESCRIPTION: Verilator: include/ guidelines for AI coding agents
+     SPDX-FileCopyrightText: 2026-2026 Wilson Snyder
+     SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -->
+
+# include/ -- Verilator runtime library
+
+Covers the C++ runtime under `include/` (`verilated.h/.cpp`, `verilated_*.h/.cpp`)
+that every generated model links against. Read the repository-root
+[AGENTS.md](../AGENTS.md) first. The rules here differ from `src/`: this code
+ships to users, runs every simulation cycle, and must stay portable and fast.
+
+---
+
+# Orientation
+
+- **This is the runtime, not the compiler.** The passes in `src/` *emit* C++ that
+  calls into this library; this code then *runs* during simulation. Optimize it
+  for execution speed and portability, not for compile-time clarity.
+- **Key files:** `verilated.h` (core model API), `verilated_types.h` (data
+  types), `verilated_random.cpp` (constrained-random runtime), `verilated_cov.*`
+  (coverage), `verilated_threads.*` (MT runtime), `verilated_timing.*`
+  (`--timing` runtime), `verilated_vcd_c.*`/`verilated_fst_c.*` (tracing).
+- A runtime-only fix lives entirely here and does not rebuild `verilator_bin`.
+
+---
+
+# Before you open a PR
+
+- **C++14 baseline.** The runtime must build under `--no-timing` with C++14; C++20
+  features are allowed only in `--timing` code paths.
+- **Public API naming and docs.** Prefix public classes and types with
+  `Verilated`/`Vl` to avoid collisions with user code, and document the API with
+  `///` comments -- they feed doc generation.
+- **No exceptions in runtime code** -- use error returns or assertions; exceptions
+  add overhead on every path.
+- **Use fixed-width model types** (`CData`/`SData`/`IData`/`QData`/`VlWide`), never
+  `size_t`, for model data. Process wide data word-by-word (`VL_MEMSET_W`,
+  `VL_MEMCPY_W`), never bit-by-bit or byte-by-byte.
+- **Do all string parsing at verilation time** -- never parse strings during
+  simulation; emit structured data or compile-time hints instead.
+- **Keep per-cycle code lean.** Do not add vtables to high-frequency objects
+  (8 bytes per instance); guard optional features behind
+  `hasClasses()`/`hasEvents()`-style checks; functions called per cycle must avoid
+  mutexes -- use atomics or lockless designs.
+- **Emit no runtime loops** the compiler could have expanded at verilation time;
+  prefer a single runtime call.
+- **Thread safety.** Annotate with the hierarchy `VL_PURE` > `VL_MT_SAFE` >
+  `VL_MT_STABLE`; annotations must match the implementation. Annotate
+  mutex-protected members with `VL_GUARDED_BY` and document acquisition ordering.
+  Prefer has-a over is-a: a guarded class wrapping the unguarded internal one, with
+  the guarded version as the default public API.
+- **Keep runtime and compiler headers separate** -- never include `verilated.h`
+  into the compiler in `src/`.
+
+## File-specific rules
+
+| File | Rule |
+|---|---|
+| `verilated_random.cpp` | Emit only portable SMT-LIB 2.6 -- no solver-specific or MaxSMT extensions; the generated solver text is the model's runtime constraint interface |
+| `verilated_cov.cpp` | Coverage runtime is shared by all models -- keep per-point overhead minimal and the on-disk format stable for `verilator_coverage` |