runtime: build-time init snapshot census (instr-only): Supabase check differ=0, D 1,643 (93.9%), production bytes = main

changelog.d/snap-startup-census.md

@@ -0,0 +1 @@
+Instrumented builds gain the startup-snapshot census (`PERRY_SNAP_CENSUS=<out>` on a binary compiled against the instr runtime): it reports which module inits a startup image could hold, with env cells, one environment guard, the entry body, key-granular globalThis locations and a check run. It is off by default and absent from production builds, whose code and startup cost are unchanged.

crates/perry-codegen/src/codegen/entry.rs

@@ -192,6 +192,16 @@ pub(super) fn compile_module_entry(
             llmod.declare_function(&format!("{}__init", prefix), VOID, &[]);
             llmod.declare_function(&format!("__perry_prepare_literals_{}", prefix), VOID, &[]);
         }
+        if std::env::var_os("PERRY_SNAP_CENSUS").is_some_and(|v| !v.is_empty()) {
+            llmod.declare_function("js_snap_entry_body", VOID, &[]);
+            llmod.declare_function("js_snap_tls_program", VOID, &[PTR, PTR, PTR, PTR]);
+            for anchor in crate::stubs::SNAP_TLS_ANCHORS {
+                llmod.add_external_tls_global(anchor, "i8", "localexec");
+            }
+            if entry_in_init {
+                llmod.declare_function("js_snap_entry_module", VOID, &[]);
+            }
+        }
         // Issue #753: emit a no-op `<entry_prefix>__init` stub so the
         // dispatch site in some other module that does `await
         // import("./entry.ts")` resolves at link time. The entry
