Arhan's Blog

Bring Back the Paragraph

Fri, 07 Aug 2026 17:59:10 GMT

One of the most insidious impacts of LLMs is the online death of the paragraph. You know exactly what I mean.

Here is a bullet point — it is bold for no meaningful reason. The author does not trust me to have the attention span to read what they have to say.
Here is another bullet point — You can’t explain why, but you feel forced to read this sentence. Your attention has been hijacked.

Here is some more text,

expressing only a singular idea,

that is

unnecessarily

separated by line breaks.

Is this not exhausting to read?

I like to call this type of writing “spaghetti writing”. Spaghetti writing is not bad per se: there are benefits to micro-optimizing the communication of certain ideas or varying your sentence structure. However, you see it literally anywhere online. Most forms of writing on the worst social media sites longer than two sentences look like spaghetti writing. But social media was always meant for short-form content, so whatever. That was what you signed up for.

Suddenly, spaghetti writing is becoming more prominent outside of social media—in places on the Internet I didn’t sign up for. I used to be able to call Google search and GitHub safe havens for discovering technical authors who cared deeply about their craft. Now, to have the same opinion would be dishonest. LLMs are not only producing spaghetti writing, but subconciously teaching people spaghetti writing. Websites like Hacker News and Lobste.rs remain mostly high-quality, but the well is drying.

My ask to the reader is straightforward: the next time you want to write something meaningful, consider writing in contiguous paragraphs. Here is a brilliant guide on how to write a paragraph; there is no shame in relearning how to do so. I never understood what it meant to write a paragraph more than “it has a complete thought” and was never taught after grade school. Experiment with pacing your writing and building up to a conclusion.

Always bet on text. Writing is the most powerful and intricate form of human expression; to be a great writer is to be human.

The first step towards a more literate digital culture is to learn how to write a paragraph.

Native Instant Space Switching on MacOS

Mon, 23 Mar 2026 09:27:02 GMT

The worst part about the MacOS window management situation is the inability to instantly switch spaces, and that Apple has continuously ignored requests to disable the nauseating switching animation. Sure, it’s not that long, but I switch spaces often enough to the point where it becomes very noticeable and drives me insane.

I believe to have found the best solution to instant space switching!

But before I show you, of course, other people share the same sentiment. I claim that none of the surveyed contemporary solutions, except for what I bring up at the end of this article, suffice for what I want:

Enable the “Reduce motion” setting in System Settings.

This is always the default answer to this question online, and I’m sick of it! It doesn’t even solve the problem, but rather replaces it with an equally useless fade-in animation. It also has the side effect of activating the prefers-reduced-motion media query on web browsers.
Install the yabai tiling window manager and use its instant space switcher.

And to be fair, it works pretty well. There are only two problems: for one, yabai does this by binary patching a part of the operating system. This is only possible by disabling System Integrity Protection at your own discretion. For the second, installing yabai forces you to learn and use it as your tiling window manager¹. I personally use PaperWM.spoon as my window manager. Both of which are incompatible when installed together.
Use a third-party virtual space manager facade, hiding and showing windows as needed when switching spaces.

Some popular options are FlashSpace and AeroSpace virtual workspaces. I actually offer no criticism other than that they are not native to MacOS, and feel unnecessary given that all we want to do is disable an animation.
Pay for a license for BetterTouchTool. Enable “Move Right Space (Without Animation)” and “Move Left Space (Without Animation)”.

Without further ado, I managed to find InstantSpaceSwitcher by jurplel on GitHub. It is a simple menu bar application that achieves instant space switching while offering none of the aforementioned drawbacks. You can bind a keybind or use swipe gestures to instantly switch spaces.

Here I have InstantSpaceSwitcher paired up with SpaceName.

InstantSpaceSwitcher does not require disabling Security Integration Protection; it works by simulating a trackpad swipe with a large amount of velocity. It additionally allows you to instantly jump to a space number. The last thing it provides is a command line interface.

The installation instructions are listed on the README, and I will briefly repeat them. You can either install InstantSpaceSwiter via Homebrew:

brew install --cask jurplel/tap/instant-space-switcher

Building from source:

git clone https://github.com/jurplel/InstantSpaceSwitcher
cd InstantSpaceSwitcher
./dist/build.sh
open ./build/InstantSpaceSwitcher.app

Or using a pre-built binary.

It is recommended to move InstantSpaceSwitcher.app to /Applications to install it as a native application.

The command line interface is provided at:

$ InstantSpaceSwitcher.app/Contents/MacOS/ISSCli --help
Usage: InstantSpaceSwitcher.app/Contents/MacOS/ISSCli [left|right|index <n>]

Did I mention that the repository literally has one star on GitHub (me)? I want more people to discover InstantSpaceSwitcher and consider it trustworthy; hence, please consider giving it a star if you find it helpful.

Until next time!

Footnotes

I found instantspaces on GitHub, which attempts to isolate yabai’s instant space switcher. Unfortunately, I tried, and I really tried, but I could not get it to work on MacOS Tahoe. Although I anyways prefer InstantSpaceSwitcher, please let me know if you can get this working. ↩

Memory-corrupting Pong

Mon, 17 Nov 2025 18:50:42 GMT

If you’ve kept up with my blog, you might know that my recent “street-cred” has been messing around with “corruption art.” I can’t help it. Stuff like this is always so fascinating to me.

Some context would be in order. Two years ago, I made NAND, a 16-bit computer made entirely from NAND gates emulated on the web. NAND features its own custom CPU architecture, virtual machine, programming language, compiler, and IDE, and it is based on the Jack-VM-Hack platform specified in the Nand to Tetris course. Here’s (single-player) pong!

Your browser does not support the video tag.

Now, I have many wonderful things to talk about with NAND, but we’re not going to be focusing on that. A few weeks ago during the height of my midterms I had a crazy idea: what if we allocated memory on the screen instead of on the heap?

To understand what that means, let’s consider this program written in NAND’s custom programming language.

class Main {
    function void main() {
        var int length;
        var Array a;
        let length = Keyboard.readInt("How much memory? ");
        let a = Array.new(length);
    }
}

The compiler stores the local variables of a function in a memory region called the stack. Everything on the stack must have a size that is known at compile time so the compiler knows how much memory to reserve for it. However, the compiler has no way of knowing how much memory is required to store the array a—it’s a dynamic amount only known at run time. The contemporary solution is to use a memory allocator, something that you can ask for an arbitrary amount of memory and will return a pointer to a chunk of that much memory. The memory allocator looks for memory in a memory region called the heap.

If you run the above program and enter 5, the NAND memory allocator does this to allocate the array:

The NAND memory allocator traverses a linked list of memory blocks and returns the first one with enough memory to satisfy the allocation request. It can undoubtedly be made more efficient. The screen is stored as a bitmap of 512 (length) * 256 (width) = 131072 pixels in its own dedicated memory region. There are no colors; a 0 means black and a 1 means green. To allocate memory on the screen instead of the heap means to tell the memory allocator to treat the screen memory region as the heap memory region.

What makes this so interesting is the fact that NAND has no trap instructions, no hardware interrupts, and no concept of a kernel mode. Universally among modern computers, if you try to read or write memory that belongs to another process or memory region, the operating system will trigger a segmentation fault and terminate your program. But NAND gives every program full reign to modify any part of the computer memory; hence, logically invalid memory operations are shamelessly allowed.

Now to actually do it.

Memory.jack

class Memory {
    static Array ptr;
    static int offset;

    /** Initializes the class. */
    function void init() {
    function void init(int offset_) {
        let ptr = 0;
        let ptr[2048] = 14334;
        let ptr[2049] = 16384;
        let offset = offset_;
        let ptr[offset] = 24574 - offset;
        let ptr[offset + 1] = 24576;
    }

    /** Finds an available RAM block of the given size and returns
     *  a reference to its base address. */
    function int alloc(int size) {
        var Array segment;
        var int length;
        if (size < 0)
            do Sys.error(5);
        let segment = 2048;
        let segment = offset;
        ...

(Reminder that this is NAND’s custom programming language; you can read it like Java)

In terms of modifying the memory allocator, this is all that is needed. The memory allocator normally starts at memory address 2048 and initializes its linked list data structure over there, the start of the heap memory region. This modification tells the memory allocator to start at the integer offset_ provided as an argument during initialization.

Sys.jack

class Sys {

    /** Performs all the initializations required by the OS. */
    function void init() {
        do Memory.init();
        do Memory.init(16384);
        do Math.init();
        do Screen.init();
        do Screen.clearScreen();
        do Output.init();
        do Main.main();
        do Sys.halt();
    }
    ...

The entrypoint of every NAND program is hardcoded to be Sys.init. When this function is called, it initializes the operating system libraries, runs Main.main to execute the program, and runs Sys.halt to terminate the program. It’s analogous to the _start entrypoint on Linux. We change Memory.init to take as input the start of the screen memory region, 16384, so the memory allocator allocates memory on the screen. Additionally, we have to disable the routine that automatically clears the screen at the start of every program because it zeros out the metadata that was just configured by Memory.init and renders the memory allocator unusable.

With that out of the way, let’s run it on a hello world program and see what happens.

Main.jack

class Main {
    function void main() {
        do Output.printString("Hello world!");
    }
}

Great, there’s our heap! If you look at the top left corner of the screen, you’ll see “Hello World!”. Printing the text to the screen overwrote some of the heap memory data. It looks wonderful, but this program is relatively uninteresting: it immediately terminates afterwards. Can we run the pong program initially shown with our modified, silly memory allocator? We need to do two more things.

Sys.jack

    ...
    /** Halts the program execution. */
    function void halt() {
        // Set a hardware-specific flag to tell the computer runtime to stop
        do Memory.poke(24576, 32767);
        while (~false) {}
    }
    ...

First, whenever a NAND program is finished or the operating system detects something logically invalid like dividing by zero, the operating system prints “ERR” followed by an error code number to the screen and calls Sys.halt to terminate the program¹. We don’t want our program to terminate for any reason, so we simply delete this code.

Second, we add a prompt before running the program that asks the user to enter an integer offset to add to the screen region memory address (i.e Memory.init(16384 + offset)). We do this because allocating heap data at the same place on the screen would produce the same results every time. It’s nice (as you will soon see) to introduce variety in the results. The code at this point doesn’t feel necessary to explain in full detail, so I’ve omitted it.

We’re off to the races. I spent a few days playing around with memory offsets and want to showcase the most interesting results. First up is memory offset 914:

Your browser does not support the video tag.

There’s a lot to unpack here! You might have noticed that the ball appears to teleport—this is because it is literally overwriting the bits that control its position on the screen while in motion. The ball then overwrites the paddle’s position bits to the top of the screen and height bits to approximately three times as tall. Despite the extensive memory corruption, why did the pong program still have some semblance of being able to run? NAND uses the Harvard architecture, which means that the program memory is stored separately from the instruction memory. The instruction memory can only be written to once when loading a program; it is read-only during its execution. So, the logic to move the paddle around and bounce the ball will always still exist.

Next, here is memory offset 777:

Your browser does not support the video tag.

The ball is doing some spooky things here—it’s supposed to move in a straight line as a reminder 👻. The main takeaway with this program is that it somehow restarts itself at the end. Why this happens is simple: the program executed an instruction that sets the program counter’s value to 0, effectively telling the program to jump to the first instruction and start over.

Your browser does not support the video tag.

Bam, what happened here? I would be lying if I said I knew exactly what happened, but what probably did is the program executed an instruction to jump to some random part in the instruction memory. At that point, all bets on what is supposed to happen are off: the abstractions of function calls and the program logic flow are destroyed. The processor might as well just be executing random instructions and interpreting random noise as memory. You invoked undefined behavior. NAND invoked Cthulhu.

I don’t have much to say about the next few videos, but you should give each one a moment to marvel at what is actually happening.

Here is memory offset 6:

Your browser does not support the video tag.

Here is a run with extra modifications that I don’t remember:

Your browser does not support the video tag.

Here is memory offset 577:

Your browser does not support the video tag.

Here is memory offset -10:

Your browser does not support the video tag.

This last one is my personal favorite because of how it long it lasts before restarting the program. Try to play pong all the way to the end; it’s a fun challenge.

I invite you to try out this program with your own memory offsets at NAND’s website. To run it, click “Load example program”, select “CorruptedPong”, and click “Start”. Note that your results will not always be deterministic because the program memory persists when a program is manually reset. If you want the same behavior every time, or if you want to reproduce the results of the memory offsets in my videos, make sure to first clear the program memory by clicking “Dec” on the memory view and selecting “Clr”.

So, yeah. Your takeaway should be that this could technically happen the next time you read one byte of memory out of bounds in C. Until next time!

Footnotes

If Memory.poke(24576, 32767) terminates the program, why does Sys.halt need an infinite loop? It boils down to an implementation detail in the computer runtime: the program will execute up to 30000 instructions at a time before polling memory address 24576 and testing if it is equal to 32767. So, it’s possible for other instructions to modify the program memory after setting the termination flag but before it is polled. It wouldn’t make sense for random memory to be modified after calling Sys.halt because it can be used to debug the program memory using the built-in memory view. As such, Sys.halt enters an infinite loop until the termination flag is actively polled again. ↩

The Generativity Pattern in Rust

Mon, 04 Aug 2025 17:59:01 GMT

This article was peer-reviewed by my close friends Henry Rovynak, Kartavya Vashishtha, Jack Hogan, Mikhail Khan and Crystal Durham. I thank them for their invaluable feedback. This article also uses special characters like the em-dash (—). These characters were lovingly hand-inserted and are not the result of AI-generated text.

Introduction
Background
- Permutations
- Permutation groups
The unsafe approach
The atomic ID approach
The generativity approach
- The fundamental purpose
- Why the implementation caveat?
How does generativity work?
Benchmarks
Conclusion

Introduction

The generativity pattern in Rust is a combination of typestate and GhostCell, techniques that move what you’d normally check at run-time to compile-time. This pattern is not commonplace; its usage warrants a specific set of circumstances. However, it is a hugely important part of garbage collection utilities and other niche Rust crates.

Aside from thinly spread academic literature¹, I haven’t found an accessible analysis of this pattern online. In order to build up a full picture of the “what” and more importantly the “why,” we will first spend some time walking through a realistic example to gauge the type of problem the generativity pattern solves—statically requiring data to come from or refer to the same source—as a stronger form of ownership. Then, we will introduce the generativity pattern and explain how to use it in the latter half of this article. Finally, we will follow up with a study of Crystal Durham’s generativity crate, a novel improvement to the generativity pattern. Buckle up!

Background

Permutations

Let us take the role of a crate author about permutations. We want to investigate the composition of zero-indexed permutations. This can be expressed nicely visually.

The permutation b defines the remapping of the elements from permutation a. Pretty simple. Notice that permutation composition is only possible under the following three conditions:

a and b must have the same length.
Every element from a and b must be non-negative and less than the length.
Every element from a and b must be unique.

Our library is general-purpose, so it is important to handle these error cases. Here is the simplest way to do that.

/// We provide a `compose_into` function in case the caller already
/// has a permutation preallocated. (This is good practice IMO).
pub fn compose_into(a: &[usize], b: &[usize], result: &mut [usize]) -> Result<(), &'static str> {
    if a.len() != b.len() || b.len() != result.len() {
        return Err("Permutations must have the same length");
    }
    let mut seen_b = vec![false; a.len()];
    let mut seen_a = vec![false; b.len()];
    for (result_value, &b_value) in result.iter_mut().zip(b) {
        if *seen_b
            .get(b_value)
            .ok_or("B contains an element greater than or equal to the length")?
        {
            return Err("B contains repeated elements");
        }
        seen_b[b_value] = true;

        let a_value = a[b_value];
        if *seen_a
            .get(a_value)
            .ok_or("A contains an element greater than or equal to the length")?
        {
            return Err("A contains repeated elements");
        }
        seen_a[a_value] = true;

        *result_value = a_value;
    }
    Ok(())
}

Good on you if this made your Rust senses tingle because we shouldn’t have to validate a and b every time. Rust allows us to enforce at the type level that they are valid permutations, using the newtype design pattern.

pub struct Permutation(Box<[usize]>);

impl Permutation {
    pub fn from_mapping(mapping: Vec<usize>) -> Result<Self, &'static str> {
        // This function errors if `mapping` is an invalid
        // permutation or its length does not match the second
        // argument. The implementation is ommitted.
        validate_permutation(&mapping, mapping.len())?;
        Ok(Self(mapping.into_boxed_slice()))
    }

    pub fn compose_into(&self, b: &Self, result: &mut Self) -> Result<(), &'static str> {
        if self.0.len() != b.0.len() || b.0.len() != result.0.len() {
            return Err("Permutations must have the same length");
        }
        for (result_value, &b_value) in result.0.iter_mut().zip(&b.0) {
            // SAFETY: `b` is guaranteed to be a valid permutation
            // whose elements can index `self`
            *result_value = unsafe { *self.0.get_unchecked(b_value) };
        }
        Ok(())
    }

    pub fn compose(&self, b: &Self) -> Result<Self, &'static str> {
        let mut result = Self(vec![0; self.0.len()].into_boxed_slice());
        self.compose_into(b, &mut result)?;
        Ok(result)
    }
}

