Add vm-counters feature: per-run instruction, allocation, and RC counts

A cargo feature on the VM (off by default, passed through by the compiler) counts
dispatched instructions, heap allocations, and incref/decref per run and prints
them on exit. The increments are cfg-gated no-op methods, so the normal build is
unchanged and pays nothing. The counts are deterministic, so they read from the
feature build while wall-clock reads from the plain build, and the counter cost
never contaminates a timing.

First finding, the hello-world HTTP request (two-point measurement, per request):
about 3,865 instructions, 94 allocations, and 274 reference-count operations. The
allocation and RC traffic, not raw dispatch, is the larger interpreter lever and
the concrete target for reference-count elision. Recorded in PROFILING.md.

Author: Axmouth

plans/PROFILING.md

@@ -18,9 +18,14 @@ Three tools, since heavyweight profilers are often unavailable in a sandbox:
 - **`strace -f -c`** on the server gives the syscall histogram, which is where the connection-lifecycle
   cost shows up. It roughly triples the runtime, so read the counts and the distribution, not the
   absolute times.
-- **VM instrumentation counters** (planned, not yet built): dispatched instructions, allocations, and
-  incref/decref per request. These are deterministic, so they double as a regression gate, and they
-  are what sizes the interpreter-internal levers (RC elision, fusion) that strace cannot see.
+- **VM instrumentation counters** (built, behind the `vm-counters` cargo feature, off by default):
+  dispatched instructions, heap allocations, and incref/decref per run, printed to stderr on exit.
+  The increments compile out of the normal build, so it pays nothing by default. Build with
+  `cargo build --release -p solid-snake-compiler --features vm-counters`, run a bounded program, and
+  divide the totals by the request count. The counts are deterministic, so they double as a
+  regression gate, and they size the interpreter-internal levers (RC elision, fusion) that strace
+  cannot see. Read counts from this build and wall-clock from the plain build, so the counters' own
+  cost never contaminates a timing.
 
 Two server shapes bracket the cost. The full `std.http` library server measures the realistic path
 (request parsing included). A raw server (`srv_perreq.ss`, `srv_ka.ss`) that reads a request and
@@ -54,16 +59,31 @@ requests). Reference counting reclaims each request's allocations immediately, s
 bounded with no per-request growth. This is lean, well under a typical Node idle footprint and in
 Go's range.
 
+Interpreter internals per request, from the `vm-counters` build (two-point measurement subtracting a
+1000-request run from a 4000-request run, so fixed setup cancels, and the counts are perfectly
+linear):
+
+- dispatched instructions: about 3,865
+- heap allocations: about 94
+- incref: about 102, decref: about 172, so about 274 reference-count operations
+
+That is a large amount of allocation and reference-count traffic for a fixed-response hello-world.
+Most of it is request-parsing temporaries that are uniquely owned and short-lived, which is exactly
+what reference-count elision targets. So of the roughly 24 us of interpreter parsing, a large share
+is the allocation and reference-count work these counts expose, not raw dispatch.
+
 ## The levers, sized
 
 - **Keep-alive is the syscall lever.** It removes a hard 27 us per request. On the raw path that is a
   3.3x jump (25k to 83k). On the full library the ratio is smaller, because once the connection
   syscalls are gone the parse cost dominates, so the estimate is roughly 15.8k to 28k. The server is
   `Connection: close` today (`std.http` defers keep-alive deliberately), so this is unbuilt.
-- **The interpreter is the next lever.** The roughly 24 us of parsing is where RC elision (skip the
-  retain and release where a value is provably uniquely owned and does not escape, which is most
-  temporaries) and instruction fusion (cut dispatch and register traffic on hot runs) pay off. The
-  VM counters will break this down into how much is RC traffic versus raw dispatch.
+- **The interpreter is the next lever, and it is allocation and reference counting more than raw
+  dispatch.** The counters show about 94 allocations and about 274 reference-count operations per
+  request. RC elision (skip the retain and release where a value is provably uniquely owned and does
+  not escape, which is most temporaries) removes RC operations and the allocations tied to them, and
+  instruction fusion cuts dispatch on the roughly 3,865 instructions. The allocation and RC traffic
+  is the larger, more concrete target of the two.
 
 ## Where this sits
 