@@ -468,6 +478,16 @@ pub(super) fn compile_module_entry(
         let _ = main.create_block("entry");
         {
             let blk = main.block_mut(0).unwrap();
+            // SNAP census: the program's TLS slots lie between the anchors the
+            // driver links before and after the program objects; the runner
+            // protects those pages only (never runtime thread-locals).
+            if std::env::var_os("PERRY_SNAP_CENSUS").is_some_and(|v| !v.is_empty()) {
+                let a = crate::stubs::SNAP_TLS_ANCHORS.map(|n| format!("@{n}"));
+                blk.call_void(
+                    "js_snap_tls_program",
+                    &[(PTR, &a[0]), (PTR, &a[1]), (PTR, &a[2]), (PTR, &a[3])],
+                );
+            }
             if let Some((const_name, byte_len)) = process_entry_path.as_ref() {
                 let path_ptr = format!("@{}", const_name);
                 let len_str = byte_len.to_string();
@@ -713,6 +733,11 @@ pub(super) fn compile_module_entry(
                 }
                 blk.call_void(&format!("{}__init", prefix), &[]);
             }
+            // SNAP census (`PERRY_SNAP_CENSUS` set while compiling, with
+            // `PERRY_GC_INSTRUMENTS=1`): the entry's own body starts here.
+            if std::env::var_os("PERRY_SNAP_CENSUS").is_some_and(|v| !v.is_empty()) {
+                blk.call_void("js_snap_entry_body", &[]);
+            }
         }
         // Mark the boundary between init prelude and user code so
         // hoisted post-init setup (cached `@perry_class_keys_*` loads
@@ -1131,6 +1156,10 @@ pub(super) fn compile_module_entry(
             buffer_alias_scopes,
         };
         if entry_in_init {
+            // SNAP census: the entry module's evaluation is the entry body.
+            if std::env::var_os("PERRY_SNAP_CENSUS").is_some_and(|v| !v.is_empty()) {
+                ctx.block().call_void("js_snap_entry_module", &[]);
+            }
             ctx.block()
                 .call_void(&format!("{}__init", module_prefix), &[]);
         } else {

crates/perry-codegen/src/expr/array_methods.rs

@@ -436,7 +436,10 @@ pub(crate) fn lower(ctx: &mut FnCtx<'_>, expr: &Expr) -> Result<String> {
             // js_getenv_value returns `undefined` (nullish) for an unset
             // var, not a STRING_TAG'd null pointer — so `?? default`
             // applies and typeof/JSON.stringify agree (#1312).
-            Ok(blk.call(DOUBLE, "js_getenv_value", &[(I64, &key_handle)]))
+            super::snap_env_site::emit(ctx, expr);
+            Ok(ctx
+                .block()
+                .call(DOUBLE, "js_getenv_value", &[(I64, &key_handle)]))
         }
         Expr::EnvGetDynamic(name_expr) => {
             let key_box = lower_expr(ctx, name_expr)?;
@@ -445,8 +448,11 @@ pub(crate) fn lower(ctx: &mut FnCtx<'_>, expr: &Expr) -> Result<String> {
             // `process.env[shortName]`); `js_getenv` dereferences it as
             // `*StringHeader`. #214 SSO bug class.
             let key_handle = unbox_str_handle(blk, &key_box);
+            super::snap_env_site::emit(ctx, expr);
             // `undefined` for unset vars — see EnvGet above (#1312).
-            Ok(blk.call(DOUBLE, "js_getenv_value", &[(I64, &key_handle)]))
+            Ok(ctx
+                .block()
+                .call(DOUBLE, "js_getenv_value", &[(I64, &key_handle)]))
         }
         Expr::ProcessEnv => {
             // `process.env` (or `globalThis.process.env`) as a value.

crates/perry-codegen/src/expr/dispatch.rs

@@ -50,6 +50,9 @@ fn lower_expr_inner(ctx: &mut FnCtx<'_>, expr: &Expr) -> Result<String> {
     // one. Handlers that care receive it as an argument, because they consult
     // it after lowering their operands — by which point the field is gone.
     let value_discarded = std::mem::take(&mut ctx.discard_this_expr);
+    // SNAP census (instrumented compiles only): an env read whose value this
+    // expression stores is a store site (`expr/snap_env_site.rs`).
+    super::snap_env_site::note_store_parent(ctx, expr);
     // #9856: under `--debug-symbols`, record this expression's source line
     // for the DWARF line table (`crate::debug_info`). No-op otherwise.
     crate::debug_info::mark_expr_location(ctx, expr);

crates/perry-codegen/src/expr/mod.rs

@@ -105,6 +105,7 @@ pub(crate) mod hot_tls;
 pub(crate) mod inline_birth;
 pub(crate) mod literal_chunks;
 mod literal_descriptor;
+pub(crate) mod snap_env_site;
 /// A worker program's literal-descriptor IR, for the dialect reader's round trip.
 #[cfg(test)]
 pub(crate) fn literal_descriptor_worker_ir() -> String {

crates/perry-codegen/src/expr/snap_env_site.rs

@@ -0,0 +1,105 @@
+//! SNAP census: the consumer kind of a `process.env` read site
+//! (`secret-tests/nightly/CW/SNAP_DESIGN_2026-10-30.md` §2.10.5), emitted in
+//! instrumented compiles only (`PERRY_SNAP_CENSUS` set while compiling, the
+//! switch `js_snap_entry_body` uses). An ordinary compile emits nothing.
+//!
+//! A read is a *store* site when its value is directly the stored value of a
+//! module-global binding (`let`/`const` lowered to a module global, an
+//! assignment to one, `GlobalSet`), a property or index set, or an element of
+//! an array or object literal. Every other read is an *observe* site. Codegen
+//! calls `js_snap_env_site(kind)` right before the read's runtime call; the
+//! runtime keeps the kind for that frame's next `js_getenv`. No table is
+//! emitted: the kind is the call's argument.
+
+use std::cell::RefCell;
+
+use perry_hir::Expr;
+
+use crate::types::I32;
+
+use super::FnCtx;
+
+/// `js_snap_env_site` kinds (the runtime reads the same numbers).
+const OBSERVE: i32 = 0;
+const STORE: i32 = 1;
+
+thread_local! {
+    /// Env-read expressions (by address) whose parent stores their value,
+    /// noted when the parent is lowered and taken when the read is.
+    static STORE_SITES: RefCell<Vec<usize>> = const { RefCell::new(Vec::new()) };
+}
+
+pub(crate) fn census_compile() -> bool {
+    std::env::var_os("PERRY_SNAP_CENSUS").is_some_and(|v| !v.is_empty())
+}
+
+fn is_env_read(e: &Expr) -> bool {
+    matches!(e, Expr::EnvGet(_) | Expr::EnvGetDynamic(_))
+}
+
+fn note<'e>(children: impl Iterator<Item = &'e Expr> + Clone) {
+    if children.clone().any(is_env_read) && census_compile() {
+        STORE_SITES.with(|s| {
+            let mut s = s.borrow_mut();
+            for c in children.filter(|c| is_env_read(c)) {
+                s.push(c as *const Expr as usize);
+            }
+        });
+    }
+}
+
+/// `expr` is about to be lowered: when it stores the value of a direct
+/// env-read child, that child is a store site.
+pub(crate) fn note_store_parent(ctx: &FnCtx<'_>, expr: &Expr) {
+    match expr {
+        Expr::GlobalSet(_, v) => note(std::iter::once(&**v)),
+        Expr::LocalSet(id, v) if ctx.module_globals.contains_key(id) => note(std::iter::once(&**v)),
+        Expr::PropertySet { value, .. } | Expr::IndexSet { value, .. } => {
+            note(std::iter::once(&**value))
+        }
+        Expr::Object(fields) => note(fields.iter().map(|(_, v)| v)),
+        // A plain object literal lowers to `new __AnonShape_*(values...)`:
+        // the literal shape has no constructor, its values are its fields.
+        Expr::New {
+            class_name, args, ..
+        } if ctx
+            .classes
+            .get(class_name)
+            .is_some_and(|c| c.is_literal_shape()) =>
+        {
+            note(args.iter())
+        }
+        Expr::Array(elems, _) => note(elems.iter()),
+        _ => {}
+    }
+}
+
+/// A `let`/`const` binding `id` with initializer `init` is being lowered.
+pub(crate) fn note_let(ctx: &FnCtx<'_>, id: u32, init: Option<&Expr>) {
+    if let Some(init) = init {
+        if ctx.module_globals.contains_key(&id) {
+            note(std::iter::once(init));
+        }
+    }
+}
+
+/// Emit the site hook for the env read `expr`, right before its runtime call.
+pub(crate) fn emit(ctx: &mut FnCtx<'_>, expr: &Expr) {
+    if !census_compile() {
+        return;
+    }
+    let addr = expr as *const Expr as usize;
+    let store = STORE_SITES.with(|s| {
+        let mut s = s.borrow_mut();
+        match s.iter().position(|&a| a == addr) {
+            Some(i) => {
+                s.swap_remove(i);
+                true
+            }
+            None => false,
+        }
+    });
+    let kind = if store { STORE } else { OBSERVE };
+    ctx.block()
+        .call_void("js_snap_env_site", &[(I32, &kind.to_string())]);
+}

crates/perry-codegen/src/lower_call/native/native_runtime_branch.rs

@@ -374,7 +374,16 @@ return crate::lower_array_record_length::lower(ctx, &args[0]);
                 let init_fn = format!("{prefix}__init");
                 ctx.pending_declares
                     .push((init_fn.clone(), crate::types::VOID, vec![]));
+                // SNAP census: the evaluation this guard starts was reached
+                // by `require`, not by `import()` (instrumented compiles only).
+                let census = crate::expr::snap_env_site::census_compile();
+                if census {
+                    ctx.block().call_void("js_snap_require_edge", &[(crate::types::I32, "1")]);
+                }
                 ctx.block().call_void(&init_fn, &[]);
+                if census {
+                    ctx.block().call_void("js_snap_require_edge", &[(crate::types::I32, "0")]);
+                }
                 return lower_expr(ctx, &args[0]);
             }
             "isBuiltin" => {

crates/perry-codegen/src/runtime_decls/strings.rs

@@ -944,6 +944,11 @@ pub fn declare_phase_b_strings(module: &mut LlModule) {
     );
     module.declare_function("js_getenv", I64, &[I64]);
     module.declare_function("js_getenv_value", DOUBLE, &[I64]);
+    // SNAP census site hook (`expr/snap_env_site.rs`): instrumented compiles only.
+    if crate::expr::snap_env_site::census_compile() {
+        module.declare_function("js_snap_env_site", VOID, &[I32]);
+        module.declare_function("js_snap_require_edge", VOID, &[I32]);
+    }
     // #1344: process.env.X = v / delete process.env.X.
     module.declare_function("js_setenv", VOID, &[I64, DOUBLE]);
     module.declare_function("js_removeenv", VOID, &[I64]);

crates/perry-codegen/src/stmt/mod.rs

@@ -632,6 +632,7 @@ fn lower_stmt_inner(ctx: &mut FnCtx<'_>, stmt: &Stmt) -> Result<()> {
             {
                 ctx.typed_element_locals.insert(*id);
             }
+            crate::expr::snap_env_site::note_let(ctx, *id, init.as_ref());
             lower_let(ctx, *id, name, init.as_ref(), ty, *mutable)?;
             // Object model step 1: a family prototype's birth.
             crate::layout_desc::create_families::lower_binding(ctx, *id)?;

crates/perry-codegen/src/stubs.rs

@@ -256,6 +256,38 @@ pub fn generate_feature_installer_object(
     compile_ll_to_object(&ll, triple.as_deref())
 }
 
+/// SNAP census TLS anchors (census compiles only, `PERRY_SNAP_CENSUS`): data
+/// begin, data end, bss begin, bss end. The driver links the begin object
+/// first and the end object after every other compiled object, so the
+/// linker, which lays `.tdata` and `.tbss` input sections out in command-line
+/// order, puts the program's TLS slots between them and the runtime archive's
+/// thread-locals after them. Each anchor is page-aligned, so the program's
+/// slots fill whole pages that hold nothing else.
+pub const SNAP_TLS_ANCHORS: [&str; 4] = [
+    "__perry_snap_tls_data_begin",
+    "__perry_snap_tls_data_end",
+    "__perry_snap_tls_bss_begin",
+    "__perry_snap_tls_bss_end",
+];
+
+/// The object holding the begin (`end == false`) or end anchors of
+/// [`SNAP_TLS_ANCHORS`]: one page-aligned byte in `.tdata` (initialized) and
+/// one in `.tbss` (zero).
+pub fn generate_snap_tls_anchor_object(end: bool, target: Option<&str>) -> Result<Vec<u8>> {
+    let (data, bss) = if end {
+        (SNAP_TLS_ANCHORS[1], SNAP_TLS_ANCHORS[3])
+    } else {
+        (SNAP_TLS_ANCHORS[0], SNAP_TLS_ANCHORS[2])
+    };
+    let ll = format!(
+        "; Perry SNAP census TLS anchors, generated by perry-codegen::stubs\n\n\
+         @{data} = thread_local global i8 1, align 4096\n\
+         @{bss} = thread_local global i8 0, align 4096\n"
+    );
+    let triple = target.and_then(crate::resolve_target_triple);
+    compile_ll_to_object(&ll, triple.as_deref())
+}
+
 /// The LLVM IR of the program's static shape seed unit (design step 4, WRT
 /// step 2): the program's literal seeds as data. For each seed: its layout
 /// request, its packed key names, and, on targets whose atoms are image

crates/perry-runtime/src/arena/allocators.rs

@@ -701,6 +701,7 @@ fn arena_alloc_gc_slow(size: usize, align: usize, obj_type: u8, total: usize) ->
     };
 
     if let Some(user_ptr) = reused {
+        crate::snap_census::birth_user(user_ptr as usize, total);
         ARENA.with(|a| unsafe { (&mut *a.get()).note_allocation(total, total >= 16 * 1024) });
         // Reusing a free-list slot: the GcHeader is already in place (before user_ptr)
         // Just update it

crates/perry-runtime/src/arena/block.rs

@@ -578,6 +578,7 @@ impl ArenaBlock {
         let ptr = unsafe { self.data.add(aligned_offset) };
         let next = bumped.checked_add(pad - 1)? & !(pad - 1);
         self.offset = next;
+        crate::snap_census::birth(ptr, size);
         Some(ptr)
     }
 
@@ -1306,7 +1307,6 @@ thread_local! {
     /// `arena_reset_empty_blocks`).
     pub(crate) static ARENA_TOTAL_BYTES: crate::gc::TriggerInput<usize> = const { crate::gc::TriggerInput::new(0) };
 }
-
 crate::perry_thread_local! {
     /// Cached running sum of `block.offset` across the old-gen arena —
     /// the delta-maintained twin of `ARENA_TOTAL_BYTES` above, same

crates/perry-runtime/src/arena/inline.rs

@@ -250,7 +250,7 @@ pub fn arena_start_fresh_general_block() {
 /// extent and the existing coloring/seeding path.
 #[inline(always)]
 pub(crate) fn allocation_limit(offset: usize, block_size: usize) -> usize {
-    if crate::gc::gc_birth_extra_flags() != 0 {
+    if crate::gc::gc_birth_extra_flags() != 0 || crate::snap_census::inline_bump_closed() {
         0
     } else {
         super::alloc_sample::inline_limit(offset, block_size)

crates/perry-runtime/src/arena/mod.rs

@@ -231,3 +231,7 @@ pub(crate) use region::new_test_block_backing;
 pub(crate) use region::release_test_block_backing;
 
 pub(crate) use inline::refresh_inline_allocation_limit;
+#[cfg(all(perry_gc_instruments, target_os = "linux", target_arch = "x86_64"))]
+pub(crate) use region::reservation::{
+    for_each_mapped as snap_reservation_regions, payload_bounds as snap_reservation_bounds,
+};

crates/perry-runtime/src/arena/region/reservation.rs

@@ -434,10 +434,37 @@ pub(super) unsafe fn map(kind: Kind, mapped: usize) -> *mut u8 {
             d.publication
                 .store(serial() | kind_bits(kind) | MAPPED, SeqCst);
         }
+        crate::snap_census::region_mapped(base, mapped);
         return data.cast();
     }
     std::ptr::null_mut()
 }
+/// `[base, base + len)` of the reservation's payload (empty before it
+/// exists). The SNAP census sizes its page map with it.
+#[cfg(all(perry_gc_instruments, target_os = "linux", target_arch = "x86_64"))]
+pub(crate) fn payload_bounds() -> (usize, usize) {
+    initialized().map_or((0, 0), |r| (r.base, r.base + r.len))
+}
+
+/// Every mapped region, `[base, end)`, once each.
+#[cfg(all(perry_gc_instruments, target_os = "linux", target_arch = "x86_64"))]
+pub(crate) fn for_each_mapped(mut f: impl FnMut(usize, usize)) {
+    let Some(r) = existing() else {
+        return;
+    };
+    let mut slot = 0;
+    while slot < r.len / ALIGN {
+        let d = r.descriptor(slot);
+        if d.publication.load(SeqCst) & MAPPED != 0 {
+            let (base, end) = (d.base.load(SeqCst), d.end.load(SeqCst));
+            f(base, end);
+            slot = (end - r.base).div_ceil(ALIGN).max(slot + 1);
+        } else {
+            slot += 1;
+        }
+    }
+}
+
 pub(super) unsafe fn unmap(data: *mut u8, mapped: usize) {
     let r = existing().expect("region reservation missing");
     let _guard = r.allocation.lock().unwrap_or_else(|e| e.into_inner());