The newtype pattern is more useful than just for getting around the orphan rule. We restrict construction of Permutation to Permutation::from_mapping, which returns an error if the input is not a valid permutation. That means if we have an instance of Permutation, we don’t have to worry about its mapping being potentially invalid, reducing the validation overhead to a length check and permitting unsafe during permutation composition. Rustaceans describe type-level guarantees like this by saying an invariant of Permutation is that it represents a valid permutation. Composing two permutations upholds this invariant, so we expose Permutation::compose to create a new Permutation from existing ones.

This code is a major improvement! It is simple, easy to use, and it provides reasonable errors. However, a closer examination reveals some problems:

Every call to our composition function spends time performing a length check. Our example is simplistic so it happens to be cheap, but this type of check may require more expensive logic in a practical scenario. Note that we can’t use const generic lengths because our library operates on arbitrarily-sized slices at run-time.
Returning a Result forces the caller to be prepared to handle the error variant. Library users might be able to guarantee that the length checks will pass, which would make the error handling more annoying than helpful.

Yes, these aren’t important problems per se, but they are still inconveniences to be aware of.

Permutation groups

We now want to extend our library to model a permutation group, a description of a set of permutations. In a permutation group, every permutation in the set can be written as a sequence of compositions of a select few base permutations, which we will use to represent the entire collection. For example, the manipulations of the Rubik’s Cube form a permutation group. Its base permutations which represent the entire permutation group are the six face rotations. By definition, every possible state on the Rubik’s Cube can be reached from a combination of those face rotations.

The illustrated turn is a permutation fifty-four elements long, because there are fifty-four stickers on a Rubik’s Cube².

It follows that if you compose two permutations in a permutation group, the resulting permutation will also be a permutation in that group. The reasoning is not so relevant; take this at face value.

A reasonable data structure for permutation groups looks like this:

pub struct PermGroup {
    base_permutation_length: usize,
    base_permutations: Vec<Permutation>,
}

impl PermGroup {
    pub fn new(
        base_permutation_length: usize,
        base_permutation_mappings: Vec<Vec<usize>>,
    ) -> Result<Self, &'static str> {
        for mapping in &base_permutation_mappings {
            validate_permutation(mapping, base_permutation_length)?;
        }
        Ok(Self {
            base_permutation_length,
            base_permutations: base_permutation_mappings
                .into_iter()
                .map(|mapping| Permutation(mapping.into_boxed_slice()))
                .collect::<Result<Vec<Permutation>, &'static str>>()?,
        })
    }

    pub fn base_permutations(&self) -> &[Permutation] {
        &self.base_permutations
    }
}

Your inner Ferris awakens. With the annoyances of our last iteration freshly in memory, you ask yourself: can we perform that length check (done in the validate_permutation function) during the creation of PermGroup, and avoid it entirely in Permutation::compose_into? Then, can we tweak our composition function to only operate on permutations from the same permutation group?

impl Permutation {
    // No `from_mapping` method. `Permutation` can only be
    // constructed within `PermGroup::new`, and accessed via
    // `PermGroup::base_permutations`.

    pub fn compose_into(&self, b: &Permutation, result: &mut Permutation) {
        for i in 0..result.0.len() {
            // SAFETY: ... ?
            unsafe {
                *result.0.get_unchecked_mut(i) = *self.0.get_unchecked(*b.0.get_unchecked(i));
            }
        }
    }

    pub fn compose(&self, b: &Permutation) -> Permutation {
        let mut result = Self(vec![0; self.0.len()].into_boxed_slice());
        self.compose_into(b, &mut result);
        result
    }
}

All of a sudden, we’ve opened up an unsafety hole! We implicitly assumed that the permutations to compose were from the same permutation group. This is not necessarily true: what if a library user composes two base permutations from different permutation groups? If the permutation lengths don’t match, get_unchecked will index out of bounds and exhibit undefined behavior; this is clearly a problem! The intent of this operation is obviously nonsensical, but it does not change the fact that it is still our responsibility, as the crate author, that the safe functions we provide can never cause undefined behavior.

There is a more fundamental reason to care about this unsoundness if left unchecked. An invariant of permutation composition within the same permutation group is membership; if the permutations to compose are in the same permutation group, the resulting permutation is also in that group. Even if the lengths of permutations from two different permutation groups did match, composing them could produce a permutation outside of either group, which is a logic error. Other code may even have unsafe blocks that rely on permutation group membership, for example a Rubik’s Cube solver optimized for speed.

Mitigating this by checking permutation group membership every function call is a very expensive operation. This is an example of the “practical scenario” mentioned beforehand.

We have demonstrated that the newtype pattern alone is not powerful enough to prevent this logic error. We will analyze different approaches that ensure our library only permits permutation composition within the same permutation group. Each has their own trade-offs, but are all right answers for different situations. They will also lay the groundwork to justify using the generativity pattern.

All the code segments provided in this article can be found here.

The unsafe approach

The simplest solution is to mark Permutation::compose_into and Permutation::compose unsafe.

/// # Safety
///
/// `self`, `b`, and `result` must all be from the same
/// permutation group.
pub unsafe fn compose_into(&self, b: &Permutation, result: &mut Permutation) {
    for i in 0..result.0.len() {
        // SAFETY: permutations within the same group can be
        // composed.
        unsafe {
            *result.0.get_unchecked_mut(i) = *self.0.get_unchecked(*b.0.get_unchecked(i));
        }
    }
}

Although the extent of the undefined behavior with permutation composition is just the bounds checking, the goal of this approach is to enforce permutation group membership. Thus, the above safety contract is made more restrictive to reflect this idea. The usage of unsafe to maintain a validity invariant is contentious. Permutation composition of the same length within different permutation groups is a logic error, and it violates the safety contract, but is not technically unsafe. Sure, you might panic later on or get some other issue, but this alone will never cause undefined behavior.

To play devil’s advocate, since we only care about composition within the same permutation group, one may consider producing an invalid value from this type of permutation composition undefined behavior. With the safety contract’s additional restriction, calling code no longer has to worry about handling this logic error, while additionally gaining the contextual benefit of this assumption. Personally, I believe this use of unsafe is warranted—at the end of the day, the safety contract does still prevent undefined behavior. I encourage you to have your own opinion.

If you don’t care about using unsafe—and there are valid reasons not to—then this might be what you want. That said, it’s not always going to be this simple. What if we introduce a new trait, ComposablePermutation, that generalizes over different permutation representations? For example, the PSHUFB instruction can compose two permutations in a single clock cycle if they have less than sixteen elements.

pub trait ComposablePermutation: Clone {
    fn from_mapping(mapping: Vec<usize>) -> Result<Self, &'static str>;

    /// # Safety
    ///
    /// `self`, `b`, and `result` must all be from the same
    // permutation group.
    unsafe fn compose_into(&self, b: &Self, result: &mut Self);

    /// # Safety
    ///
    /// `self` and `b` must both be from the same permutation
    // group.
    unsafe fn compose(&self, b: &Self) -> Self {
        let mut result = self.clone();
        // SAFETY: `self`, `b`, and `result` are all from the
        // same permutation group.
        unsafe { self.compose_into(b, &mut result) };
        result
    }
}

impl ComposablePermutation for Permutation {
    // ...
}

The consequences of using unsafe begin to show. Because our generic Permutation implements ComposablePermutation, and we have shown that permutation composition from different permutation groups may cause undefined behavior, Permutation::compose_into must be made unsafe at the trait level. Rust doesn’t allow us to only make Permutation’s implementation unsafe. Either all implementers must be made unsafe, or none at all. In a library about permutation composition, we have now forced our users to wrangle with unsafe for its most essential operation. Not just with Permutation::compose_into, but with all of their own implementations of ComposablePermutation!

“That is completely unfair!” You might say. “This is a small edge condition I don’t care about. I’m going to mark this trait method safe anyways.” Well, the Rust community generally has a zero-tolerance stance on undefined behavior; the last time someone wanted to mark an unsound method safe, it didn’t end very well.

The atomic ID approach

The second approach is to validate our base permutations upfront and use a private integer to associate them to a unique permutation group. This simplifies the test for permutation group membership to a cheap integer comparison. Internalizing how this approach works will be crucial to understanding the generativity approach. Rereading is encouraged.

use std::sync::atomic::{AtomicU64, Ordering::Relaxed};

pub struct PermGroup {
    base_permutation_length: usize,
    base_permutations: Vec<Permutation>,
    id: u64,
}

static ID: AtomicU64 = AtomicU64::new(0);

impl PermGroup {
    pub fn new(
        base_permutation_length: usize,
        base_permutation_mappings: Vec<Vec<usize>>,
    ) -> Result<Self, &'static str> {
        for mapping in &base_permutation_mappings {
            validate_permutation(mapping, base_permutation_length)?;
        }
        let id = ID.fetch_add(1, Relaxed);
        Ok(Self {
            base_permutation_length,
            base_permutations: base_permutation_mappings
                .into_iter()
                .map(|mapping| Permutation(mapping.into_boxed_slice(), id))
                .collect(),
            id,
        })
    }

    pub fn base_permutations(&self) -> &[Permutation] {
        &self.base_permutations
    }
}

The implementation of PermGroup does not actually change much. As before, we check that all mappings from base_permutation_mappings are valid permutations of the same length before creating a new PermGroup. This time, we utilize a global AtomicU64 to uniquely identify the permutations in a permutation group, passing it as an integer to Permutation. The integer is guaranteed to be unique for Permutations among different PermGroups because we increment the identifier every call to PermGroup::new.

pub struct Permutation(Box<[usize]>, u64);

impl Permutation {
    pub fn from_mapping_and_group(
        mapping: Vec<usize>,
        group: &PermGroup,
    ) -> Result<Self, &'static str> {
        validate_permutation(&mapping, group.base_permutation_length)?;
        let permutation = Self(mapping.into_boxed_slice(), group.id);
        validate_permutation_group_membership(&permutation, &group.base_permutations)?;
        Ok(permutation)
    }

    pub fn compose_into(&self, b: &Self, result: &mut Self) -> Result<(), &'static str> {
        if self.1 != b.1 || b.1 != result.1 {
            return Err("Permutations must come from the same permutation group");
        }
        for i in 0..result.0.len() {
            // SAFETY: `self`, `b`, and `result` have the same ID.
            // Therefore, they are members of the same group and
            // can be composed.
            unsafe {
                *result.0.get_unchecked_mut(i) = *self.0.get_unchecked(*b.0.get_unchecked(i));
            }
        }
        Ok(())
    }

    pub fn compose(&self, b: &Self) -> Result<Self, &'static str> {
        let mut result = Self(vec![0; self.0.len()].into_boxed_slice(), self.1);
        self.compose_into(b, &mut result)?;
        Ok(result)
    }
}

Creating a new Permutation now requires a mapping and a PermGroup reference. Once the mapping is verified as both a valid permutation and a member of that permutation group, only then is a new Permutation created with that PermGroup’s identifier, as a “token” of its membership. We can no longer create Permutations willy-nilly from just a mapping because that would offer no guarantees about the uniqueness of its identifier.

The fruits of our labor are rewarded in Permutation::compose_into. The expensive permutation group membership test is performed exclusively during Permutation’s creation. When two permutations are composed, those same “tokens” are used to cheaply verify membership within the same permutation group. Hence, callers can safely assume permutation composition produces another permutation in the same permutation group without compromising efficiency.

This solution is likely to be considered good enough in industry—most practitioners would need a good reason to care more about this problem. However, if your interest is piqued, what would really be nice is an infallible yet zero-cost permutation composition operation—one that is guaranteed to be valid at compile-time and as fast as the unsafe approach. If you’re willing to go a small step farther, we arrive at…

The generativity approach

The big reveal: the generativity approach is functionally equivalent to the atomic ID approach, except everything is done at compile-time. Generativity solves the fundamental problem thus far: the invariant of Permutation guarantees it is a valid permutation, but not that it is necessarily associated with a specific PermGroup.

Existing literature achieves generativity by sacrificing ergonomics and readability. They require wrapping all code in (often deeply nested) closures, warding off much of their interest in practice. We will spend the rest of this article examining Crystal Durham’s generativity crate, which utilizes a novel and highly experimental technique to achieve generativity without needing a closure. Later, we will show that the generativity crate is a zero-cost compile-time abstraction.

(Subtle-but-no-so-subtle foreshadowing: we will explore my own improvement to this technique in the next section)

use generativity::{Guard, Id, make_guard}

fn main() {
    // Create a variable `guard` of type `Guard<'_>`
    make_guard!(guard);
    // Consume that `guard` into an `Id<'_>`
    let id: Id<'_> = guard.into();
}

generativity publicizes three things: Guard, Id, and make_guard. Invoking the make_guard macro creates a Guard<'_> with a let binding, an identifier that carries a guaranteed unique lifetime. This lifetime is not actually used as a lifetime in the usual sense. It exists solely to make each instance of Guard<'_> a unique type. This is not voluntary nor merely a suggestion; the following does not compile because make_guard’s lifetime uniqueness guarantee cannot be broken³.

fn unify_lifetimes<'a>(a: &Guard<'a>, b: &Guard<'a>) {}

make_guard!(a);
make_guard!(b);
// rejected: unique lifetimes cannot be unified (this
// is not the actual compiler error message)
unify_lifetimes(&a, &b);

Id<'_> is like Guard<'_> except that it implements Copy and Clone while the latter does not. So, to create distributable copies of this identifier, you must consume a Guard<'_> into an Id<'_> using its From implementation. This is all that generativity exports.

With the generativity pattern in place, the body of PermGroup::new remains sound because it creates Permutations with the same lifetime identifier, making it unique among different PermGroups.