solid-snake-compiler/Cargo.toml

@@ -3,6 +3,11 @@ name = "solid-snake-compiler"
 version = "0.1.0"
 edition = "2024"
 
+[features]
+# Pass through the VM's per-run profiling counters, so `--features vm-counters` on the CLI enables
+# them end to end. Off by default. See plans/PROFILING.md.
+vm-counters = ["solid-snake-vm/vm-counters"]
+
 [dependencies]
 solid-snake-vm = { path = "../solid-snake-vm" }
 ariadne = "0.5.1"

solid-snake-vm/Cargo.toml

@@ -3,6 +3,12 @@ name = "solid-snake-vm"
 version = "0.1.0"
 edition = "2024"
 
+[features]
+# Count dispatched instructions, heap allocations, and incref/decref per run, printed on exit. Off
+# by default so the increments compile out entirely and the normal build pays nothing. See
+# plans/PROFILING.md. Build with `--features vm-counters` to read the per-run tallies.
+vm-counters = []
+
 [dependencies]
 solid-snake-vm-macros = { path = "../solid-snake-vm-macros" }
 env_logger = "0.11.8"

solid-snake-vm/src/executor/interpreted/implimentation.rs

@@ -136,13 +136,20 @@ pub trait VmHeapExt {
 pub struct VmHeap {
     memory_sections: Vec<VmMemorySection>,
     freed_sections: Vec<usize>,
+    /// Total allocations over the run, only under `vm-counters`. Unlike `section_count`, this counts
+    /// every `alloc` including those that reuse a freed slot, so it measures allocation traffic (what
+    /// reference-count elision would reduce), not live sections.
+    #[cfg(feature = "vm-counters")]
+    alloc_count: u64,
 }
 
 impl VmHeap {
     pub fn new() -> Self {
         Self {
             freed_sections: Vec::new(),
             memory_sections: Vec::new(),
+            #[cfg(feature = "vm-counters")]
+            alloc_count: 0,
         }
     }
 
@@ -151,10 +158,20 @@ impl VmHeap {
     pub fn section_count(&self) -> usize {
         self.memory_sections.len()
     }
+
+    /// Total allocations over the run (only meaningful under `vm-counters`).
+    #[cfg(feature = "vm-counters")]
+    pub fn alloc_count(&self) -> u64 {
+        self.alloc_count
+    }
 }
 
 impl VmHeapExt for VmHeap {
     fn alloc(&mut self, n: usize) -> Result<usize, VmExecutionError> {
+        #[cfg(feature = "vm-counters")]
+        {
+            self.alloc_count += 1;
+        }
         let memory_block: Vec<u8> = vec![0; n];
         let new_section = VmMemorySection::new_with_bytes(memory_block);
         if let Some(idx) = self.freed_sections.pop() {
@@ -464,6 +481,18 @@ impl InputSource {
     }
 }
 
+/// Per-run profiling counters, populated only under the `vm-counters` feature. The counts are
+/// deterministic (a program does the same work every run), so they measure the interpreter workload
+/// shape without depending on wall-clock, and the increments compile out of the normal build. See
+/// plans/PROFILING.md.
+#[cfg(feature = "vm-counters")]
+#[derive(Default, Debug, Clone, Copy)]
+pub struct PerfCounters {
+    pub instructions: u64,
+    pub incref: u64,
+    pub decref: u64,
+}
+
 pub struct VmInterpretedExecutor {
     pub frame_stack: Vec<CallFrame>,
     pub stack_top: usize,
@@ -521,6 +550,10 @@ pub struct VmInterpretedExecutor {
     /// add or override handlers through `register_builtin`, so the VM core does not hardcode which
     /// builtins exist. See `plans/BUILTIN_REGISTRY.md`.
     builtins: BuiltinRegistry,
+    /// Per-run profiling counters, only under the `vm-counters` feature so the increments compile
+    /// out of the normal build.
+    #[cfg(feature = "vm-counters")]
+    perf: PerfCounters,
 }
 
 impl VmInterpretedExecutor {
@@ -552,9 +585,50 @@ impl VmInterpretedExecutor {
             handles: HandleTable::default(),
             program: Vec::new(),
             builtins: BuiltinRegistry::with_defaults(),
+            #[cfg(feature = "vm-counters")]
+            perf: PerfCounters::default(),
         }
     }
 
+    // The counter methods are no-ops without `vm-counters`, so call sites stay unconditional.
+    #[cfg(feature = "vm-counters")]
+    #[inline(always)]
+    pub fn perf_instr(&mut self) {
+        self.perf.instructions += 1;
+    }
+    #[cfg(not(feature = "vm-counters"))]
+    #[inline(always)]
+    pub fn perf_instr(&mut self) {}
+
+    #[cfg(feature = "vm-counters")]
+    #[inline(always)]
+    pub fn perf_incref(&mut self) {
+        self.perf.incref += 1;
+    }
+    #[cfg(not(feature = "vm-counters"))]
+    #[inline(always)]
+    pub fn perf_incref(&mut self) {}
+
+    #[cfg(feature = "vm-counters")]
+    #[inline(always)]
+    pub fn perf_decref(&mut self) {
+        self.perf.decref += 1;
+    }
+    #[cfg(not(feature = "vm-counters"))]
+    #[inline(always)]
+    pub fn perf_decref(&mut self) {}
+
+    #[cfg(feature = "vm-counters")]
+    pub fn perf_report(&self) -> String {
+        format!(
+            "vm-counters: instructions={} allocations={} incref={} decref={}",
+            self.perf.instructions,
+            self.heap.alloc_count(),
+            self.perf.incref,
+            self.perf.decref,
+        )
+    }
+
     /// The builtin handler at an index, if one is installed. Read out before dispatch so the call
     /// holds no borrow into the executor it mutates (handlers are `Copy` function pointers).
     #[inline(always)]
@@ -959,11 +1033,14 @@ impl VmExecutorExt for VmInterpretedExecutor {
             let decoded = self.program[self.program_counter];
 
             if let DecodedInstruction::Halt((exit_code,)) = decoded {
+                #[cfg(feature = "vm-counters")]
+                eprintln!("{}", self.perf_report());
                 return Ok(exit_code);
             }
             self.prev_error_code = self.error_code;
             self.error_code = 0; // TODO: examine if any instruction will need it kept set between multiple instructions.
             self.program_counter += 1;
+            self.perf_instr();
             decoded.exec(self)?;
         }
     }

solid-snake-vm/src/executor/interpreted/opcode_impl/memory.rs

@@ -245,6 +245,7 @@ pub fn incref_handler(
     args: IncRefArgs,
 ) -> Result<(), VmExecutionError> {
     let (reg_target,) = args;
+    executor.perf_incref();
     let section_idx: u64 = executor.registers().get_value(reg_target)?;
     adjust_refcount(executor, section_idx as usize, 1)?;
     Ok(())
@@ -255,6 +256,7 @@ pub fn decref_handler(
     args: DecRefArgs,
 ) -> Result<(), VmExecutionError> {
     let (reg_target,) = args;
+    executor.perf_decref();
     let root: u64 = executor.registers().get_value(reg_target)?;
     release_cascade(executor, root as usize)
 }

tools/profiling/README.md

@@ -41,3 +41,17 @@ grep -E 'VmRSS|VmHWM' /proc/<pid>/status    # resident and peak memory
 
 The `srv_ka.ss` and `srv_perreq.ss` servers serve a bounded number of connections and then exit, so
 the accept count in each file must be at least the number of client connections used.
+
+## Interpreter counters
+
+Build with the `vm-counters` feature to print dispatched instructions, heap allocations, and
+incref/decref on exit, then divide by the request count (or subtract two run sizes to cancel fixed
+setup). Off by default, so the normal build pays nothing.
+
+```
+cargo build --release -p solid-snake-compiler --features vm-counters
+./target/release/solid-snake-compiler tools/profiling/hello_server.ss &   # serves a bounded count
+python3 tools/profiling/load.py 3000 8
+# the server prints: vm-counters: instructions=... allocations=... incref=... decref=...
+```
+