pub struct PermGroup {
pub struct PermGroup<'id> {
    base_permutation_length: usize,
    base_permutations: Vec<Permutation>,
    id: u64,
    id: Id<'id>
}

pub fn new(
    base_permutation_length: usize,
    base_permutation_mappings: Vec<Vec<usize>>,
    guard: Guard<'id>,
) -> Result<Self, &'static str> {
    for mapping in &base_permutation_mappings {
        validate_permutation(mapping, base_permutation_length)?;
    }
    let id = ID.fetch_add(1, Relaxed);
    let id = guard.into();
    Ok(Self {
        base_permutation_length,
        base_permutations: base_permutation_mappings
            .into_iter()
            .map(|mapping| Permutation(mapping.into_boxed_slice(), id))
            .collect(),
        id,
    })
}

Why is guard passed as an argument, and why isn’t make_guard creating it within the function body? This reveals generativity’s implementation caveat: a Guard<'id> can never escape the scope it was defined in. Think of creating a Guard<'id> as creating a reference to a local variable. No matter what, it is only valid inside of its enclosing scope.

So, instantiating two different permutation groups, for example, looks like this:

make_guard!(guard1);
make_guard!(guard2);
let first = PermGroup::new(..., guard1);
let second = PermGroup::new(..., guard2);
// rejected: `guard1` used after move
// let third = PermGroup::new(..., guard1);

The purpose of Guard<'id> when Id<'id> already exists becomes clear when considering that third is rejected by the compiler. If PermGroup::new accepted an Id<'id>, two different permutation groups could be assigned the same Id<'id> because it implements Copy.

Okay, this is all fine and dandy, but how does this help improve permutation composition?

pub struct Permutation(Box<[usize]>, u64);
pub struct Permutation<'id>(Box<[usize]>, Id<'id>);

Recall that every Id<'id> carries a unique lifetime among different PermGroup<'id>s. By combining Permutation with Id<'id> and a lifetime parameter, we create a collection Permutation<'id>s whose types are the same within a PermGroup<'id> but distinct from permutations within other PermGroups<'id2>s. Our permutation composition function takes in the same type Self for all arguments—it follows that Permutation<'id>s from different permutation groups cannot be composed as they are not the same type, and Permutation<'id>s from the same permutation group can be composed as they are the same type. This is the essence of the generativity pattern, enforced at compile-time.

Behold: a permutation composition function that is unchecked, infallible, and safe. The full implementation is here.

pub fn compose_into(&self, b: &Self, result: &mut Self) -> Result<(), &'static str> {
    if self.1 != b.1 || b.1 != result.1 {
        return Err("Permutations must come from the same permutation group");
    }
pub fn compose_into(&self, b: &Self, result: &mut Self) {
    for i in 0..result.0.len() {
        // SAFETY: `self`, `b`, and `result` are members of the
        // same group and can be composed.
        unsafe {
            *result.0.get_unchecked_mut(i) = *self.0.get_unchecked(*b.0.get_unchecked(i));
        }
    }
    Ok(())
}

Let us informally prove generativity’s equivalence to the atomic ID approach:

In the atomic ID approach, unique integer identifiers are created à la ID.fetch_add(1, Relaxed). This directly parallels make_guard!(guard), which creates a unique Guard<'id> identifier.
The unique integer identifier is then stored inside a primitive u64. This implements Copy and it is distributed among the input base permutations to associate each one with its permutation group. Similarly, Id<'id> serves this purpose.
The unique integer identifier is used to test permutation group membership during permutation composition, erroring if not the case. The generativity pattern directly embeds the same test into the type system.

It would be irresponsible for me to advertise the generativity crate as a perfect solution barring its implementation caveat. Yes, the implementation caveat is its only functional limitation, but there are some developer experience problems to consider.

Although there’s only a single line marked unsafe in our Permutation<'id> example, its soundness is now much harder to justify. It is on the developer to prove that 'id uniquely associates permutations to their permutation group; any mishandling could easily make the whole thing unsound (i.e. if PermGroup::new took an Id<'id> instead of a Guard<'id>).
The 'id lifetime, like all other lifetimes, is pervasive. Data structures that wish to store Guard<'id> or Id<'id>, or any other data structure that stores Guard<'id> or Id<'id>, must have a lifetime annotation. But make_guard is typically invoked at the outermost scope, and will likely have to be passed through many types, so the number of lifetime annotations is amplified.
Some APIs require types to satisfy 'static. For example, the closure passed to thread::spawn must satisfy 'static, making it impossible to return a Permutation<'id>. The workaround is usually an inconvenient band-aid; in this case the standard library offers thread::scope to borrow non-'static data in a thread.
The compiler errors from misusing generativity don’t provide the location of the error. They are generally confusing, even when you know how generativity internally works.

The atomic ID approach shares only the first problem. Given your use case, it might be what you want.

The fundamental purpose

Notice how different instances of Permutation<'id> masquerade as separate types even though they have the same underlying data representation. In Rust, 'id is known as a branded lifetime, or more generally, a type brand. The first principles of type branding date back at least to the work of John Launchbury and Simon Peyton Jones on the ST monad in Haskell (section 2.5.2) in 1995. Aria Desires’ master’s thesis (section 6.3) brought this into the context of Rust in 2015, coining lifetime branding in Rust with the term “generativity.” The more recent GhostCell paper by Joshua Yanovski and others utilized generativity to present interior mutability as a zero-cost abstraction in 2021.

This segues into an important point. The fundamental purpose of the generativity pattern is not necessarily to improve performance, but to statically require that individual values come from or refer to the same source. The performance benefits are a symptom of this requirement. I like to informally think of it as a stronger form of ownership.

For an alternative perspective, Aria Desires’ master’s thesis explores this idea with BrandedVec, an append-only vector. When the ith element of an ordinary vector vec is accessed through &vec[i], a run-time check is performed to see if i is in bounds. If not, then the program will panic. However, in many situations we know that the indices are always in bounds; one such case regards the append-only vector, the BrandedVec. All elements pushed to this type of vector are forever valid. Leveraging this fact, the push operation returns the index of the pushed element so it can later be used to soundly perform unchecked indexing.

If we want to mark the unchecked indexing operation safe, this returned index can’t be an ordinary usize. Bad actors may provide their own usize instead of one returned from the push operation. This returned index can’t be a newtyped usize either. The problem with this is a microcosm of the problem with our initial Permutation example: different indices from different append-only vectors may be used to unsoundly index one another. To make our accesses safe, the solution is to lifetime brand the returned indices to statically associate them with BrandedVec—the generativity pattern.

As hinted to beforehand, generativity has traditionally only been achieved through the use of a closure. The GhostCell paper includes this following example, taken from its inspired adaption of BrandedVec.

let vec1: Vec<u8> = vec![10, 11];
let vec2: Vec<u8> = vec![20, 21];

BrandedVec::new(vec1, move |mut bvec1: BrandedVec<u8>| {
    bvec1.push(12);
    let i1 = bvec1.push(13);
    let _idx = bvec1.get_index(0).unwrap();
    BrandedVec::new(vec2, move |mut bvec2: BrandedVec<u8>| {
        let i2 = bvec2.push(22);
        println!("{:?}", bvec2.get(i2)); // No bound check! Prints 22
        *bvec2.get_mut(i2) -= 1;         // No bound check!
        println!("{:?}", bvec2.get(i2)); // Prints 21
        println!("{:?}", bvec1.get(i1)); // Prints 13
        // rejected: i1 is not an index of bvec2
        // println!("{:?}", bvec2.get(i1));
    });
});

Each BrandedVec created from a Vec receives its own lifetime brand within each closure⁴. In terms of ergonomics, it’s not exactly your Friendly Neighborhood Spider-Man.

But through the generativity crate, we eliminate the rightward drift, changing just nine lines of BrandedVec’s implementation. The API now appears less foreign and more Rust-like.

let vec1: Vec<u8> = vec![10, 11];
let vec2: Vec<u8> = vec![20, 21];

make_guard!(guard1);
let mut bvec1 = BrandedVec::new(vec1, guard1);
bvec1.push(12)
let i1 = bvec1.push(13);
let _idx = bvec1.get_index(0).unwrap();

make_guard!(guard2);
let mut bvec2 = BrandedVec::new(vec2, guard2);
let i2 = bvec2.push(22);
println!("{:?}", bvec2.get(i2)); // No bound check! Prints 22
*bvec2.get_mut(i2) -= 1;         // No bound check!
println!("{:?}", bvec2.get(i2)); // Prints 21
println!("{:?}", bvec1.get(i1)); // Prints 13
// rejected: i1 is not an index of bvec2
// println!("{:?}", bvec2.get(i1))

Our digression in bringing up this comparison has an ulterior motive. The original closure technique bears the exact same implementation caveat with generativity: nothing declared inside of the closure can escape it. make_guard effectively does the same thing as wrapping the rest of the function in an immediately invoked closure, and is no less capable than the closure technique.

Why the implementation caveat?

Let us offer another perspective as to why Guard<'id> cannot escape its defining scope. StackOverflow user rodrigo points out that you can achieve something similar to generativity using an anonymous unit struct and a macro to create the permutation group. Successive calls to this macro create permutation groups branded by this newly generated unit struct. In the context of our Permutation example, example usage looks like this. The full implementation is here.

#[macro_export]
macro_rules! new_perm_group {
    ($len:expr, $mappings:expr) => {{
        let len = $len;
        let mappings = $mappings;
        struct InvariantToken;
        // SAFETY: private API, only used in this macro.
        unsafe {
            $crate::PermGroup::<InvariantToken>::new(len, mappings)
        }
    }};
}

let first_perm_group = new_perm_group!(4, vec![vec![1, 2, 0, 3]]).unwrap();
let second_perm_group = new_perm_group!(3, vec![vec![2, 0, 1]]).unwrap();
let first_perm = &first_perm_group.base_permutations()[0];
let second_perm = &second_perm_group.base_permutations()[0];

// rejected: `first_perm` and `second_perm` are not the same type
// first_perm.compose(second_perm);

The flaw is quite subtle. The macro constructor creates a token per-call-site instead of per-owner. Every expression results in a particular type; if the same macro is run more than once, it will produce the same type, even if it is unique to the expression. This can be exploited to give multiple owners the same brand. To exemplify:

let first = (4, vec![vec![1, 2, 0, 3]]);
let second = (3, vec![vec![2, 0, 1]]);

let mut perm_groups = vec![];
for (len, mappings) in [first, second] {
    // I expanded the macro to make it easier to understand!
    // perm_groups.push(new_perm_group!(len, mappings).unwrap());

    perm_groups.push({
        let len = len;
        let mappings = mappings;
        struct InvariantToken;
        // SAFETY: private API, only used in this macro.
        unsafe {
            crate::PermGroup::<InvariantToken>::new(len, mappings)
        }
    }.unwrap());
}
let first_perm = &perm_groups[0].base_permutations()[0];
let second_perm = &perm_groups[1].base_permutations()[0];

// not rejected, UB!
first_perm.compose(second_perm);

We have just invoked undefined behavior from safe user-facing code. This is unsound without question, and there is no point in endorsing this approach.

There is a remedy: combine InvariantToken with a locally-scoped lifetime, as illustrated in binarycat’s crate typetoken. This only creates a strictly less capable version of generativity. There is no point in endorsing this approach either.

If the above code were possible with generativity, 'id could escape the scope and assign all elements of the vector the same lifetime brand. We would have the exact same unsoundness problem, thus we cannot use a loop to create a dynamic number of PermGroup<'id>s.

How does `generativity` work?

At this point a good part of my readers are itching to know what makes the generativity crate so magical compared to the age-old closure technique. The suspense is probably killing you. Or more likely putting you to sleep. We will introduce the inner workings of generativity top-down. I will first present my own minimal rewrite of the generativity crate, called min_generativity. Then, we will comprehensively walk through how each part of it works.

`min_generativity`

use std::marker::PhantomData;

pub type Id<'id> = PhantomData<fn(&'id ()) -> &'id ()>;

pub struct Guard<'id>(pub Id<'id>);

impl<'id> From<Guard<'id>> for Id<'id> {
    fn from(guard: Guard<'id>) -> Self {
        guard.0
    }
}

pub struct LifetimeBrand<'id>(PhantomData<&'id Id<'id>>);

impl<'id> LifetimeBrand<'id> {
    pub fn new(_: &'id Id<'id>) -> Self {
        LifetimeBrand(PhantomData)
    }
}

impl<'id> Drop for LifetimeBrand<'id> {
    fn drop(&mut self) {}
}

#[macro_export]
macro_rules! make_guard {
    ($name:ident) => {
        let branded_place: $crate::Id = std::marker::PhantomData;
        let lifetime_brand = $crate::LifetimeBrand::new(&branded_place);
        let $name = $crate::Guard(branded_place);
    };
}

Before we get started, let’s get some low hanging fruit out of the way. We can verify that min_generativity is zero-cost: every single type is some form of PhantomData, a zero-sized type that is optimized away at compile-time. However, there is a sharp corner: we create a reference to a PhantomData in make_guard, and references to zero-sized types are perhaps surprisingly not zero-sized due to some idiosyncrasies. Thus, we cannot prove min_generativity is zero-cost as Rust lacks a specification for optimization behavior. I claim that in practice this is the case the overwhelming majority of the time. The reference: is never used anywhere, is associated with an unused variable (lifetime_brand), and has no Drop impl. Even at the most basic optimization level, rustc is smart enough to no-op everything.

Note that min_generativity benevolently assumes that library users will only use make_guard to construct Id<'id> and Guard<'id>, as both are public types with public field visibility. The actual generativity crate privatizes Id<'id> (via a newtype) and Guard<'id> and marks their constructors unsafe, hidden within make_guard. Such was omitted to be concise.

The first part

use std::marker::PhantomData;

pub type Id<'id> = PhantomData<fn(&'id ()) -> &'id ()>;

If you’ve only used PhantomData when the compiler has told you to, this certainly looks nonsensical. The purpose of Id<'id> as we saw earlier is to carry a unique lifetime brand among different PermGroup<'id>s, but aren’t lifetimes already unique? What’s the deal?

In Rust, variance determines whether you can substitute one lifetime for another. If you have a longer lifetime, Rust lets you use it where a shorter one is expected. This is also known as subtyping. Normally this is good—subtyping introduces static analysis that allows for more programs to compile—but in our case this automatic substitution works against our favor. If an Id<'id> can be tied to a lifetime other than its lifetime brand, we lose. So, the unique lifetime 'id must have no subtyping relation with other lifetimes; 'id is what’s called an invariant lifetime.

The contemporary usage of the word “invariant” by Rustaceans has two meanings: one as a type-level guarantee (a noun), and one as a no-subtyping relation (an adjective). Invariant generally means something that cannot change or must be fixed to a specific value. Both meanings refer to this same general concept. We’ve been working with the first meaning so far, but for the rest of this article we’ll switch to the second one.

To make 'id invariant, we take advantage of a fundamental constraint with function pointer types. When you have fn(&'id T) -> &'id T, the caller provides a reference with lifetime 'id and expects to get back a reference with that same lifetime 'id. If Rust allowed the function pointer type to accept a longer lifetime but return a shorter one, or vice versa, it would break this explicit contract. You might pass in a reference that lives for ten seconds but get one back that lives for five seconds, creating a dangling pointer. Function pointer types with the same lifetime in the input and output positions force that lifetime to be invariant. No substitution allowed.

Of course, we don’t actually want to store a function pointer at run-time. We only utilize it to make 'id invariant at compile-time. The language provides PhantomData to enable fine-grained control over variance. In this case it tells the compiler to pretend like it holds a function pointer while not actually taking up any space.

Throughout the years lifetime invariance has been achieved in several other ways.

pub type Id<'id> = PhantomData<&'id mut &'id ()>; // Rust standard library
pub type Id<'id> = PhantomData<*mut &'id ()>; // GhostCell paper
pub type Id<'id> = PhantomData<Cell<&'id u8>>; // Aria Desires' master's thesis
pub type Id<'id> = PhantomData<Cell<&'id mut ()>>; // Also from her master's thesis

They work because they follow the core principal that &mut T is invariant over T (click here to see why). With T = &'id (), 'id must become invariant. Unlike the others, PhantomData<fn(T) -> T> implements all auto traits (Send, Sync, etc) for its owner, and it is generally preferred to convey that the only purpose is to indicate invariance. For further reading, the Rustonomicon provides a table of common PhantomData patterns.

When I first learned how to use PhantomData to indicate variance I couldn’t help but think of it as an obnoxiously leaky abstraction. There is a movement to make it a bit more ergonomic by introducing custom variance newtypes into the standard library, i.e. PhantomInvariantLifetime. Sure enough, the status quo of PhantomData has been considered “something of a failure.”

The second part

pub struct Guard<'id>(pub Id<'id>);

impl<'id> From<Guard<'id>> for Id<'id> {
    fn from(guard: Guard<'id>) -> Self {
        guard.0
    }
}

The entire implementation of Guard<'id> is a newtype around Id<'id>. The established difference being that Guard<'id> doesn’t implement Copy or Clone. We provide a From implementation to consume a Guard<'id> into an Id<'id> to create distributable copies of the lifetime brand, as we saw earlier.

The third part

pub struct LifetimeBrand<'id>(PhantomData<&'id Id<'id>>);

impl<'id> LifetimeBrand<'id> {
    pub fn new(_: &'id Id<'id>) -> Self {
        LifetimeBrand(PhantomData)
    }
}

impl<'id> Drop for LifetimeBrand<'id> {
    fn drop(&mut self) {}
}

#[macro_export]
macro_rules! make_guard {
    ($name:ident) => {
        let branded_place: $crate::Id = std::marker::PhantomData;
        let lifetime_brand = $crate::LifetimeBrand::new(&branded_place);
        let $name = $crate::Guard(branded_place);
    };
}

It turns out that disabling lifetime subtyping is not enough. While Rust believes it’s unsound to freely resize 'id, there’s nothing that constrains where 'id should come from. Consider the following system:

fn unify_lifetimes<'id>(_: &Id<'id>, _: &Id<'id>) {}

let id1: Id<'id1> = PhantomData;
let id2: Id<'id2> = PhantomData;
unify_lifetimes(&id1, &id2);

The constraint solver realizes there is no logical contradiction with the obvious solution of 'id2 = 'id1, and it allows this program to compile. We need to uniquely tie 'id1 and 'id2 to their respective declaration sites to prevent Rust from unifying them.

After make_guard creates branded_place and generates an invariant lifetime 'id, we are now armed with the knowledge required to examine how LifetimeBrand ensures it is non-unifiable. It takes the approach of establishing distinct lower and upper bounds for 'id, highlighting the need for a macro with protected hygiene to prevent these bounds from potentially being manipulated.

Notice that LifetimeBrand carries the phantom type &'id Id<'id> (to avoid actually storing the reference). The existence of LifetimeBrand’s Drop impl means this borrowed data could potentially be used at the end of the scope, delegating special analysis called the drop check. The drop check forces the compiler to extend 'id to live at the point where lifetime_brand is dropped, constituting our lower bound. The actual Drop impl is purposefully left blank.

An important guarantee from the compiler is that local variables in a scope are dropped in the opposite order they are defined. Now we must prevent successive make_guard invocations in the same scope from unifying with the first invocation whose lifetime lives the longest. We are left with a need to upper-bound 'id, and this is done by tying 'id to the borrow of what created it. So, any expansion of 'id would mean branded_place’s borrow of lifetime 'id wouldn’t live long enough when it is dropped.

If you still find it confusing, I encourage you to work out rustc’s error message in this example. I also encourage you to play around with this code snippet to see what compiles and what doesn’t. I’ve found this exercise illuminating. Another tip to help you understand is to remember the pithy saying that lifetimes are descriptive, not prescriptive.

Verifying soundness

It is easy to verify that generativity is sound.

make_guard!(id1);
make_guard!(id2);
assert_eq!(id1, id1);
assert_eq!(id2, id2);
// rejected: `branded_place` does not live long enough
// assert_eq!(id1, id2);

At the time of writing, this test case passes. However, generativity’s vice is that it relies on internal behavior from the drop check analysis, the precise rules of which have historically been ill-defined and subject to change. In theory, sufficiently advanced analysis would be able to see that dropping lifetime_brand doesn’t require 'id to live because its Drop impl is empty, destroying the uniqueness guarantee we have created.

Pertaining to our concerns, any weakening of the drop check forcing captured lifetimes to live will most likely be opt-in, based on the direction of the “drop check eyepatch” RFC. It introduces the unsafe #[may_dangle] attribute which relaxes this requirement. #[may_dangle] opts-in a struct’s Drop impl to say, “I don’t access a generic parameter, so it can be dropped before I run.” Drop check eyepatch was introduced as a hacky refinement over “unguarded escape hatch,” which permitted high-priority collections like Vec<&T> to drop despite the &T borrow being invalidated beforehand.

Here are some famous last words. Drop check eyepatch was accepted nine years ago, yet stabilization is still opposed. There are too many subtle gotchas with respect to the drop check that have been found to be too much of a footgun even for an internal compiler feature. It has resulted in unsoundness multiple times. The stable analysis is deliberately conservative for this reason. To quote from the Rustonomicon’s explanation of #[may_dangle], “it is better to avoid adding the attribute.”

The existing avenue of improvement clarifies the semantics but still holds that this behavior will be opt-in. Hence, we can strengthen our confidence that the livelihood requirements for generativity will remain sound.

There are two other soundness concerns that are unlikely to be problematic but are still brought up in brief:

generativity relies on an unused variable, lifetime_brand, to impact borrow checking and the drop check. If support for unused variable analysis is ever removed, then scopeguard, a crate with hundreds of millions of downloads, would break, and Rust is very careful not to break existing code. scopeguard also relies on the Drop impl of an unused variable. Additionally, with the drop check, borrow checking must also run by virtue of lifetime_brand’s Drop impl, which could possibly access the borrow⁵.
In the ultra rare case where generativity is used in a divergent function, the drop checker will realize that Drop never runs and skip the drop check entirely. Special care is required in this case to uphold soundness.
It may still be hard to trust the delicate configuration of upper and lower bounding the generated lifetime. With non-lexical lifetimes stabilized in 2022 as the second edition of the borrow checker, the only planned next iteration is Polonius, the implementation of which currently passes the aforementioned test case. I haven’t given it much thought, but proving generativity’s soundness with Polonius’ formal model of the borrow checker would be a fun project (to me at least).

Language support

We can no longer ignore the elephant in the room with the make_guard macro: it looks ugly. It injects local variables into the current scope, and we saw this was necessary in the statement-position to prevent the lifetime bounding tricks from being manipulated. For a while there was no resolution, until just a few months ago when the experimental super let feature was introduced to extend the lifetimes of block-scoped variables. By creating a block scope, expression-position make_guard is made possible on nightly Rust.

#![feature(super_let)]

// ...

#[macro_export]
macro_rules! make_guard {
    ($name:ident) => {
        let branded_place: $crate::Id = std::marker::PhantomData;
        let lifetime_brand = $crate::LifetimeBrand::new(&branded_place);
        let $name = $crate::Guard(branded_place);
    };
    () => {{
        super let branded_place: $crate::Id = std::marker::PhantomData;
        super let lifetime_brand = $crate::LifetimeBrand::new(&branded_place);
        $crate::Guard(branded_place)
    }};
}

fn main() {
    make_guard!(guard);
    let guard = make_guard!();
}

Furthermore, there are preliminary ideas that would allow make_guard to be a function instead of a macro. The feedback for super let has so far been positive, so once the semantics are ironed out I think efforts to stabilize this feature will be underway.

My last contribution to this discussion is some wishful thinking about first-class language support for generativity. The troubles with unique lifetime branding stem from the fact that Rust offers no way to prevent lifetimes from unifying. So, I propose the #[nonunifiable] lifetime attribute. It would allow lifetimes to declaratively guarantee non-unifiability without having to resort to generativity’s lifetime bounding tricks. #[nonunifiable] is not intended to indicate variance—that’s the job of PhantomData. For the permutation example, first-class language support from the compiler would look like this. The full implementation is here.

pub struct PermGroup<#[nonunifiable] 'id> {
    base_permutation_length: usize,
    base_permutations: Vec<Permutation<'id>>,
    id: PhantomData<fn(&'id ()) -> &'id ()>
}

pub struct Permutation<'id>(Box<[usize]>, PhantomData<fn(&'id ()) -> &'id ()>);

First-class language support is also the perfect excuse to improve the confusing compiler errors:

let first = PermGroup::new(4, vec![vec![1, 2, 0, 3]]).unwrap();
let second = PermGroup::new(3, vec![vec![2, 0, 1]]).unwrap();
let first_perm = &first.base_permutations()[0];
let second_perm = &second.base_permutations()[0];

first_perm.compose(second_perm);

error[E0308]: mismatched types
 --> src/main.rs:9:23
  |
6 |     let first_perm = &first.base_permutations()[0];
  |         ---------- binding `first_perm` declared here with nonunifiable lifetime `’1`
7 |     let second_perm = &second.base_permutations()[0];
  |         ----------- binding `second_perm` declared here with nonunifiable lifetime `’2`
8 |
9 |     first_perm.compose(second_perm);
  |                ------- ^^^^^^^^^^^ expected `Permutation<'1>`, found a different `Permutation<'2>`
  |                |
  |                arguments to this method are incorrect
  |
  = note: expected reference `&Permutation<'1>`
             found reference `&Permutation<'2>`
  = note: `Permtuation<'1>` and `Permutation<'2>` look like similar types, but are distinct because they carry `#[nonunifiable]` lifetimes

Jack (one of this article’s peer reviewers) and I discussed what first-class language support to remove the lifetime parameter and allow Guard to escape its scope could look like. Unfortunately, we came to the conclusion that such a system would be equivalent to the problem case described in Why the implementation caveat?. Creating an arbitrary number of branded types in a loop during run-time would require deep changes to the type system.

Maybe #[nonunifiable] will have an unexpected use case that would make it practical, or maybe not. I’m not going to pretend like I’ve figured out all of the semantics. The point is to get my thoughts up in the air.

Benchmarks

No comparison would be complete without a benchmark. Yes, the point of the generativity pattern is more fundamental than just speed, but I know what people want. I statically generated two random length-fifteen permutations and wrote a Criterion benchmark for all five approaches to permutation composition.

Benchmark Name	Time (ns)
1-slice	14.805
2-newtype	4.257
4-atomic_id	3.940
5-generativity	3.604
3-unsafe_trait	3.602

Empirically, this validates all of my observations. The naive 1-slice is the slowest because it checks every permutation for complete validity during composition. 2-newtype removes most of the validation overhead. Admittedly this is good enough; again, from a practical standpoint, you would only care about the other solutions if you could prove that permutation composition was the bottleneck. 4-atomic_id replaces the validation with a single integer comparison, making it marginally faster, likely because it avoids dereferencing. Finally, 5-generativity and 3-unsafe_trait emerge the fastest because they avoid validation entirely, and I have also verified that the generated machine code is identical. The important difference: 3-unsafe_trait marks permutation composition unsafe while 5-generativity does not.

Conclusion

Truthfully I don’t have many final thoughts. I just needed a transition to end this article. I suppose my primary conclusion is that this article has gotten far longer than I had originally planned 😛.

I don’t think this is a bad thing; its comprehensiveness more than makes up for it. The hidden agenda was to survey design patterns and write about Rust code I thought were interesting, culminating with the generativity pattern, which shows us how to take advantage of the type checker’s power in a non-obvious manner.

This concludes my first educational write-up on my blog. I came into this topic with surface level understandings of what generativity, PhantomData, and the drop check are and how they work. I was not expecting this to take five weeks of meticulous research and writing throughout my summer break in undergrad. I was entirely unprepared for how interesting the full story would be.

Thank you for reading this far :-). Until next time!

Footnotes

Yes, I will eventually get to them. You just need to keep reading. ↩
The center stickers don’t actually move, and thus can be ignored, so the illustrated turn is traditionally simplified to a permutation forty-eight elements long. ↩
This lifetime is not technically unique. You could unify it with another lifetime in a similar function call: fn unify_lifetimes<'id>(impostor: &'id (), guard: &Guard<'id>) { ... }. The lifetime is only unique among the provided Id<'id> and Guard<'id> types, so as long as your code only trusts lifetimes carried by those types it will be sound. ↩
Rust doesn’t have rank-2 polymorphism, so we need to replicate it using a closure with a Higher-Rank Trait Bound. The type signature of the closure passed to BrandedVec::new is inner: impl for<'id> FnOnce(BrandedVec<'id, T>) -> R, and this just means every call to inner must be prepared to handle an argument with any possible lifetime. Within a single function the compiler has perfect information, but calling inner inside BrandedVec::new tricks the borrow checker. Since it doesn’t (and will likely never) do interprocedural analysis, it conservatively sees every call to inner as producing an opaque lifetime that can’t be unified with any other. To avoid any relation with an existing lifetime, a fresh new lifetime is statically generated for every call to BrandedVec::new, our lifetime brand for BrandedVec<'id, T>. This is just a brief overview of a well-investigated topic. Repeating for convenience, further reading is encouraged here (section 6.3) and here (section 2.2.1). ↩
Unreachable code on the other hand is not borrow checked because it simply wasn’t a priority. ↩

Turning Image Corruption into Art

Wed, 14 May 2025 05:15:02 GMT

You might have heard of the recent “Replicate Image” trend. It reminded me of something I used to do when I was younger. When I was bored, or had some sort of exam tomorrow, I would open a JPEG in TextEdit and delete random binary data to see how it would corrupt the image. It turns out that modern image formats are quite malleable, and more often than not, you would still end up with a decodable image! Definitely a little geeky, but hear me out, it was a surprisingly fun way to waste time pointing out the bizarre image artifacts. As you may have guessed, I was spontaneously motivated to turn this into its own “Replicate Image” project.

The gist: I would write a program that would randomly tweak a few bytes of an image a thousand times over. Then, I would compile every image into a video of the process from start to finish, and do this many times for different image formats. Let’s get to it.

First, I needed a target image to work with, ideally something with interesting color variety. My close friend Adrian snapped this cool picture demonstrating the concept of symmetry on the Rubik’s Cube.

This marvelous composition has no idea what it's about to go through

Perfect! Now, a simple Python script to perform our byte-hacking does the trick, using ffmpeg to perform some error checking.

image_corrupt.py

import argparse
import sys
import subprocess
import random
from pathlib import Path

COUNT = 1000

parser = argparse.ArgumentParser(description="Corrupt an image file.")
parser.add_argument(
    "image_file",
    type=str,
    help="The image file to corrupt"
)

args = parser.parse_args()
file = Path(args.image_file)
base = file.stem
ext = file.suffix[1:]
if not ext:
    print("image_corrupt.py: Please provide an image file with an extension.")
    sys.exit(1)
if not file.exists():
    print(f"image_corrupt.py: File {file} does not exist.")
    sys.exit(1)

with open(f"{base}.{ext}", "rb") as f:
    data = bytearray(f.read())

subprocess.run(["mkdir", "-p", f"{ext}s"])

for i in range(COUNT):
    while True:
        olddata = data[:]
        # The beginning has important metadata
        pos = random.randint(100, len(data) - 1)
        # I didn't have luck *deleting* bytes, as the image
        # quickly became unrecoverably corrupted. I found success
        # in just incrementing each randomly selected byte
        data[pos] = (data[pos] + 1) % 256
        with open(f"{ext}s/{i:04}.{ext}", "wb") as f:
            f.write(data)
        if (
            subprocess.run(
                [
                    "ffmpeg",
                    "-v",
                    "error",
                    "-i",
                    f"{ext}s/{i:04}.{ext}",
                    "-f",
                    "null",
                    "-",
                ],
                stderr=subprocess.DEVNULL,
            ).returncode
            == 0
        ):
            break
        data = olddata

I converted Adrian’s picture to JPEG, PNG, WEBP, and AVIF and ran my script to generate the images. So far, the results looked extremely promising.

You could hang this up on a wall in your house and pass it off as an eccentric art piece. Somebody could come in and have no idea what they were looking at was the result of changing a single byte from an original image

To convert the images to a video, I experimented with two different methods. First, a simple Google search demonstrates directly using ffmpeg like so.

image_corrupt.sh

#!/bin/bash

# The image extension
ext=...
# The image base name
base=...

# Assume the generated images are in "${ext}s"
cd "${ext}s"
# If ffmpeg doesn't glob-match properly, follow this
# https://stackoverflow.com/a/64407890/12230735
ffmpeg -framerate 30 -pattern_type glob -i "*.$ext" -c:v libx264 -pix_fmt yuv420p -vf "pad=ceil(iw/2)*2:ceil(ih/2)*2" "$base".mp4
echo
echo Done! Generated "$base".mp4 in the directory "${ext}s".

However, most of my experimentation with this approach was uninteresting. ffmpeg conservatively repairs each image fed as input when converting to video. The files were apparently so viscerally mangled that ffmpeg deems the whole operation unworthy and just gives up.

ffmpeg's entire 30 second video is a green screen with occasional flickering

Alternatively, you could first use ImageMagick to convert the images to a GIF and then use ffmpeg to convert that GIF to a video. Yes, this was literally the only intermediary step I could get working. The plan isn’t entirely foolproof. Despite the error checking from ffmpeg, some of the generated images were still invalid. I figured out that re-feeding each image one-by-one into ffmpeg repaired them enough to shut up ImageMagick’s complaints without compromising the image data. Thanks kind strangers. I love the Internet!

image_corrupt.sh

#!/bin/bash

# The image extension
ext=...
# The image base name
base=...

# Assume the generated images are in "${ext}s"
cd "${ext}s"
# Use parallel processing if `parallel` is installed
if command -v parallel &> /dev/null; then
    # Functionally identical to the `else` branch
    parallel --progress --eta ffmpeg -y -i {} _{} ::: *."$ext"
    for file in [!_]*."$ext"; do
        mv "_$file" "$file"
    done
else
    for file in *."$ext"; do
        ffmpeg -y -i "$file" "_$file"
        mv "_$file" "$file"
    done
fi
# I had to resort to ImageMagick's deprecated `convert` program because
# ImageMagick would sometimes crash more than half way through without
# generating the GIF. The old version handled this correctly, and I
# couldn't figure out how to make the current version do this.
magick convert -limit memory 100000 ./*."$ext" "$base".gif
ffmpeg -itsscale 0.2 -i "$base".gif -movflags faststart -pix_fmt yuv420p -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" "$base".mp4
echo
echo Done! Generated "$base".gif and "$base".mp4 in the directory "${ext}s".

Most of what you’re about to see was produced by this cursed workaround. Compared to ffmpeg, ImageMagick was far less pedantic about repairing images, so the results turned out more visually interesting.

With everything in hand, off to the races! First up, PNG.

Your browser does not support the video tag.

PNGs were the hardest to corrupt. Each image iteration took a few dozen attempts before finding a byte that could be changed while still passing the error checking mechanism. Intuitively, this makes sense. PNG is a lossless format from 1995, when data corruption was endemic and most small companies had their connectivity through flaky phone lines. So, the PNG designers put a strong emphasis on data integrity, making every image chunk include a cycle redundancy check (CRC), and adding even more checks for more important image chunks. What you’re seeing is probably just ffmpeg trying its best to recover from malformed CRCs.

Additionally, I got this one work. Some more techno spaghettio.

Your browser does not support the video tag.

Next up, JPEG.

Your browser does not support the video tag.

I was really excited to be able to make out block splitting and the discrete cosine transform. This is the stuff I live for! Unlike every other format, I was only able to make this interesting by skipping the repair phase with ffmpeg and directly feeding each image to ImageMagick. Even though ImageMagick was operating on raw, corrupted JPEGs, it was still able to recognize three-fourths of the generated images before crashing. A quick look at JPEG’s syntax and structure corroborates that its only form of data integrity is sparse “restart markers” that don’t seem to have much effect. Honestly, JPEG data corruption is itself a whole other topic worth investigating. See the JPEG editor on this excellent blog.

Up again, WEBP.

Your browser does not support the video tag.

It’s not quite static noise, and it’s not quite order either. It’s like you’re trying to remember something, but you can only see a blurry mess of pixels. There is more detail than meets the eye; you could pause at any timestamp and land on a novel expression of color. On the technical side, WEBP worked without issue and was well-behaved. I don’t have much else to say, so let’s finally move on to AVIF.

Your browser does not support the video tag.

This took me many tries to get right. It’s my favorite one, and it’s incredibly mesmerizing!

I asked my friend Matthew to give me another image to corrupt with the AVIF format. This was the highest quality video I could produce before ImageMagick ran out of memory. The result also ended up being awesome!

Your browser does not support the video tag.

I’ve written some goofy blog posts before, but this one takes the cake for how much fun I working on it. I have made the source code public so you can try corrupting your own images. Do let me know how it goes. Until next time!

An Image Compression Tip with Astro

Sat, 10 May 2025 03:57:18 GMT

Thanks to my friend Eric for telling me about this! If you use Astro, the web framework this site is built on, there is a sweet drop-in replacement for the <Image> component that offers better compression:

<Image
<Picture 
    formats={["avif", "webp"]}
    src={penguinSrc}
    alt="A very cool penguin!"
/>

Better, you can create a light component wrapper around this technique called <ContentImage> to encapsulate the formats parameter.

The <Picture> component instructs the browser to use the modern AVIF format for efficient image compression. If your browser doesn’t support AVIF (which is unlikely), it falls back to the WEBP format, what <Image> already compiles to. However, this of course means Astro generates two versions of every image, so keep that in mind if you have many images on your site.

A side note: AVIF is amazing! Someone managed to compress the entirety of Shrek in 8MB. How it works is borderline magic, and its future looks bright. Once it becomes a little more mature in the web ecosystem, I have no doubt <Image> will eventually compile to AVIF and automate this process.

Until next time!

Two Years of University

Wed, 30 Apr 2025 02:39:17 GMT

Throughout my teenage years, college felt like a mystery. I had a general idea of what life was like after college, through TV shows, my parents, and the Internet. And, at that time, I was exactly living through life before college. College itself, on the other hand, was a black box, where people go into, are never heard from again until after four years, and magically transform into adults. I had no idea what to expect from going into college, and would often be met with the dull “it’s the best time of your life” and “it’s a place to discover yourself.” Maybe I was just ignorant, but this was overwhelmingly how I felt. I cried on my first night in my dorm room.

Now, I completed two years as a computer science major and electrical computer engineering minor at Purdue University! Okay, I still have two more weeks before the year ends, but whatever. Sue me. If you are expecting me to say something meaningful about the college experience, I’m not going to pretend like the conventional advice about college is untrue. It would feel disingenuous to try regurgitating it, so all I have to say in that regard is I’m loving every moment of university so far. This is my blog after all, so let’s go over what’s happened since my last update.

I ditched the skateboard

From the beginning to end of 2024, I learned how to skateboard, became moderately good at it, and quit without looking back. On my way to class, my back foot hit the back wheel while pushing off my board sending me tumbling into the asphalt. It was a very rough fall, and I eventually turned out fine, but I was spooked enough when it happened again that I decided skateboarding wasn’t worth jeopardizing my well-being. Oh well, I’m glad I tried it out.

I uninstalled social media

I used to be morbidly addicted to social media. Quintessential Gen Z stuff. I’m not entirely clean, I still watch a lot of YouTube, my last vice, but I’ve phased out everything else from my life. Ultimately, none of it ever mattered to me. I am proud to say that I have recently been spending my time focusing on things I care about.

I took interesting classes

I declared a minor in electrical computer engineering! This semester I finished my first electrical engineering fundamentals class, absolutely loving it, albeit scary at first. Truthfully, I wasn’t confident about taking up the minor; it’s not something you usually hear CS majors doing. Compared to other minors, I had to take triple the number of classes, forcing me to stay at Purdue for all four years. It’s not particularly helpful on a resume either. Don’t get me wrong, while an ECE minor is nice to show off, there are better time investments into my career for my major. In my interpretation, these arguments were missing of the point of a minor¹: to do something because you enjoy it. I would never be able to live with myself if I passed up the opportunity to take advantage of one of the best engineering programs in the world and Purdue’s maker space culture.

I made an audio equalizer circuit!

As a student, I had always hated English class. The word “hate” isn’t used lightly; I fell into a defeatist, closed-minded mindset, and actively refused to read because it was never something I thought I could get good at. Fast forward to my previous semester at university, I had the option to fulfill my writing requirement with an easy class I wouldn’t really care about. I gave myself a chance, and reluctantly signed up for a discussion-based reading and writing class. I’m so happy I did. It was my favorite class this semester! As much as I love computers, this class was a breath of fresh air. I especially enjoyed reading Dante’s The Inferno. I will definitely be checking out the sequels Purgatorio and Paradiso. My goal by the end of this year is to start reading for pleasure more often.

I joined my favorite club

My hand-crafted Purdue Hackers passport

I joined the Purdue Hackers club! I frequently regular Hack Night, the club’s flagship weekly hacker festival, where people collaborate to create and engineer interesting technical projects. I have made crazy talented friends at Hack Night who continue to inspire and motivate me. I have many more positive thoughts, but I think Galactic Empire does full justice to the unique culture Purdue Hackers has spent years creating.

Your browser does not support the video tag.

Hazel rescued an abandoned industrial robot arm from the flooded swamps of Florida, brought it to Hack Night, and actually managed to get it working

And onwards

One thing I admire about one of my best friends Henry is his motivation to write in a personal journal. I’ve never felt the need to express myself privately, it’s not something I feel motivated to do. But writing in any form is cathartic, and I’ve found that expressing myself to others suddenly makes the process fun and exciting. I think that blogging is just a great way to share all the cool stuff I’ve been up to.

This post is quite different compared to the other technical write-ups on my blog. If it isn’t your cup of tea, throughout my last few months of inactivity, I did end up thinking of some new blogpost ideas, some of which I am currently working on.

The Rubik’s Cube is a Computer: My most ambitious project to date, where all my time has recently been put towards, and a collaboration with friends Henry and Asher. It will take many months or even a year for this to come out.
From NAND to AI: A detailed technical narrative of NAND.
GitHub’s Most Influential Controversies: I want to curate the most influential issues from here and analyze the role of drama in shaping policy.
Implanting a VSCode Rickroll: I exploited an oversight in a popular VSCode extension to implant a silly rickroll into VSCode. It would have otherwise been a small write-up, however in doing so I may have potentially uncovered a subtle vulnerability with private GitHub repositories. Unfortunately there hasn’t been much recent development, but if something happens I will definitely get around to publishing it.
A Timeline of Rust: If there is one thing more enjoyable than writing Rust, it’s reading Rust! I want to briefly look at its older design using real examples. I intend to remaster this excellent post.
Four Years, 30k Lines of Code, and Nothing to Show For It: If you happen to know me then you know what this is going to be about, and I would appreciate if you please don’t personally bring this up to me :(

So… stay tuned. There’s always more to come. Until next time!

Footnotes

I have considered saving ECE for my masters. I decided against it because I want to reserve it for something else CS related. ↩

Wasm-pack Optimization Flags you Never Knew About!

Sun, 25 Aug 2024 08:00:00 GMT

We’ve all known and loved Rust’s wasm-pack for generating WebAssembly packages. Did you know that it provides dozens of obscure optimization flags hiding in plain sight?

Let’s first take a look at the available optimization flags from wasm-pack’s documentation.

[package.metadata.wasm-pack.profile.dev]
# Should `wasm-opt` be used to further optimize the wasm binary generated after
# the Rust compiler has finished? Using `wasm-opt` can often further decrease
# binary size or do clever tricks that haven't made their way into LLVM yet.
#
# Configuration is set to `false` by default for the dev profile, but it can
# be set to an array of strings which are explicit arguments to pass to
# `wasm-opt`. For example `['-Os']` would optimize for size while `['-O4']`
# would execute very expensive optimizations passes
wasm-opt = ['-O']

For most people, -O4 is enough, case closed, but it is easy to overlook an important detail. wasm-opt isn’t a tool from Rust, but rather a Rust-facing wrapper around binaryen’s wasm-opt, the C++ toolchain infrastructure that actually does the meat of the work. You never could have known this if you were new to rustwasm, as it’s omitted from the documentation.

You have to dig through source to find the full list of binaryen’s wasm-opt optimization flags. Bizarrely, the only mention of the list in fine print is within this test file.

test/lit/help/wasm-opt.test

...
;; CHECK-NEXT: Optimization options:
;; CHECK-NEXT: ---------------------
;; CHECK-NEXT:
;; CHECK-NEXT:    -O                                           execute default optimization
;; CHECK-NEXT:                                                 passes (equivalent to -Os)
;; CHECK-NEXT:
;; CHECK-NEXT:    -O0                                          execute no optimization passes
;; CHECK-NEXT:
;; CHECK-NEXT:    -O1                                          execute -O1 optimization passes
;; CHECK-NEXT:                                                 (quick&useful opts, useful for
;; CHECK-NEXT:                                                 iteration builds)
;; CHECK-NEXT:
;; CHECK-NEXT:    -O2                                          execute -O2 optimization passes
;; CHECK-NEXT:                                                 (most opts, generally gets most
;; CHECK-NEXT:                                                 perf)
;; CHECK-NEXT:
;; CHECK-NEXT:    -O3                                          execute -O3 optimization passes
;; CHECK-NEXT:                                                 (spends potentially a lot of
;; CHECK-NEXT:                                                 time optimizing)
;; CHECK-NEXT:
;; CHECK-NEXT:    -O4                                          execute -O4 optimization passes
;; CHECK-NEXT:                                                 (also flatten the IR, which can
;; CHECK-NEXT:                                                 take a lot more time and memory,
;; CHECK-NEXT:                                                 but is useful on more nested /
;; CHECK-NEXT:                                                 complex / less-optimized input)
;; CHECK-NEXT:
;; CHECK-NEXT:    -Os                                          execute default optimization
;; CHECK-NEXT:                                                 passes, focusing on code size
;; CHECK-NEXT:
;; CHECK-NEXT:    -Oz                                          execute default optimization
;; CHECK-NEXT:                                                 passes, super-focusing on code
;; CHECK-NEXT:                                                 size
;; CHECK-NEXT:
;; CHECK-NEXT:   --optimize-level,-ol                          How much to focus on optimizing
;; CHECK-NEXT:                                                 code
;; CHECK-NEXT:
;; CHECK-NEXT:   --shrink-level,-s                             How much to focus on shrinking
;; CHECK-NEXT:                                                 code size
;; CHECK-NEXT:
;; CHECK-NEXT:   --debuginfo,-g                                Emit names section in wasm
;; CHECK-NEXT:                                                 binary (or full debuginfo in
;; CHECK-NEXT:                                                 wast)
;; CHECK-NEXT:
;; CHECK-NEXT:   --always-inline-max-function-size,-aimfs      Max size of functions that are
;; CHECK-NEXT:                                                 always inlined (default 2, which
;; CHECK-NEXT:                                                 is safe for use with -Os builds)
;; CHECK-NEXT:
;; CHECK-NEXT:   --flexible-inline-max-function-size,-fimfs    Max size of functions that are
;; CHECK-NEXT:                                                 inlined when lightweight (no
;; CHECK-NEXT:                                                 loops or function calls) when
;; CHECK-NEXT:                                                 optimizing aggressively for
;; CHECK-NEXT:                                                 speed (-O3). Default: 20
;; CHECK-NEXT:
;; CHECK-NEXT:   --one-caller-inline-max-function-size,-ocimfs Max size of functions that are
;; CHECK-NEXT:                                                 inlined when there is only one
;; CHECK-NEXT:                                                 caller (default -1, which means
;; CHECK-NEXT:                                                 all such functions are inlined)
;; CHECK-NEXT:
;; CHECK-NEXT:   --inline-functions-with-loops,-ifwl           Allow inlining functions with
;; CHECK-NEXT:                                                 loops
;; CHECK-NEXT:
;; CHECK-NEXT:   --partial-inlining-ifs,-pii                   Number of ifs allowed in partial
;; CHECK-NEXT:                                                 inlining (zero means partial
;; CHECK-NEXT:                                                 inlining is disabled) (default:
;; CHECK-NEXT:                                                 0)
;; CHECK-NEXT:
;; CHECK-NEXT:   --ignore-implicit-traps,-iit                  Optimize under the helpful
;; CHECK-NEXT:                                                 assumption that no surprising
;; CHECK-NEXT:                                                 traps occur (from load, div/mod,
;; CHECK-NEXT:                                                 etc.)
;; CHECK-NEXT:
;; CHECK-NEXT:   --traps-never-happen,-tnh                     Optimize under the helpful
;; CHECK-NEXT:                                                 assumption that no trap is
;; CHECK-NEXT:                                                 reached at runtime (from load,
;; CHECK-NEXT:                                                 div/mod, etc.)
;; CHECK-NEXT:
;; CHECK-NEXT:   --low-memory-unused,-lmu                      Optimize under the helpful
;; CHECK-NEXT:                                                 assumption that the low 1K of
;; CHECK-NEXT:                                                 memory is not used by the
;; CHECK-NEXT:                                                 application
;; CHECK-NEXT:
;; CHECK-NEXT:   --fast-math,-ffm                              Optimize floats without handling
;; CHECK-NEXT:                                                 corner cases of NaNs and
;; CHECK-NEXT:                                                 rounding
;; CHECK-NEXT:
;; CHECK-NEXT:   --zero-filled-memory,-uim                     Assume that an imported memory
;; CHECK-NEXT:                                                 will be zero-initialized
...

Shrouded within the codebase, these few extra flags are actually useful in extreme optimization cases. Namely, in my case, --flexible-inline-max-function-size boasts a respectful 40% speed improvement while increasing my WebAssembly file size from 67KB to 83KB.

Cargo.toml

...
[package.metadata.wasm-pack.profile.release]
wasm-opt = [
    "-O4",
    "--flexible-inline-max-function-size",
    "4294967295",
]
...

These are just the “Optimization options”. There exists an even larger list of around 150 “Optimization passes” within the same test file.

...
;; CHECK-NEXT: Optimization passes:
;; CHECK-NEXT: --------------------
;; CHECK-NEXT:
;; CHECK-NEXT:   --abstract-type-refining                      refine and merge abstract
;; CHECK-NEXT:                                                 (never-created) types
;; CHECK-NEXT:
;; CHECK-NEXT:   --alignment-lowering                          lower unaligned loads and stores
;; CHECK-NEXT:                                                 to smaller aligned ones
;; CHECK-NEXT:
;; CHECK-NEXT:   --asyncify                                    async/await style transform,
;; CHECK-NEXT:                                                 allowing pausing and resuming
;; CHECK-NEXT:
;; CHECK-NEXT:   --avoid-reinterprets                          Tries to avoid reinterpret
;; CHECK-NEXT:                                                 operations via more loads
;; CHECK-NEXT:
;; CHECK-NEXT:   --cfp                                         propagate constant struct field
;; CHECK-NEXT:                                                 values
;; CHECK-NEXT:
;; CHECK-NEXT:   --coalesce-locals                             reduce # of locals by coalescing
;; CHECK-NEXT:
;; CHECK-NEXT:   --coalesce-locals-learning                    reduce # of locals by coalescing
;; CHECK-NEXT:                                                 and learning
;; CHECK-NEXT:
;; CHECK-NEXT:   --code-folding                                fold code, merging duplicates
;; CHECK-NEXT:
;; CHECK-NEXT:   --code-pushing                                push code forward, potentially
;; CHECK-NEXT:                                                 making it not always execute
;; CHECK-NEXT:
;; CHECK-NEXT:   --const-hoisting                              hoist repeated constants to a
;; CHECK-NEXT:                                                 local
;; CHECK-NEXT:
;; CHECK-NEXT:   --dae                                         removes arguments to calls in an
;; CHECK-NEXT:                                                 lto-like manner
...

I spent almost an entire day testing out the effectiveness of each flag to little avail. A lot of these flags aren’t even optimizations, and the ones that are were all seemingly ineffectual. If you’re looking to hyper-optimize your binaryen WebAssembly you’re better off sticking with the “Optimization options” flags. You may also find useful the optimizer cookbook and the GC optimization guidebook from binaryen’s wiki.

Coming to think about it, this post doesn’t have to be about wasm-pack at all, as the topic more closely concerns binaryen. I thought it was important to frame this post from a Rust point of view because of how surprisingly obscure this information is to wasm-pack users new to the WebAssembly pipeline. I have opened a pull request that explicitly references the full list of available wasm-opt flags in wasm-pack’s documentation to make them easier to find.

Until next time!

How Many Iconic Computing Numbers can you Recognize?

Fri, 23 Aug 2024 08:00:00 GMT

TL;DR: Here is the challenge https://numbers.arhan.sh/

Two years ago, I applied to college. I would be lying if I said it wasn’t a harrowing process, but like all other phases in life it passed.

During that time, one of my friends sent me a meme on Reddit about a list acronyms that only college applicants could understand. The author coined it as “the only place on the internet where you can say something like this and it makes total sense”. And you know what, they’re not wrong. The post reads like absolute nonsense to the ordinary person. Through a sense of shared adversity, students applying to college have created a digital subculture, and I found this concept fascinating to think about.

Reddit posts don’t usually deserve this much attention, but it inspired me to create something similar for computer nerds with my own creative twist. As programmers, we’re often told to avoid so called “magic numbers” for good reason, as they can make programs harder to understand. Let’s flip this idea on its head.

My close friend Adrian and I spent three weeks curating a secret message, a string of 31 iconic magic numbers in various fields of computing that only true programming hobbyists can decipher. If you think you’re into computers, I challenge you to fully decipher my secret message in under 40 guesses: https://numbers.arhan.sh/

On an unrelated note, this was my first time properly using Tailwindcss! I’m enamored by its simplicity, and love everything about it so far. Check out this project’s associated GitHub repository.

Comments about how many guesses and how long it took you to finish the challenge are welcomed and appreciated, have fun! Until next time!

Implementing === in JavaScript from Scratch

Sat, 17 Aug 2024 08:00:00 GMT

Yes, I know exactly what you’re thinking.

Reinventing the wheel? That’s the most moronic idea I’ve ever heard since that guy who wanted to invade Russia in the winter.

And you’re not wrong. For all practical purposes, this blog is pointless. What you’re about to read is so obscenely nutty that it only works on a legacy version of Chromium as an extension running millions of times slower.

The strict equality operator in JavaScript (===) compares two values for object equality. As you probably already know, this operator tests reference equality for non-primitive JavaScript values. In effect, because { foo: 42 } === { foo: 42 } is false, reimplementing spec-compliant functionality becomes much more interesting. I’m not talking about the obvious ways. Various other built-ins make object reference comparison trivial.

let obj1 = { foo: 42 };
let obj2 = obj1;

Object.is(obj1, obj2) && console.log("same");
[obj1].includes(obj2) && console.log("same");
switch (obj1) {
  case obj2:
    console.log("same");
}
new Set().add(obj1).has(obj2) && console.log("same");

We will implement this basic operation on a far lower level. But what does that mean, and how else could JavaScript differentiate two objects that hold the same data? Surface level research yields nothing, so we’re on our own. Let’s take a deep dive.

A few weeks ago I was looking into the Chromium DevTools heap profiler for a separate blog post of mine. I keenly noticed that the heap profiler distinguishes JavaScript objects by memory location. I might be able to utilize that to my advantage.

let obj1 = { foo: 42 };
let obj2 = { foo: 42 };

This isn’t useful if there isn’t a way to access these memory locations programmatically. Fortunately, Chrome uses the Chrome DevTools Protocol (CDP), a standardized JavaScript API that allows for direct inspection into the JavaScript runtime on Blink-based browsers.

The original question still stands; how does JavaScript access the CDP? The documentation endorses two means of access. First, open “devtools-on-devtools” and interface with the CDP like so.

let Main = await import('./devtools-frontend/front_end/entrypoints/main/main.js');
await Main.MainImpl.sendOverProtocol('Emulation.setDeviceMetricsOverride', {
  mobile: true,
  width: 412,
  height: 732,
  deviceScaleFactor: 2.625,
});

const data = await Main.MainImpl.sendOverProtocol("Page.captureScreenshot");

This requires explicit access to DevTools and some setup, meaning it wouldn’t work plainly on a website. The alternative option is the chrome.debugger API within a Chrome extension. Although this would be a bit harder to use, it was actually programmatic and eventually the option I chose to work with.

I hacked up a Chrome extension but was surprised when my testing errored with the following message.

{"code":-32601,"message":"'HeapProfiler.enable' wasn't found"}

What’s going on here? As it turns out, internal documentation reveals that specific protocol domains including the heap profiler are restricted for security reasons.

However, since the protocol is also exposed to chrome extensions through chrome.debugger API, the backend implements additional access control in some of the methods to prevent extensio[n]s form accessing file system or otherwise escaping the sandbox. These restrictions are not extended to other types of clients.

Here is the v8 commit that adds these restrictions, dating back to May 2022 and Chromium version v104. The solution to our dilemma, you guessed it, is time travel.

Google doesn’t distribute legacy versions of Chrome. We’ll have to be a bit more hands-on. Archives of older versions of Chrome exist online. However, I’m wary of downloading unknown files from the Internet. Instead, I installed the official v103 Chromium build from source following their guide. You may have to run /usr/bin/xattr -cr /Applications/Chromium.app on an ARM-based Macs to fix broken metadata preventing Chromium from launching.

My extension didn’t initially work because global content scripts were only supported in Chromium v111 and later, so I had to resort to an older content script hack to get it to work.

That was a lot; let’s take a small step back. To reiterate, the goal is to implement a spec-compliant strict equality operation in JavaScript from scratch. We’ve found a version of Chromium that enables programmatic access to the DevTools heap profiler. Let’s build the bridge between the CDP and JavaScript object memory addresses.

A good place to start is the HeapProfiler.takeHeapSnapshot method. This will profile the entire page, and is obviously cumbersome, but whatever. Next, the Runtime.evaluate method creates a unique object identifier from the evaluation result of a stringified JavaScript expression. The caveat is that this only evaluates the global scope, coercing some really bizarre JavaScript.

strictEquality.js

async function strictEquality(obj1, obj2) {
  window.__obj1 = obj1;
  window.__obj2 = obj2;
  // Communicate with the extension content script
  // and perform the strict equality (will be explained later)
  document.dispatchEvent(new CustomEvent("strictEquality"));
  let e = await new Promise((resolve) =>
    document.addEventListener("strictEqualityResponse", resolve, { once: true })
  );
  delete window.__obj1;
  delete window.__obj2;
  if (e.detail.length) {
    throw new Error(e.detail);
  } else {
    return e.detail;
  }
}

Ugh. It’s async not because of I/O, but because of the event loop. It’s also non-reentrant, in other words it must always be await-ed. These types of unavoidably stateful functions are typically only present within C, not JavaScript!

Fine. Finally, we can pass that identifier to HeapProfiler.getHeapObjectId and earn our heap profiler memory address value. The full pipeline:

background.js

...
await chrome.debugger.attach({ tabId }, "1.3");
await chrome.debugger.sendCommand({ tabId }, "HeapProfiler.takeHeapSnapshot");
let objDetails = await Promise.all([
  chrome.debugger.sendCommand({ tabId }, "Runtime.evaluate", {
    expression: "window.__obj1",
  }),
  chrome.debugger.sendCommand({ tabId }, "Runtime.evaluate", {
    expression: "window.__obj2",
  }),
]);
let objHeapDetails = await Promise.all([
  chrome.debugger.sendCommand({ tabId }, "HeapProfiler.getHeapObjectId", {
    objectId: objDetails[0].result.objectId,
  }),
  chrome.debugger.sendCommand({ tabId }, "HeapProfiler.getHeapObjectId", {
    objectId: objDetails[1].result.objectId,
  }),
]);
await chrome.debugger.detach({ tabId: sender.tab.filePath });

sendResponse(
  !(
    objHeapDetails[0].heapSnapshotObjectId -
    objHeapDetails[1].heapSnapshotObjectId
  )
);
...

We’re almost done! We now just need to handle important edge cases. Because primitive types aren’t usually stored on the heap and instead on the stack (with the exception of Symbols), Runtime.evaluate treats them differently. The method skips to the last step and directly returns their memcpy-able value.

// `Runtime.evaluate` on `{ foo: 42 }`
{
  "className": "Object",
  "description": "Object",
  "objectId": "...",
  "type": "object"
}

// `Runtime.evaluate` on `42`
{
  "description": "42",
  "type": "number",
  "value": 42
}

While comparing two primitives would be a simple equality operation, I wanted to stay true to my word and avoid its use entirely. Rather, we need to implement the isStrictlyEqual ecma262 subroutine at the high level like so.

background.js

...
function primitiveEquality(p1, p2) {
  if (p1.subtype) {
    p1.type = p1.subtype;
  }
  if (p2.subtype) {
    p2.type = p2.subtype;
  }
  if (!stringEquality(p1.type, p2.type)) {
    return false;
  }
  if (stringEquality(p1.type, "number")) {
    if (
      stringEquality(p1.description, "NaN") ||
      stringEquality(p2.description, "NaN")
    ) {
      return false;
    }
    if (
      (stringEquality(p1.description, "0") &&
        stringEquality(p2.description, "-0")) ||
      (stringEquality(p1.description, "-0") &&
        stringEquality(p2.description, "0"))
    ) {
      return true;
    }
    if (p1.unserializableValue || p2.unserializableValue) {
      return stringEquality(p1.description, p2.description);
    }
    return !(p1.value - p2.value);
  }
  if (stringEquality(p1.type, "null") || stringEquality(p1.type, "undefined")) {
    return true;
  }
  if (stringEquality(p1.type, "bigint")) {
    return stringEquality(p1.description, p2.description);
  }
  if (stringEquality(p1.type, "string")) {
    return stringEquality(p1.value, p2.value);
  }
  if (stringEquality(p1.type, "boolean")) {
    return !(p1.value - p2.value);
  }
  throw new Error("Unsupported primitive type");
}

function stringEquality(str1, str2) {
  if (str1.length - str2.length) {
    return false;
  }
  for (let i = 0; i < str1.length; i++) {
    if (str1.charCodeAt(i) - str2.charCodeAt(i)) {
      return false;
    }
  }
  return true;
}

And… there we go. The full implementation is provided in a GitHub repository. I coughed together an ugly test module to verify its correctness.

Did I forget to mention that it doesn’t work on page load because content scripts aren’t available globally? You’ll have to have fun awaiting the strictEqualityLoaded event before usage.

test.html

(async () => {
  await new Promise((resolve) => {
    document.addEventListener("strictEqualityLoaded", resolve, { once: true });
  });
  let significantValues = [
    0,
    -0,
    1,
    0n,
    Symbol(),
    Math.PI,
    Number.MAX_SAFE_INTEGER,
    Number.MIN_SAFE_INTEGER,
    Number.MAX_SAFE_INTEGER + 1,
    Number.MIN_SAFE_INTEGER - 1,
    Infinity,
    -Infinity,
    NaN,
    null,
    undefined,
    true,
    false,
    "",
    {},
    [],
    new Date(),
  ];

  for (let obj1 of significantValues) {
    for (let obj2 of significantValues) {
      let expected = obj1 === obj2;
      let actual = await strictEquality(obj1, obj2);
      if (actual !== expected) {
        throw new Error(`Failed for ${obj1} and ${obj2}`);
      }
    }
  }
  console.log("Passed!");
})();

Until next time!

DEF CON 32 Photo Dump

Tue, 13 Aug 2024 08:00:00 GMT

It’s that time of year again. I had the opportunity to attend DEF CON 32 at Las Vegas with my friends Adrian and Ruien, my CTF teammates. DEF CON is the world’s largest cybersecurity convention, and this was my second DEF CON event. The event lasted for four days, so we made sure to spend that time in its fullest.

This year, DEF CON moved to an entirely new venue. Feast your eyes on the Las Vegas Convention Center, one of the largest convention centers in the world.

This photo was taken at 0.5x zoom

As expected, we were greeted by this hacked sign. This was how we knew we were at the right place.

Someone gave me some cool swag xD.

We spent the entirety of our first day in LineCon. I’m not exaggerating. I waited in the merch line for seven hours straight.

Your browser does not support the video tag.

Anyways, this year’s DEF CON badge was a fully fleshed out entire RPG game made by a sole developer. More excitingly, DEF CON attendees were given exclusive access to the new RP2350 Raspberry PI MCU embedded within the badge.

The chip is the small black square at the bottom center

I tried to hack it, but eventually gave up because the tooling for such a new technology was virtually nonexistent.

Me trying and failing to install pico-sdk

The second day, we played a mini CTF called 5n4ck3y.

You don't get to say every day that you managed to brick a vending machine

And won a cool DOOM gameboy.

Yes, I did remove the plastic wrapper later

The day after that, we spent the entire afternoon playing our first attack and defense CTF. We managed to somehow win the first round by being quick, but placed third in the second round. Neither of us really knew what we were doing. We played blue team pretty much the entire time, changing passwords and rebooting attacked systems. Still, it was a cool learning experience.

We met a friend on our team as well.

Finally, on our last day, I visited some DEF CON villages and tried my hand at soldering and lock picking. I also got the chance to talk with other students from Purdue. Exciting stuff!

Of course, as my last remark, we can’t leave out our friend group shenanigans at the hotel.

Your browser does not support the video tag.

This year’s DEF CON was awesome! Until next time!

True Private State in JavaScript: a Chromium Rabbit Hole

Sun, 11 Aug 2024 08:00:00 GMT

What is “true” private state?
True private state in JavaScript
True private state in DevTools
True private state in DevTools: the extension way
Closing thoughts

What is “true” private state?

One of the first programming concepts you learn is the private variable, and the notion of encapsulation. These are fundamental concepts of object-oriented programming, a paradigm that emphasizes data structures, message passing, and abstraction.

For no reason at all, we’re going to casually set aside the intended theory, and take the term “private variable” (or “private state”) literally.

What do I think true private state should actually mean? For a class definition in a given programming language:

There must not exist a way to directly access a private variable’s value given an instance of the class.
There must exist exactly one indirect way to access a private variable’s value given an instance of the class.
The first step of the private variable access must be performed from within the language (no CheatEngine/GDB).
The class implementation’s source cannot be modified by the private variable access (to counter archaic solutions similar to this)
The class implementation must not use cryptography or network programming.

Direct access refers to code that aliases into a private variable’s value, for example by property accessor syntax such as rectangle.length or direct memory access. Indirect access refers to code that evaluates to a private variable’s value, but doesn’t actually alias into it in the same manner. While the expression rectangle.getLength() retrieves the private variable’s value, the expression alone doesn’t alias into it.

My definitions inherently make the meaning of indirect access subjective. After all, these concepts and ideas are based on high-level programming abstractions. The processor sees every operation as just reading and writing to memory, thereby voiding the concept of indirect access at the low level. Hopefully, the following examples and the rest of the post will help draw the line between what qualifies access as “direct” or “indirect”.

These five implementation requirements will be the key criteria in assessing whether or not a class implementation provides true private state. Generalizing them across many popular programming languages unmasks true identity of the term “private variable”… as a shameless misnomer!

Let’s first look at Java, a language whose primary purpose is to provide strong encapsulation boundaries. So, implementing true private state seems like it would simple enough, right?

public class Secret {
  private Object secret;

  public Secret(Object secret) {
    this.secret = secret;
  }

  public Object get() {
    return secret;
  }
}

Red buzzer. It’s easy to hijack private fields using Java’s reflection services, breaking the requirement of no direct memory access for true private state.

import java.lang.reflect.Field;

public class Main {
  public static void main(String[] args) throws NoSuchFieldException, IllegalAccessException {
    Secret secret = new Secret(Character.toString(65).repeat(10));
    Field secretField = secret.getClass().getDeclaredField("secret");
    secretField.setAccessible(true);
    System.out.println(secretField.get(secret));
    // Output: AAAAAAAAAA
  }
}

You may point out that reflection can be disabled with the -Djava.security.manager flag. But because this flag is opt-in, it doesn’t matter; recall that there must not exist a way of direct access into a private variable. Even then, you could alternatively use Java’s Native Interface API as demonstrated here.

Looking at something else, Python barely even tries!

class Secret:
  def __init__(self, secret):
    self.__secret = secret

  def get(self):
    return self.__secret

secret = Secret(chr(65) * 10)
print(secret._Secret__secret)
# Output: AAAAAAAAAA

Such is the case with C++, C#, Ruby, and so on — there’s always a way to alias into private fields in such a way that breaks the requirements for true private state, most namely through foreign function interfaces.

I want to make clear that I understand that these escape hatches are the results of intentional and thought-out design efforts. If you discount cryptography and network programming and really think about it, private state in modern object-oriented programming is by obscurity. The general philosophy is to present a massive “Here be dragons” warning when people decide to access the internals of an object anyways, typically through discomfort and community disapproval.

In the Python example, _Secret__secret is intimidating enough to discourage its usage, actively making the programmer feel bad. Endowing the programmer with full access to the internals of an object is OK, because it is assumed that they understand the consequences of depending on undocumented and volatile class APIs.

True private state in JavaScript

In regards to true private state, what does JavaScript offer?

class Secret {
  #secret;

  constructor(secret) {
    this.#secret = secret;
  }

  get() {
    return this.#secret;
  }
}

let secret = new Secret(String.fromCharCode(65).repeat(10));
console.log(secret.get());
// Output: AAAAAAAAAA

Believe it or not, for how historically chaotically-evil JavaScript has proven itself as a language, this is our silly little answer. True private state! The proposal for private JavaScript class fields guarantees their soundness:

Private fields provide a strong encapsulation boundary: It’s impossible to access the private field from outside of the class, unless there is some explicit code to expose it (for example, providing a getter).

If this is it, what was the deal with the mumbo jumbo at the beginning? Well, you can see from the remaining length of this blog post that there’s far more to the story than just JavaScript private fields. Our treasure lands on another island; I’m going to introduce a seemingly arbitrary liberation to the challenge: Chromium DevTools. What you see when you “inspect element” a web page. As I will soon demonstrate, this environment enables a myriad of backdoors that make true private state far more interesting.

True private state in DevTools

Something is already wrong right off the bat. Some research unveils this documentation.

Code run in the Chrome console can access private properties outside the class. This is a DevTools-only relaxation of the JavaScript syntax restriction.

Okay, we just need to try a little harder.

var Secret = (() => {
  // The difference between WeakMap
  // and Map isn't relevant
  let _secrets = new WeakMap();
  return class Secret {
    constructor(secret) {
      _secrets.set(this, secret);
    }
    get() {
      return _secrets.get(this);
    }
  };
})();

let secret = new Secret(String.fromCharCode(65).repeat(10));
console.log(secret.get());
// Output: AAAAAAAAAA

This approach is widely used as a polyfill for private JavaScript class fields, by Babel for instance. There’s seemingly no way for external code to access the closure variable _secrets, is this true private state? Unfortunately, no. DevTools reveals the first trick of many up its sleeve.

Recall my definition of direct access as “aliasing into a private variable’s value”. This is evidently what’s happening, thus discrediting closure variables as a solution, perhaps our biggest weapon so far. The DevTools scope inspector gives you access to practically every internal variable within a class. To put the nail in the coffin, I developed a way to programmatically access closure variables within DevTools, and exactly how is a story for another blog.

let secret = new Secret(String.fromCharCode(65).repeat(10));
await scopeInspect("secret");
// {value: 'AAAAAAAAAA'}

Hm, let’s see if we can exploit the dynamic nature of the eval function. Directly calling eval still reveals closure variables to the scope inspector. Could we instead use a reference to eval to conditionally capture closure variables?

class Secret {
  constructor(secret) {
    this.get = () => window["ev" + "al"]("sec" + "ret");
  }
}

let secret = new Secret(String.fromCharCode(65).repeat(10));
console.log(secret.get());
// Output: AAAAAAAAAA (?)

Considering that complete static analysis for a program has been proven to be undecidable, window["ev" + "al"] can only be evaluated at runtime. In theory, the scope inspector wouldn’t know to capture closure variables until the eval in the getter function is called.

As it turns out, the V8 engine is one step ahead of us. The above code throws a ReferenceError because smarter people than me have already thought of ways to compensate for this issue. eval captures local scope only when directly called and captures global scope otherwise, bringing us back to square one.

At this point I realized that what I was trying to achieve was going to be much more difficult than expected. A day of tinkering later, I stumbled upon this solution.

class Secret {
  constructor(secret) {
    console.warn("`Secret` may not properly serialize complex JavaScript values");
    this.get = Function(`return JSON.parse('${JSON.stringify(secret)}')`)
      .bind()
      .bind();
  }
}

let secret = new Secret(String.fromCharCode(65).repeat(10));
console.log(secret.get());
// Output: AAAAAAAAAA

To my credit, this was a surprisingly witty solution. It avoided the use of closures and utilized the Function constructor to hide the secret. Calling valueOf or toString on a function normally reveals its source code, however postfixing two .bind()s tricks DevTools into revealing function () { [native code] } instead.

It’s a shame that my friend Adrian debunked my findings two days later.

Pivoting once again, does DevTools reveal WebAssembly memory? If not, we could interface with it to our advantage.

Yes, it does as a form of direct memory access.

Now, our first real breakthrough!

class Secret {
  constructor(secret) {
    this.init(secret);
  }

  init(secret) {
    this.secret = new Promise((resolve) => {
      this.updateState = resolve;
    }).then(this.init.bind(this, secret));
    return secret;
  }
}

let secret = new Secret(String.fromCharCode(65).repeat(10));
secret.updateState(), console.log(await secret.secret);
// Output: AAAAAAAAAA

This is similar to the closure solution except unlike the eval solution, we’ve actually tricked DevTools. For brevity I won’t show an image, but this time secret is hidden from the scope inspector. Binding this.updateState directly to resolve relinquishes its need to display secret because the binding doesn’t canonically create a closure. Simply calling the resolver and awaiting the promise gives back the original value!

In a cruel twist of fate, this solution happens to be invalid because of the DevTools heap profiler.

The heap profiler exposes variables from web workers and popups as well

However, that doesn’t mean there isn’t more to the story. I was missing the bigger, more abstract picture. JavaScript is inherently a garbage collected language. Logically speaking, it’s impossible to remove all references to a secret variable or else it would become garbage collected. I mean, duh, but saying this out loud made me realize I needed to completely reapproach my strategy.

True private state in DevTools: the extension way

You could argue I’m pushing the limits of the DevTools environment, but I like to think of this as thinking outside the box. Chrome extensions provide a secure sandboxing environment to uphold their security guarantees. We can use this to our advantage.

Here is an implementation of private state in JavaScript that satisfies all five of my requirements. It utilizes IndexedDB on a Chrome extension background script to store secret variables in an isolated execution context (the chrome.storage API works too).

You’ve seen enough code blocks so far, so as to not ruin your patience I’ve taken the liberty of hiding the code implementation in a dropdown.

The code

manifest.json

{
  "name": "Secret",
  "description": "An extension that provides private state within DevTools",
  "version": "0.1",
  "manifest_version": 3,
  "host_permissions": ["http://*/*", "https://*/*"],
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["contentScript.js"]
    },
    {
      "matches": ["<all_urls>"],
      "js": ["secret.js"],
      "world": "MAIN"
    }
  ]
}

secret.js

class Secret {
  static secretId = 0;

  constructor(secret) {
    this.secretId = Secret.secretId++;
    document.dispatchEvent(
      new CustomEvent("set", { detail: { secret, secretId: this.secretId } })
    );
  }

  async get() {
    document.dispatchEvent(new CustomEvent("get", { detail: this.secretId }));
    return await new Promise((resolve) => {
      document.addEventListener(
        "getResponse",
        (e) => {
          resolve(e.detail);
        },
        { once: true }
      );
    });
  }
}

contentScript.js

document.addEventListener("set", function ({ detail: { secret, secretId } }) {
  chrome.runtime.sendMessage({ type: "set", secret, secretId }, () => {
    document.dispatchEvent(new CustomEvent("setResponse"));
  });
});

document.addEventListener("get", function ({ detail: secretId }) {
  chrome.runtime.sendMessage({ type: "get", secretId }, (secret) => {
    document.dispatchEvent(new CustomEvent("getResponse", { detail: secret }));
  });
});

background.js

const DB_NAME = "SecretsDB";
const DB_VERSION = 1;
const OBJECT_STORE_NAME = "secrets";

chrome.runtime.onMessage.addListener(function (
  message,
  { documentId },
  sendResponse
) {
  if (message.type === "set") {
    openDbStore("readwrite").then((store) => {
      store.get(documentId).onsuccess = (e) => {
        let data = e.target.result || { documentId, secrets: {} };
        data.secrets[message.secretId] = message.secret;
        store.put(data).onsuccess = sendResponse;
      };
    });
    return true;
  } else if (message.type === "get") {
    openDbStore("readonly").then((store) => {
      store.get(documentId).onsuccess = (e) => {
        let data = e.target.result;
        sendResponse(data?.secrets[message.secretId]);
      };
    });
    return true;
  }
});

async function openDbStore(mode) {
  let request = indexedDB.open(DB_NAME, DB_VERSION);
  request.onupgradeneeded = function (e) {
    let db = e.target.result;
    db.createObjectStore(OBJECT_STORE_NAME, { keyPath: "documentId" });
  };
  let db = await new Promise((resolve) => {
    request.onsuccess = (e) => resolve(e.target.result);
  });
  let store = db
    .transaction(OBJECT_STORE_NAME, mode)
    .objectStore(OBJECT_STORE_NAME);
  return store;
}

Instantiate and retrieve the secret like so.

let secret = new Secret(String.fromCharCode(65).repeat(10));
console.log(await secret.get());
// Output: AAAAAAAAAA

We have our answer. There’s no way for code on the web page to “directly access” the background script’s IndexedDB. The secret can only be retrieved indirectly, through the get method.

I could just end off over here, but there’s one thing left to address. It’s still possible to access the secret within Chrome if you navigate to chrome://extensions, open the background script DevTools window, and run this.

await openDbStore("readonly").then(
  (store) =>
    new Promise((resolve) => {
      store.getAll().onsuccess = (e) => resolve(e.target.result);
    })
);

For no reason at all, let’s make this even more unnecessarily complicated. Utilizing the native application API, it’s possible to store the secret outside of Chrome entirely! I’ve documented my exact findings in this GitHub repository. Instead of providing the code’s source like before, I had some free time and thought it would be cool to diagram how it worked. Some eye candy:

Closing thoughts

It’s time to address the elephant in the room. The correct way to store a secret variable is to use cryptography or networking services.

First, cryptography. Take your pick. The WebAuthn large blob and credential management APIs use your operation system keychain to store credentials, with some obscure limitations. The browser.secureStorage API might become a reality soon. SubtleCrypto can be used with IndexedDB for cryptographically secure key management. Common password manager extensions use this method.

Networking is self-explanatory, and is what 99% websites do. Store the secret on the server, rather than risk the user meddling with its value.

So… was this blog basically pointless? Yes. I will accept criticism that my requirements for “true” private state are arbitrary. It’s worth pointing out however that these topics are relevant in related fields of cybersecurity, such as in hardware security.

Was this blog a waste of your time? Maybe. Hopefully you learned something about JavaScript or DevTools debugging or the theory behind object-oriented programming. If you didn’t then I don’t really care. Until next time!

My GitHub Repository has 100,000 Contributors

Mon, 01 Jul 2024 08:00:00 GMT

What?
The plan
The script
The mystery of U_kgDOAMbr8w
The mystery of MyWebsite
100,000 Contributors

What?

Your eyes don’t deceive you. You can check right now: my GitHub repository has 100,000 contributors. If you are on GitHub mobile, the number may not appear. You have to view this repository through GitHub’s web UI.

Before I explain the why and the how, we first need to go back to a few weeks ago. I was routinely moving around some configuration files, and I accidentally swapped my ~/.gitconfig file with that of my alternate account. When I pushed to one of my repositories, I was surprised to notice that my alt account was added as a contributor! Its rendered profile picture, username, and hyperlink — all neatly displayed under “Contributors”.

There’s a good chance you’ve already seen something similar to this; it isn’t hard or particularly new to fake a commit from another user. But my curiosity was sparked. In my mind, the next logical question to ask was: how many contributors could I fake? And thereafter: could I get to exactly 100,000 contributors? It would be a fireplace of ghosts, a bizarre pit stop of GitHub users.

(Before continuing, I would like to point out that users can sign their commits to cryptographically verify their identity, ineffectuating impersonation. Even then, impersonation is against GitHub’s Acceptable Use Policies. Please be wary.)

I wasn’t trying to make 100,000 commits faking a different user each time, so I did some research and found a more efficient way. If you add two new lines under a commit message, you can co-author users with their username and email address as shown.

~ % git commit -m "Refactor usability tests.
>
>
Co-authored-by: NAME <NAME@EXAMPLE.COM>
Co-authored-by: ANOTHER-NAME <ANOTHER-NAME@EXAMPLE.COM>"

And so on, with seemingly no co-author limit. Luckily for my case, each one is added as a contributor! Armed with this knowledge, I began to formulate a plan.

The plan

Manually adding this many users to a commit message obviously isn’t practical. I needed to write an API scraper, and a quick check of GitHub’s policies affirms I’m allowed to do this provided that I’m not excessive.

We do allow the use of automated tools so long as they do not produce excessive amounts of traffic. For example, running one nmap scan against one host is allowed, but sending 65,000 requests in two minutes using Burp Suite Intruder is excessive.

So, I got to brainstorming. The most important conceptual hurdle was figuring out how to get a user’s email address, as you can’t co-author a user without it. The problem was, even if a user makes their email address address publicly visible on their profile, the GitHub API doesn’t reliably expose it¹. Surprisingly, there is a very well-known way to circumvent this and find almost anyone’s email address on GitHub.

Simply navigate to any commit authored by a user on GitHub and append .patch to the commit’s url. Et voilà! The second line from the top enclosed within angled brackets lies their email address, in full form and glory. It sounds concerning that this type of information is so easy to access, but if you think about it, emails are made public for a reason. Attribution and contact are pretty important from an open source perspective.

With these types of technical projects that work with big data, social conduct should be taken seriously. I don’t want to end up in a similar situation as this guy and piss off 100,000 people by publicly leaking their email addresses. So, I decided to only co-author private email addresses that are only valid within GitHub.

Admittedly, a small amount of real email addresses were committed at the beginning, but only for testing purposes. I believe that this amount is small enough to be insignificant and inconsequential.

How would I find 100,000 users? GitHub provides a Search API for querying for users, but this was problematic because it had a rate limit of… wait for it… 30 requests per hour. Ba dum, tss! Instead, I opted to use the API endpoint for followers to feed my scraper its users, which had a more reasonable rate limit I could work with.

Putting everything together, my API scraper will:

First use the Search API to find the most followed users on GitHub
Use the followers API endpoint to loop through each user’s followers (In retrospect, another approach could be utilizing a web crawling algorithm)
Use the “hack” as described earlier to find each follower’s email address
Filter each email address for private email addresses and format the co-author message

Hopefully you can see that, through some intuitional ingenuity, the idea no longer sounds as Herculean a task as it seems.

The script

I decided to write the scraper in JavaScript so I could utilize octokit.js, an API wrapper that provides useful built-in functionality such as throttling and retrying. I also decided to use GitHub’s GraphQL API instead of their REST API because multiple GraphQL queries could be batched in a single request and other smaller efficiencies.

After hacking up a prototype, I tested my first commit.

In ironic fashion, because I sign my commits, the commit was labeled "Partially verified" in green

It works!

I would spend the next week polishing response edge cases and ironing out inefficiencies, before I was finally ready to run my scraper.

I didn’t feel like running it locally because I knew from testing it would take a long time. Instead I bought a DigitalOcean VM, imported my script, and ran it as a background process.

:~# git clone https://github.com/ArhanChaudhary/everyone
:~# cd everyone
:~/everyone# nohup node index.mjs --co-author-count=100000 > results.txt 2> log.txt &
[1] 104705

I think it’s worth mentioning how surprisingly lenient the GraphQL API rate limits are, given how notoriously restrictive the Rest API rate limits are. Even though my scraper was continuously and asynchronously parallelizing multiple batched queries at once, the highest I ever saw the GraphQL hourly rate limit quota reach was 1,500 out of 5,000 points.

Nine hours later, combing through approximately half a million GitHub users, my scraper yielded 100,000 co-authors, each ready to become a contributor. Hooray!

I’m so sorry if it feels like I’m cutting you off, but I first wanted to discuss a few API anomalies on the error log before we get to the committing. Trust me, what I’ve found is equally, if not more interesting.

The mystery of U_kgDOAMbr8w

Out of those half a million users, exactly two of them always crash the GraphQL API. That’s a 0.0004% fallthrough rate. Following some investigation, I was able to narrow down the crashing to any valid query containing the substring history(author: {id: "..."}), where the id parameter is either of their GraphQL user IDs. If you want to try yourself, execute this on the GitHub GraphQL explorer:

query {
  repository(owner: "torvalds", name: "linux") {
    defaultBranchRef {
      target {
        ... on Commit {
          history(author: {id: "U_kgDOAMbr8w"}) {
            totalCount
          }
        }
      }
    }
  }
}

It doesn’t matter which repository you specify, the results are the same.

I emailed both users to inquire about anything they might know about this issue. The second user responded, equally as puzzled as I was. After exchanging Discords, we spent a few hours discussing theories and possible security concerns, but despite our research we weren’t able to come to a conclusion. I ultimately ended up filing a bug report to GitHub support.

I would receive this response.

Hi Arhan,

Thanks for reaching out!

I was able to reproduce the error and it seems the bug is related to some odd author information associated with user accounts.

I have filed an internal issue with the engineering team to look into this bug. While I don’t have an ETA on a fix now, we appreciate you reaching out on how we can make things better.

…

The mystery of MyWebsite

Have you ever seen a corrupted repository?

I won't be revealing the author nor the link to respect their privacy

Well, it ended up crashing my script half way through. Having to re-run it was more annoying than it should have been.

It turns out you can still clone this repository. Inspecting the commit history presents something interesting.

Desktop % git clone https://github.com/.../MyWebsite.git
Desktop % cd MyWebsite
MyWebsite % git log -n 1
...
Date:   Fri Dec 2 10:14:22 3194 +25627400
...

From a prior CTF competition, I already knew that GitHub was perfectly fine with future commit dates. I wasn’t sure why this was happening, so I replicated this commit on a test repository.

Test % git commit --allow-empty -m "Testing"
Test % commit=$(git rev-parse HEAD)
Test % git cat-file commit $commit > commit.txt
Test % vim commit.txt # change both timestamps to 38654734462000 +25627400
Test % new_commit=$(git hash-object -t commit -w commit.txt)
Test % git update-ref refs/heads/main $new_commit
Test % git push

These commands only work on Git v2.38.2 or earlier, don’t ask me how I know that.

Sure enough, after pushing, my test repository also nuked itself in a similar fashion with the same error message. I was able to pinpoint this behavior to the invalid UTC offset on the commit date, a classic parsing oversight. I took this a step further and wanted to see what would happen if I opened a pull request referencing this commit. Feast your eyes on…

I really wish I could say I found a denial-of-service PoC and became $1,000 (or more) richer. Imagine how cool of a resolution that would sound! Like before, following triage with some of my friends, I surrendered empty-handed and filed a bug report to GitHub support.

I would receive this response two days later.

Hey Arhan,

Thanks for getting in touch and flagging this. I take it you’ve been exploring different ways to edit git commits manually and exploring how they behave on GitHub? :)

We’re not able to gracefully handle every possible sort of malformed/corrupted commit that might occur, as much as we’d like to.

Given the extensive steps required to achieve this outcome, it’s unlikely this would be encountered as part of regular work when collaborating on GitHub. Because of this, it’s unlikely that if I raised this with one of our engineering teams that it’d be picked up to be worked on/improved.

I hope you can understand why we’re not always able to work on all bug reports we receive, but if you identify a way this occurs as part of regular activity, please write back and let us know - we’d be happy to investigate further.

…

Understandable, but nevertheless interesting.

100,000 Contributors

Where were we? Oh right, apologies for the side-tangents, I tend to get distracted. Now that we have all of our co-authors, let’s get the party started!

everyone % scp root@147.182.243.54:everyone/results.txt .
everyone % echo -e "👀\n\n$(cat results.txt)" | git commit --allow-empty -F -
everyone % git push

…

Thirty minutes later, nothing happens.

…

Uh oh.

I’m just messing with you, it wasn’t that dramatic. After force git-resetting, simply splitting up the co-authors into commits of 5,000 at a time did the trick.

everyone.sh

#!/bin/bash

split -l 5000 -a 5 results.txt split_
FIRST_ITERATION=1

for i in split_*
do
    if [ $FIRST_ITERATION -eq 0 ]; then
        sleep 120
    fi
    FIRST_ITERATION=0
    echo -e "👀\n\n$(cat $i)" | git commit --allow-empty -F -
    git push
done

rm split_*
echo "Co-authors successfully processed!"

After running the script, around half an hour later:

The last 14 contributors are on the icons up top

Tada! *drops mic*

Not bad for my second blog, don’t you think? Until next time!

Footnotes

The situation here is strange. For reasons unknown, the GitHub GraphQL API straight up doesn’t expose the majority of users’ public emails… UNLESS you use the GitHub REST API; in which case only this method works… UNLESS you use the GitHub GraphQL explorer which seems to work with the same level of accuracy. I know I’m not going crazy. It’s really weird. ↩

Hello World

Sat, 04 May 2024 08:00:00 GMT

When I was younger, I never had the confidence to think of myself as an interesting guy, let alone a writer. But my high school and now collegiate friends have slowly made me more cognizant of the fact that, when it comes to my nerdy interests, I LOVE to talk, typically to an intolerable degree. A day of reckoning later, I asked myself: what if I start a blog?

I thought I would give a brief life update to honor my celebratory first blog post. I’ve just finished my first year as a Computer Science major at Purdue University! Over the past school year, I…

I coded, a lot. I showed off my hobby project NAND on Hacker News, and they really seamed to like it.

I got back into video gaming.

I learned to skateboard and cut my commute time by two-thirds.

And so much more!

At the time of writing, the path forwards remains mostly unclear. One thing is for certain — this is far from the last time you’ll hear from me >:)

Arhan's Blog

Bring Back the Paragraph

Native Instant Space Switching on MacOS

Footnotes

Memory-corrupting Pong

Footnotes

The Generativity Pattern in Rust

Table of Contents

Introduction

Background

Permutations

Permutation groups

The unsafe approach

The atomic ID approach

The generativity approach

The fundamental purpose

Why the implementation caveat?

How does generativity work?

min_generativity

The first part

The second part

The third part

Verifying soundness

Language support

Benchmarks

Conclusion

Footnotes

Turning Image Corruption into Art

An Image Compression Tip with Astro

Two Years of University

I ditched the skateboard

I uninstalled social media

I took interesting classes

I joined my favorite club

And onwards

Footnotes

Wasm-pack Optimization Flags you Never Knew About!

How Many Iconic Computing Numbers can you Recognize?

Implementing === in JavaScript from Scratch

DEF CON 32 Photo Dump

True Private State in JavaScript: a Chromium Rabbit Hole

Table of Contents

What is “true” private state?

True private state in JavaScript

True private state in DevTools

True private state in DevTools: the extension way

Closing thoughts

My GitHub Repository has 100,000 Contributors

Table of Contents

What?

The plan

The script

The mystery of U_kgDOAMbr8w

The mystery of MyWebsite

100,000 Contributors

Footnotes

Hello World

How does `generativity` work?

`min_generativity`