DEV Community: Mara Averick

The 2026 stdlib community survey is open

Mara Averick — Fri, 11 Sep 2026 13:30:13 +0000

We closed our last post, on a hundred interviews, by admitting that "a project's confidence about its users and a project's evidence about its users may be close to unrelated quantities"—so rather than keep guessing, we're asking. The 2026 stdlib community survey is now open.

stdlib is a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computation, and this survey is part of a National Science Foundation award supporting a sustainable scientific computing ecosystem on the web.

What would have to be true—or visible—for you to reach for an existing numerical routine in JavaScript, instead of writing it yourself or leaving for another language?

So we're asking how you decide if you can trust the numbers a library gives you, whether you've ever had numerical code return an answer that looked plausible and turned out to be wrong, what you did the last time you needed a numerical routine and couldn't find one, and how you check numerical code an AI assistant wrote for you. Short answers are fine, and "I don't know" is real data.

You don't need to have used stdlib to answer. If you've never heard of it, you're exactly the person we're missing. If you tried numerical work in JavaScript and gave up on it, you're the person we can least afford not to hear from. And if you build or maintain numerical libraries and tools of your own, answer as a builder, not only as a user.

We kept it short on purpose. Five to ten minutes; all but the first question are optional.

Your answers help shape what we build and document next. We won't publish anything that identifies you, and we won't quote you without asking first. The last question asks for an email address only if you're open to a follow-up conversation—it's optional, we'll use it only to contact you about this work, and leaving it blank changes nothing else.

This isn't a signup for anything. It ends when you submit it.

Take the survey.

Mara Averick is a developer advocate at Quansight and contributor experience lead for stdlib.

stdlib is an open source software project dedicated to providing a comprehensive suite of robust, high-performance libraries to accelerate your project's development and give you peace of mind knowing that you're depending on expertly crafted, high-quality software.

If you've enjoyed this post, give us a star 🌟 on GitHub and consider supporting the project. Your contributions and continued support help ensure the project's long-term success and are greatly appreciated!

Acknowledgments

This work was supported in part by the National Science Foundation under Award No. 2449410.

Disclaimer: Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

Lessons learned: 100 interviews about numerical JavaScript

Mara Averick — Thu, 03 Sep 2026 13:09:31 +0000

We ran a hundred customer-discovery interviews in seven weeks earlier this year, reaching out to anyone we could think of who might have something to say about high-performance numerical and scientific computation in JavaScript (which is the thing stdlib exists to do), as well as those with knowledge about sustaining open-source ecosystems. We also searched the Journal of Open Source Software (JOSS) for work involving JavaScript—a remarkably short list—and wrote to the people behind the papers.

So, the sample is what two people's address books could reach, plus what one literature search could find. Our networks largely held people we already knew, which shaped the corpus.

Projects overestimate how well they know their users. It's in the corpus over and over—maintainers confident about what users need, users describing something adjacent but not the same when you ask them directly with no maintainer in the room. Which is not a maintainer failing, or a developer failing. Expertise and certainty aren't correlated the way we'd like them to be, and Tavris and Aronson have the bleak version of it in Mistakes Were Made (But Not by Me): "training does not increase accuracy; it increases people's confidence in their accuracy."¹ That's also how a wrong assumption persists—nothing in the loop is set up to catch it, so it just keeps being the thing everyone knows. We ran the interviews, found the pattern, and still catch ourselves in it.

What we did, and what the numbers can't say

The interviews were the "customer-discovery requirement" of the NSF I-Corps program, which stdlib went through as part of its POSE award. The count (100) and the timeline (seven weeks) came with it. Two of us doing them.

Recruiting a hundred people that fast doesn't leave much room for a sampling strategy, and two of our three channels were just us. My side of that reach was R and data visualization; Athan's was scientific Python and numerical JavaScript.

The third channel wasn't a network. To find academics actually using JavaScript in a lab, we used a mix of GitHub repo surveying and JOSS as an index—papers citing JavaScript—and cold-emailed the authors we found that way. Most had no idea who either of us were, but were generous enough to give us their time.

The interviews were also confidential, which is a routine research condition rather than a dramatic one. A brief survey runs alongside this, because the gap in the corpus is a specific gap and the people who could close it are, by definition, not in it.

Four major themes

1. The ecosystem doesn't answer is this right

People arriving at JavaScript from R or Python don't say I can't do the thing I want to do in this language. They say I can't tell whether this is right. The problem they're describing isn't capability, it's epistemic: there's no obvious mechanism in the JavaScript ecosystem for distinguishing a numerically sound implementation from one that merely runs and returns a number of roughly the right magnitude.²

Several people named this before we'd asked anything about stdlib, which is what makes it their framing rather than ours. The named counterexample, repeatedly, was CRAN—the Comprehensive R Archive Network that runs checks before a package is listed, and where the listing itself carries information.³ In the eyes of those used to the CRAN model, npm (the predominant package manager for Node.js) appears to be an open field of sorts. Things grow in it. Nobody inspects them.

So people reach for the proxies that exist. Stars. Weekly installs. Download counts. At least one person described using install counts as a quality signal while being entirely clear-eyed that it isn't one, because no signal of statistical validity is on offer and something has to bear the load. Popularity is what you use when correctness isn't measurable from the outside.

A large share of the people opening pull requests against stdlib aren't using it in their own work—filling in the ecosystem canvas is where we had to write that down.⁴ And the actual grounds for trusting the library are the reference implementations the tests check against, the fixtures generated from them, the benchmarks. All of it stays invisible to the people standing closest to it. Those grounds are inspectable, which is what open source has instead of trust us; being able to read the source is how trust here gets earned rather than granted. Reading it is also a cost, unevenly payable, which is most of what documentation conventions exist to lower. What people have in the meantime is what they've been able to watch: how a maintainer handles a bug report, what a review looks like, behavior over time. That's real evidence and it's rational to use. It just isn't transferable—you can't hand it to your team lead, and sooner or later you'll be asked to.

A project looking at its own trusting users is looking at the wrong evidence. What it sees is people relying on it. What it tends to read that as is our quality is legible from the outside. What it's often actually seeing is the people who got close enough to watch it work. And the people for whom the quality wasn't legible didn't file an issue saying so—they used something else, or went back to R, and the project never saw them at all.

More than one person described building a small solo tool that achieved unexpectedly large downstream use with essentially no feedback reaching them. That's silent adoption, and stars and downloads can't detect it at all—they count use, not whether any of it ever gets back to the person who built the thing.

Trust us, we're careful asks for exactly the thing the finding says is unavailable. It also misplaces the work: robustness and reliability aren't a claim you make about the product, they're a key part of the product. So the job isn't to ask anyone for trust—it's to show that what we do lines up with the things they already trust.

stdlib already has the material for that, built deliberately and for engineering reasons—to know the implementations are correct—rather than to demonstrate anything to anyone. The expected values in the special-function test fixtures aren't hand-written, and they aren't captured from stdlib's own output—they're generated by external reference implementations and committed next to the tests with the generator script included. Close to two hundred packages check against Julia; the rest mostly against NumPy and SciPy, Boost.Math, and R.⁵ You don't have to believe us about any of that. You can check that we match what you'd have used anyway.

2. AI is the densest theme, and it doesn't converge

Roughly thirty of the interviews touch AI-assisted contribution.

We went in with a prior, and the prior was wrong. We expected sentiment to sort by seniority—junior contributors enthusiastic, senior maintainers alarmed, some tidy generational story. It doesn't. Senior maintainers of substantial projects show up alarmed and enthusiastic in roughly equal measure, and neither that story nor its inverse holds.

Across people who disagree about everything else here there was one near-universal claim: AI has lowered the cost of submitting a contribution much further than it's lowered the cost of evaluating one. That asymmetry is the one thing nearly everyone sees. What they profoundly disagree about is whether it's a crisis, a nuisance to route around, or a net win.

Three registers are clear in the corpus, and they're different arguments:

There's alarm about quality—volume up, signal down, review time is finite.
There's alarm reframed as security, which is a different claim entirely: a contribution pipeline without process isn't just noisy, it's a risk surface, and treating it as a code-quality problem understates it.
And there's a rarer fatalist register that doesn't really argue—the technology arrived, it's here, and whether it should be isn't a live question.

A project's posture with respect to newcomers, described in Do you WANT contributors?, is a separate matter from the register in which it lands.

There may be a fourth: that code review was never only quality control, it was how a project handed its judgment to a new person, and something that produces acceptable diffs without that exchange has broken the part that mattered even when the diff is fine.

Two positions invert the dominant frame entirely. One imagines AI as the filter—the triage layer that protects a maintainer's attention rather than the flood that overwhelms it. The other argues that a project should deliberately optimize its own legibility to models as a discoverability strategy, on the reasoning that training cutoffs are why newer libraries are structurally invisible to the tool an increasing number of people ask first.

Sentiment may sort instead by which side of the submit/review transaction someone spends their day on; that hasn't been checked against every interview that touches AI (and may have legitimately changed over the subsequent months).

3. Who showed up, and what they came from

Twenty-six of the hundred people we interviewed had contributed to stdlib. Seventy-four hadn't. That split matters because it means this isn't contributors imagining what users want. It's users, or prospective users.

Within it, one relationship is about as strong as a hundred conversations can show: whether someone has contributed to stdlib predicts what language they compute in. The contributor group is JavaScript- and C/C++-native at roughly three-quarters. Not one of the twenty-six contributors arrives primarily from Python. Exactly one arrives primarily from R, and that applied-statistics-to-Node path is the origin story of stdlib's own precursor project—which isn't evidence that R people find their way to stdlib, it's evidence that one of them founded it. Meanwhile, half the non-contributor group is Python- or R-primary.

Both groups came out of the same biased pool, which is what makes the comparison usable. Whatever our networks did to the absolute numbers, they did to both columns—so the difference between them survives the sampling problem even though neither column on its own does.

Two negative findings sat alongside it, and we predicted neither. MATLAB is primary for nobody. Two people name it as a language they left. Julia is primary for nobody either, showing up only as a reference implementation people consult when they want to check what a correct answer looks like. Both of those were carrying weight in our persona assumptions, and neither earned it.

The obvious story to tell here is that stdlib's written material addresses JavaScript developers, its talks address scientists arriving from Python and R, and the contributor population is what happened. The data is consistent with that. It doesn't establish it, and there's a sufficient alternative explanation sitting right there: seventeen of the twenty-six contributors arrived by way of Google Summer of Code (GSoC)—some in the program, others contributing in the hope of getting into it—and either way the sorting is by project.

4. The most valuable parts don't scale

Ask people what made their contributor experience valuable and the same answer comes back again and again: a specific human paid individualized attention to them. Eighteen interviews say so, which makes it consistent rather than dominant—onboarding generally turns up in roughly twice as many. The Stakeholder Journey is its own subject; among the maintainers and program managers here who took the question up, it was near-unanimous that individualized attention doesn't scale, and nobody claimed to have solved it. That's a real tradeoff, not a tooling gap. Three things came up reliably about why.

First, the good-first-issue pipeline isn't the solved problem it looks like from outside: one large project reports that its organic supply of genuine beginner-appropriate issues ran out, and that beginner tasks now have to be manufactured. That complicates any assumption that onboarding gets easier as a project matures.

Second, mentorship labor includes a category that no onboarding framing counts. Sustaining the motivation of a contributor who has lost interest isn't review and it isn't documentation, and it doesn't appear on any dashboard. It's emotional work, and the one person who named it described it as the biggest stumbling block they had.

Third, an actively evolving codebase imposes a contributor cost that maintainers don't always register. Conventions shift; the shift is rarely documented as a shift. This showed up independently from more than one contributor inside the same project, which is about as clean a demonstration of the visibility asymmetry as we got.

Onboarding and mentorship read as big themes partly by construction. GSoC is a mentorship-heavy program, and it brought in a substantial part of the contributor group. The theme is real. Its rank is an artifact of who we talked to.

What we still can't answer

We don't know whether JavaScript developers actually have the ndarray comprehension gap we've assumed they have. Our own framing has been that people arriving from JavaScript need what is an ndarray explained while people arriving from Python need the subtleties. Half of that has evidence. On the other half, all hundred interviews say nothing at all—not a little, nothing. That could mean the people who bounced off it were never reachable by this recruitment channel, or it could mean it was a maintainer's assumption about users that we've been carrying as a fact. This corpus can't separate those.

There's a lot we didn't reliably ask. Which programming language someone had come from is one instance: twelve of the hundred can't be classified on the axis that produced one of our strongest findings. Migration friction is another: it came up as the two-language problem—one language, namely Python or R, for analysis, and JavaScript for visualization—not in a form we could count.

And then there's a limit on the whole corpus that no amount of re-reading fixes, and this one isn't about our sample: it's about what asking does. Nobody was hiding anything—people said plainly when they weren't sure, and more than one of them worked out mid-conversation that shorthand was all they had. That's the thing. A question hands you a slot shaped like a position, and what's available to fill it is shorthand, because that's what anybody can actually retrieve about a choice like this.

The summary here runs the operation a second time. A hundred conversations became four themes, and a theme is a position that's been made comparable to other positions—which is why it can be summarized, and it's paid for out of exactly the particularity that made any one answer worth having. So the sections above are the shape of what a hundred people say when they're asked. That's a real thing to know. It isn't the shape of what they know.

A project's confidence about its users and a project's evidence about its users may be close to unrelated quantities. Trust is where that gap opens widest. The trust a project can see is the trust it earned in view of people close enough to watch, and everyone else's assessment happens somewhere the project can't reliably see. The distrust never shows up at all—it looks like somebody quietly using something else.

There's a short survey (11 questions). If the language you compute in, your discipline, or your path to numerical computing on the web isn't represented above, that's the hole.

Mara Averick is a developer advocate at Quansight and contributor experience lead for stdlib.

Acknowledgments

This work was supported in part by the National Science Foundation under Award No. 2449410.

Disclaimer: Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

Carol Tavris and Elliot Aronson. Mistakes Were Made (But Not by Me): Why We Justify Foolish Beliefs, Bad Decisions, and Hurtful Acts. Third edition, Houghton Mifflin Harcourt, 2020, chapter 5, "Law and Disorder." ISBN 978-0-358-32961-9. ↩
Of course, as with all of open source, you could always read the source code. But, in practice, this is least likely to be helpful for those used to doing their numeric and scientific analysis in other languages. ↩
CRAN Repository Policy. https://cran.r-project.org/web/packages/policies.html. Packages must pass R CMD check on the maintained platforms before and after being listed, which is the mechanism the interviewees were reaching for—not the curation judgment, but the existence of any automated gate at all. ↩
"The Open-Source Ecosystem Canvas." https://blog.stdlib.io/open-source-ecosystem-canvas/. The Community Members cell records the phrase the canvas forced into the open—usually non-users—next to casual contributors. ↩
Counts of test/fixtures/<generator>/ directories under @stdlib/math/base/special, taken against the develop branch on 2026-08-26: Julia 198, Python 23, C++ 20, R 11, C 3, Wolfram 2. Each generator is a script calling an established library in that language, committed alongside the fixtures it produced. ↩

Write It Like C: What V8's Optimizing Compilers Explain About the Zen of stdlib

Mara Averick — Mon, 24 Aug 2026 14:15:34 +0000

JavaScript wasn't designed for numerical computing. There's one number type (a 64-bit float), no operator overloading, no control over memory layout, and a value model where every integer is, in principle, an object. And yet, on a modern V8, a tight loop over a Float64Array lands within a small constant factor of equivalent C—sometimes at basically the same speed. That's not an accident, and it's not free. It's the cumulative result of fifteen years of compiler engineering specifically aimed at recognizing, at runtime, that the dynamic-language source you wrote is in fact behaving like a statically-typed numerical kernel—and rewriting it as one.

If your first association with "V8" is horsepower and max towing capacity, the Zen of stdlib is going to read as an elegant list of design principles you're supposed to memorize. And it kind of is one—about two dozen entries. Some are about people (code is read more than it is written, be kind to your future self, tend to the garden), some are general engineering taste (don't be clever, complexity kills, simple is beautiful). Two are unmistakably about machines: write it like C, and avoid polymorphism by default, which the long form spells out as "monomorphic is best, polymorphic is not great, megamorphic is terrible." Those last three terms are counting how many different kinds of thing one spot in your code has had to handle: one, a handful, or more than the engine will keep track of.

What I didn't expect is how many of those middle entries are also about a machine. Don't be clever means something specific once you know what happens when you try to outsmart a speculative optimizer. Same with mistakes are infectious, fix them early, and stability is a feature. A lot of what looks like taste turns out to be doing real work.

I'm not a compiler engineer, I've never written a numerical kernel, and I don't write C. My job is making stdlib's conventions legible to people arriving at the codebase, and I couldn't explain half of these without knowing what V8 actually does with a loop—so I went and found out. The useful discovery, for anyone else who doesn't write C either: write it like C asks for less knowledge of C than you'd think. What it actually asks for is knowing what the optimizer is trying to prove. What follows is the map I wanted when I started, assembled from the V8 team's writing about their own pipeline and from asking stdlib maintainers why the code looks the way it does. You don't need to have gone spelunking inside V8 for it to make sense—I hadn't when I started.

The part that surprised me most: the rules have barely moved in a decade, while the machinery enforcing them has been rebuilt three or four times. That's why they're worth internalizing rather than looking up.

On other engines: this post is about V8. JavaScriptCore in Safari and SpiderMonkey in Firefox ship their own compiler architectures, and circle many of the same principles by different routes. V8 gets the attention here because it runs Chrome and it's the runtime under Node.js and Deno, so most stdlib code ends up executing on it. Where I could, I've stuck to general principles rather than V8-specific quirks, since those are the parts likely to travel.

A note on vocabulary

This post throws around terminology—hidden classes, shapes, inline caches, elements kinds, deoptimization—and uses some of it before explaining it. Don't worry—the explanations arrive later, where the terms are doing more work. If you'd rather have a running start, two pieces cover most of it:

Mathias Bynens — JavaScript engine fundamentals: Shapes and Inline Caches — hidden classes and inline caches, which is most of the vocabulary here; and
Mathias Bynens — Elements kinds in V8 — how V8 tracks what is inside an array.

Feeling a little out of your depth here is fine—I definitely did.

Why a numerical JavaScript lens?

Most V8-pipeline explainers target general-purpose JS frameworks, page-load metrics, or web-app responsiveness. The optimizations they highlight absolutely apply to numerical code—function inlining, hidden-class stability, megamorphic call sites all matter here. They just aren't the whole story for a Float64Array-bound inner loop.

Keep a loop like this one in mind:

function scale( x, out ) {
    for ( let i = 0; i < x.length; i++ ) {
        out[ i ] = x[ i ] * 2.0;
    }
}

Nothing about it is clever (which is the point). Assume x and out are Float64Arrays and that scale gets called thousands of times.

Four of the engine's questions matter much more for numerical work than they do for typical app code, and all four are about that loop. Each names something the optimizer is trying to prove, and each returns further down with the mechanism attached—so this is a map to come back to, not something to hold in your head now.

Boxing and unboxing. Does x[ i ] reach the multiply as a raw 64-bit float in a CPU register, or as a heap-allocated wrapper the engine reads through on every operation? Numerical code multiplies that difference by a million.
Elements kind. Is x's backing store (the memory the elements actually live in) a contiguous block of doubles, or a tagged array of generic JS values, where every slot has to carry its own type? V8 tracks this per array, and the loop reads through that store on every iteration.
Deoptimization. The optimizer bets that scale only ever sees Float64Array. What happens on the call that breaks the bet—when V8 has to throw the specialized code away? That bet gets tested constantly, because one kernel gets reused against different inputs all day long.
Tiering. V8 has four compilers rather than one, and they trade compile time against code quality. Does scale want the last cycle squeezed out of peak code, or to reach peak code fast enough that a Node service or notebook session spends most of its time there? That second case is the common one for numerical code.

Most of V8's recent architectural work comes back to one or another of these four: Sparkplug, Maglev, the Turboshaft intermediate representation (IR), mutable heap numbers.

A 15-year ladder

Today's V8 has four JavaScript execution tiers. It did not start there. Each addition responds to a specific gap left by the previous tier.

Crankshaft (2010–2017)

In December 2010, Google shipped Crankshaft, V8's first speculative optimizing compiler. Crankshaft was layered above V8's existing baseline compiler, Full-codegen: cold code ran there, and once a function got hot, V8 promoted it to Crankshaft for re-compilation against type assumptions. Crankshaft used two intermediate representations: a high-level static-single-assignment (SSA) graph called Hydrogen, and a lower-level form called Lithium. It leaned heavily on inline-cache feedback collected by the running baseline code.

Crankshaft is the V8 that stdlib-shaped JavaScript was first written against. Its rules still apply today—monomorphic call sites, stable hidden classes, no megamorphism, no surprise types. They were never about Crankshaft specifically; they described the underlying contract between dynamic source and a speculative optimizer. One of those terms is worth unpacking now: a hidden class is V8's internal record of an object's layout—which properties it has, in what order, at what offsets. Objects built the same way share one; code that only ever sees a single hidden class is code V8 can specialize hard. That's what monomorphic means (a fuller treatment comes below).

What Crankshaft was bad at, and what eventually retired it: keeping pace with new ECMAScript features. Generators, classes, destructuring, let/const, async functions—every one was either grudgingly supported through baseline-only paths or left unoptimized. The team had to add every new feature to both compilers—and to a third C++ runtime that the bytecode-less baseline compiler interacted with. That cost was suffocating the team.

Ignition + TurboFan (2016–2017)

Ignition shipped first, in 2016, as a bytecode interpreter—V8 hadn't previously had one. Ignition was motivated by memory, not speed: a bytecode interpreter's memory footprint is dramatically smaller than baseline-compiled machine code, which mattered enormously for the mobile devices Chrome was deploying on.¹ As a side effect, Ignition gave V8 a single canonical place where every JavaScript program existed in a stable, structured form before any compiler ever looked at it. That single canonical form is what made the next three tiers possible.

TurboFan shipped next, and in May 2017 V8 v5.9 made the new pipeline default: Ignition for first execution, TurboFan for hot functions. Crankshaft was then removed in v6.1, and Full-codegen followed in v6.2—the latter release alone deleted more than 30,000 lines of code. TurboFan introduced two big ideas:

A layered architecture with explicit phases (typing, simplification, lowering, scheduling, machine-specific instruction selection). Each supported CPU architecture needed only a few thousand lines of architecture-specific code, against more than ten thousand per chip architecture for Crankshaft.² The layering made it tractable to add new optimizations and new ES features.
A "sea of nodes" intermediate representation that lets the compiler reorder operations very freely, exposing more optimization opportunities than a strictly ordered control-flow graph would.

For numerical code, TurboFan was much better than Crankshaft at getting out of the way: it could see through more closures, inline more deeply, eliminate redundant hidden-class checks, and unbox numbers more aggressively. If your code was already monomorphic and shape-stable, TurboFan generated meaningfully tighter machine code than Crankshaft did.

Sparkplug (2021)

For the next four years, V8 was a two-tier system: Ignition → TurboFan. The gap between them was real. Ignition's bytecode dispatch is fast as interpreters go but pays a per-instruction decode cost; TurboFan only kicks in when a function has been called enough times to justify its compilation expense. Functions in the middle—called often enough to matter, not often enough to optimize—were stuck paying the interpreter tax indefinitely.

Sparkplug, shipped in V8 9.1 in 2021, fills that gap. It is a non-optimizing baseline JIT that compiles directly from Ignition bytecode in a single pass, with no IR, no type specialization, and no hidden-class-based fast paths. It defers most real work to the same builtins Ignition uses; what it eliminates is the per-bytecode dispatch overhead. Leszek Swirski's framing in the Sparkplug post is what made it click for me: a CPU is itself an interpreter for machine code, and Sparkplug is a "transpiler" from Ignition's bytecode to the CPU's. The function moves from running in an emulator to running natively, but the work it does in each instruction is roughly identical.

Sparkplug's stack frames are bit-compatible with Ignition's. Debuggers, profilers, and exception handlers don't need to know Sparkplug exists. That compatibility is also what makes mid-loop tier promotion (on-stack replacement) trivial: because the layout matches, the engine can compile a Sparkplug version of a hot loop and patch the stack frame in place.

For numerical code, Sparkplug mostly matters at the boundaries—for kernels that are called occasionally, and for code paths around the hot loop that handle argument validation and dispatch. The actual hot loop, if you wrote it well, will eventually get to TurboFan or Maglev. Sparkplug is what runs the rest while the type feedback accumulates.

Maglev (2023)

Maglev, introduced in Chrome M117 in 2023, is a mid-tier optimizing compiler slotted between Sparkplug and TurboFan. It uses the same type feedback TurboFan does, performs many of the same specializations, and emits real optimized machine code. The difference: Maglev compiles roughly 10× faster than TurboFan and 10× slower than Sparkplug, with code quality calibrated accordingly.³ Its IR is a traditional SSA-plus-CFG form—the program as an ordered graph of basic blocks (a control-flow graph, CFG) in which every value is assigned exactly once. TurboFan's sea of nodes goes the other way on ordering—operations float free of any fixed order, and the compiler works out afterward when each one happens. Fixing the order up front is what keeps Maglev's register allocation simple, and simple register allocation is most of why it compiles fast.

Maglev is the moment in the pipeline where speculative type specialization arrives. For numerical code that means two things become true simultaneously, and earlier in the warm-up curve than they used to:

Hidden-class checks get folded. Where a site has only ever seen Float64Array arguments, Maglev collapses the hidden-class guard and resolves the element-load to a direct memory offset. The same monomorphism rules that pay off at TurboFan now pay off at Maglev.
Representation selection runs. Maglev has an explicit phase that picks the in-register representation for every value: integer, float, or boxed object. A Float64Array element is unambiguously a float, so Maglev picks the right register kind immediately. A plain Array of mixed numbers and strings forces a conservative boxed representation through the whole loop. This is the moment unboxing actually happens.

A second consequence of Maglev shows up on the way back. The fall itself is unchanged: a deoptimization returns execution to Ignition, and the invocation that broke the bet finishes in the interpreter—off Maglev and off TurboFan alike, not one tier down. What Maglev changes is the recovery. Sparkplug's code is never discarded, so the next call starts in baseline machine code rather than in the interpreter, and the optimizing tier the function reaches on the way back up is Maglev rather than TurboFan. Older talks describe the deopt cliff as full machine code → interpreter, with a long crawl back. The drop is the same height; the climb out is much shorter.

Turboshaft (2023–2025), not an execution tier

Turboshaft is the one entry on this list that isn't a tier, which is why the count above stays at four. In 2023 V8 began an internal effort to migrate TurboFan off the sea-of-nodes IR onto a more conventional CFG-based form, called Turboshaft. The reasons were prosaic and accumulated over a decade: sea of nodes is flexible but cache-unfriendly (related operations end up scattered in memory), bugs are harder to investigate, and rewrite passes had grown gnarly. The blog post describing the move shipped in March 2025; by then the entire JavaScript backend of TurboFan had migrated. Compile times roughly halved versus the sea-of-nodes era.⁴

Turboshaft is invisible at the source level—the optimizations TurboFan does are still the optimizations it does—but it shifts the engineering economics. Faster compilation means functions reach optimized code sooner, so a bigger share of any run executes in fast code rather than warming up. For long-running Node services and notebook-style scientific JS, that compounds. It also makes future optimization work cheaper, which means more of it.

Putting the ladder back together

A simplified schematic of the modern pipeline, including deopts:

Every promotion is gated on type-feedback signals collected by the tiers below. Every deoptimization returns to the interpreter, whichever tier it left. The path each function takes is its own—there is no global compile pass—and a function's currently-running tier is observable with node --trace-opt and friends.

For numerical code: given enough warmup, an inner loop you care about will end up in TurboFan/Turboshaft (or Maglev, if it's not hot enough for TurboFan). The supporting code around it—argument validation, dispatch, the body of any function called occasionally—will sit at one of the lower tiers indefinitely. The discipline you apply to the hot loop pays off most at the top of the ladder; the discipline you apply to the supporting code pays off mostly by keeping a megamorphic inline-cache site or a hidden-class change from deoptimizing the hot loop.

One boundary worth naming: V8 also compiles WebAssembly, through its own baseline and optimizing tiers. It's a separate pipeline with a separate story, and out of scope here.

The representation primitives that make this work

The compiler tiers are the layer most people think about, but the value representation they operate on is doing just as much of the work. A handful of pieces show up in every V8 numerical-performance discussion.

SMI vs. HeapNumber

V8 uses pointer tagging. A 64-bit slot whose low bit is zero is a Small Integer (SMI)—a signed integer stored directly in the slot, no allocation, no indirection. The payload is 31-bit on builds with pointer compression and 32-bit on builds without. That's worth checking rather than assuming: Chrome enables pointer compression, official Node builds don't, so on Node 2**31 - 1 is still an SMI. node -p "process.config.variables.v8_enable_pointer_compression" answers it for your build. A slot whose low bit is one is a tagged pointer to a heap object. V8 stores any number that doesn't fit in the SMI range—floats included—as a HeapNumber: a heap-allocated wrapper containing a 64-bit double, referenced from the slot by a tagged pointer.

That's why the boxed vs. unboxed distinction matters. In Ignition and Sparkplug, every floating-point arithmetic operation reads through a HeapNumber wrapper, possibly allocates a new one for the result, and adds garbage-collection pressure. In Maglev or TurboFan, once the optimizer has stable feedback that a value is always a float, it strips the wrapper: the raw 64-bit value lives in a CPU floating-point register, and arithmetic compiles down to a single floating-point instruction. A tight loop of thousands of float operations collapses to bare register arithmetic. Without unboxing, every number in your hot loop allocates.

Pointer compression (V8 8.0, 2019)

Pointer compression shrinks every tagged slot from 64 bits to 32 by allocating all V8 objects within a 4 GB region and storing offsets rather than full pointers. The "base" half is shared per isolate; the "index" half is what gets stored. The headline number: heap memory dropped ~40%.⁵

The visible effect on a numerical workload is mostly cache behavior. Halving slot sizes means each cache line holds twice as many tagged values, and arrays of objects (rare in stdlib's hot loops, common around them) become half as cache-cold. Pointer compression also constrains what the compiler can do—for instance, every dereference now requires a base+offset compute—but the cache wins generally outweigh the new instruction.

Mutable heap numbers (V8, 2025)

A subtler 2025 addition: in-place updates of HeapNumbers in script-context slots. Previously, a script-level let seed = ...; seed = next(seed); pattern would allocate a fresh HeapNumber on each reassignment, even when the optimizer could prove only a single number was being threaded through. Now the slot can own its HeapNumber and mutate the underlying double in place. The case study in the post is Math.random's state. For numerical code that uses module-scoped accumulators or threaded random-number-generator state, this eliminates a previously-invisible per-update allocation.

Hidden classes and inline caches

Every V8 object points to a hidden class that records what properties it has, in what order, at what offsets, and with what attributes. The naming is genuinely a mess, and it isn't your fault if you've been tripped up by it. One concept, and every engine picked a different word for it:

Engine	Calls them
V8	`Map` — nothing to do with the JavaScript `Map` builtin
SpiderMonkey	Shape — widely borrowed, so you'll meet it outside Firefox
JavaScriptCore	Structure
Chakra	Type

Hidden class is the fifth name, and the one this post uses.⁶ Academic papers use it—but so does V8, constantly, in its own documentation, whenever it's explaining rather than implementing. The heap doc introduces Maps as "also known as hidden classes or shapes" and heads the defining section "The Map (Hidden Class)"; V8's docs page on the subject is titled Maps (Hidden Classes) in V8. It isn't the obscure choice—it's the one term that travels across all four engines and back into V8's own prose.

Two objects with the same hidden class are bit-compatible to V8's fast paths. Hidden classes are built incrementally: each added property transitions the object to a new one, which is why { x, y } and { y, x } end up different despite having the same property names.

If you come to this from C or C++, Benedikt Meurer's talk on types, classes, and maps offers the translation that tends to land hardest: a V8 hidden class plays roughly the role of a vtable pointer plus a field-offset table. "Keep the hidden class stable" then reads as the same discipline: don't reshape a struct at runtime.

Inline caches (ICs) are per-call-site memoizations of the hidden classes the site has seen. The hot path replaces dictionary lookups with a hidden-class check plus a load from a known offset. As long as a site only sees one hidden class (monomorphic) it stays fast. With two to four it becomes polymorphic—a chain of compare-and-load attempts. Past that threshold V8 gives up and falls back to a generic dictionary lookup (megamorphic), and the hot-loop assumption is over.

Hidden-class stability buys more than a fast IC, though. As Vyacheslav Egorov works through in What's up with monomorphism?, a monomorphic site lets the optimizer treat repeated hidden-class checks as redundant and eliminate all but the first. A polymorphic site structurally cannot get that: each variant needs its own guard.

ValidityCells are the trick that lets prototype-based code stay fast. Each prototype's hidden class carries a single-bit "still valid?" flag; ICs that depend on a clean prototype chain can collapse all their lookup checks down to a read of that bit. A mutation anywhere on a prototype chain (including, catastrophically, on Object.prototype) flips the cell, invalidating every IC that depended on it.

Anything that participates in a hot dispatch path has to be shape-stable—argument-shape validators, factory functions for option objects, anything that builds an object on the way into the kernel. The cost of polymorphism is not an extra cycle per access; it is the loss of the entire optimizer's bet on this call site.

Elements kinds

For array objects, V8 tracks a separate tag called the elements kind that describes what's in the numerically-indexed slots. Plain Array instances live on a six-cell lattice: PACKED_SMI / PACKED_DOUBLE / PACKED_ELEMENTS, plus the three HOLEY_* variants. The lattice is one-way. An array can be demoted from PACKED_SMI to PACKED_DOUBLE (by a single float write) to PACKED_ELEMENTS (by a single string or object write), or to a HOLEY_* variant (by delete, by new Array(n) without immediate fill, by writing past length). On the value-type axis the demotion is permanent for the life of that array, even if the offending value is removed—writing an integer back over the float doesn't restore PACKED_SMI. The holey axis is the one exception: Array.prototype.fill can return a holey array to packed, including one made holey by delete.⁷

Typed arrays—Float64Array, Int32Array, and friends—sit outside this lattice on their own elements kinds (FLOAT64_ELEMENTS, INT32_ELEMENTS, etc.). They cannot be demoted, cannot be made holey, and cannot have their type changed—the typed-array API enforces all three. From V8's point of view, a typed-array element is already in its raw machine-level representation on the backing buffer; reading one is a memory load, not a wrapper unwrap.

Typed arrays aren't an optimization; they're a guarantee. Every element is provably a fixed-width number, every access has a well-defined in-bounds outcome, every stored value is provably the right type.

That guarantee, rather than raw speed, is why numerical stdlib code is built on them—and the distinction matters, because the obvious version of the claim isn't true. A plain Array of integers isn't automatically slower than an Int32Array. Typed arrays even do work a plain array doesn't: every write is coerced to the element type, so 2**31 stored into an Int32Array reads back as -2147483648, and 300 stored into a Uint8ClampedArray reads back as 255.

What they buy isn't a lower floor. It's a narrower band. A plain array is fast right up until something demotes it, and then it's quietly slower for the rest of its life—and nothing in the code says so. A typed array can't be demoted, so the millionth call performs like the first. That's what write it like C is asking for; the Zen says "prefer predictable performance," not peak performance.

And one reason has nothing to do with the optimizer at all: a typed array is a view over an ArrayBuffer, which is the layout a C routine expects on the other side of a native add-on, so the data crosses without being copied.

What this means for stdlib-style code

This is where the aphorisms cash out. Each convention below protects one specific decision the machinery above makes, and once you can name the decision, the convention stops reading as a prohibition.

One dtype, one implementation. stdlib ships separate dasum and sasum—double-precision and single-precision absolute-sum kernels—instead of one polymorphic kernel that dispatches on argument type. Two stories combine here, elements kinds and ICs: passing a Float64Array and a Float32Array to the same function makes its loop body see two different elements kinds, so the IC at the indexed-access site goes polymorphic, and the optimizer's bet gets weaker on every successive call. Two separate functions, each used only with its own dtype, stay monomorphic. stdlib makes this argument in its own source, too. @stdlib/array/base/arraylike2object exists to normalize array-likes into one fixed-shape descriptor object, and its README says why in as many words: if objects are built with properties in different orders, "then those objects will have different 'hidden' classes," and a function fed enough of those shapes "will cause the function to be considered 'megamorphic'." The workaround is a helper whose only job is to hand every call site the same shape.

One of stdlib's maintainers frames the whole discipline in terms of the language it's imitating: "Just like in C you have to create every single different typed interface as a new function, we're doing the exact same thing." The proliferation of near-identical kernels isn't duplication that a cleverer abstraction would collapse. It's the point.

Hidden classes have to be stable up to and across the kernel. When a kernel takes an options object—a strided-ndarray descriptor, a BLAS-style transposition flag—every call site has to build that object the same way, with the same property names in the same order. If a caller mutates the object after construction (adds a property, deletes one), it transitions the hidden class out of whatever the kernel's IC was specialized on. stdlib's convention follows from that: every property defined at construction time, in a fixed order, never mutated afterward—and, where it matters, that construction centralized in a factory rather than left to each call site to remember.

Typed arrays do double duty. They give you (1) shape stability—Float64Array cannot become a Float32Array, cannot acquire holes, cannot become megamorphic—and (2) unboxed representation—every element is a raw double on the backing buffer, no HeapNumber wrapper. A plain Array of numbers can have the second: a PACKED_DOUBLE array stores raw doubles in a FixedDoubleArray, no wrappers. What it can't have is the first—and losing the first costs you the second. One string write demotes the array to PACKED_ELEMENTS, and every element becomes a tagged pointer again. The guarantee is what makes the representation durable.

Loops stay lean. TurboFan can optimize an enormous amount, but it cannot prove invariants the source doesn't make available to it. This is the mechanical content of be explicit—the optimizer is one of the readers whose mental model won't match yours. Three patterns follow from it:

Loop unswitching. Where a loop body branches on a value that doesn't change inside the loop (an option === 'conjugate-transpose' flag, say), stdlib hoists the branch out and writes two loop bodies. TurboFan has loop-invariant code motion, but it can't always prove an opaque comparison is side-effect-free, so the fix lands at authoring time instead—as a stdlib maintainer puts it, "if you need to duplicate loops, so be it." (In benchmarks it does a second job: it keeps the optimizer from eliminating the unobserved branch and silently measuring less work than you meant to.)
Scalar decomposition before entry. Where a complex scalar alpha is used throughout a loop, it gets decomposed once before entry—const re = real(alpha); const im = imag(alpha);—and the loop reads re and im. Even where TurboFan would have hoisted the calls, being explicit removes the uncertainty.
No allocation inside the loop. Calling .get(i) on a Complex128Array inside a loop allocates a complex-number object every iteration, so kernels cast to a Float64Array view of the same memory with @stdlib/strided/base/reinterpret-complex128 and read pairs of doubles instead. It's the same memory layout a C implementation would walk with a double* over interleaved real and imaginary parts, which is the part of write it like C that's literal rather than analogical. Athan Reines' accessor-protocol post unpacks that two-layer arrangement: logical complex-values on top, raw floats underneath.

The through-line: move anything invariant across iterations out of the loop at authoring time, rather than leaving it for the compiler to maybe hoist.

Plain arrays stay packed. Where a plain Array is unavoidable—the stdlib generic dtype, argument lists—stdlib builds it with a literal [ ] or with push rather than new Array(n) followed by index assignment, and removes indices with splice rather than delete. Once an array transitions to HOLEY_*, every read pays for a possible prototype-chain walk in case Array.prototype[i] was set. That cost is what fix them early is pointing at: on the value-type axis the lattice is one-way, so there's no later cleanup pass that undoes it, and even on the recoverable holey axis the fix has to be deliberate—fill is something you have to know to reach for, not something that happens on its own.

Prototypes don't change after instances exist. Adding a method to a constructor's prototype after instances exist invalidates every IC that watched that prototype. Adding anything to Object.prototype invalidates every prototype-walking IC in the running program. This is mistakes are infectious with a runtime mechanism behind it—one upstream mutation is paid for by every downstream caller, none of whom did anything wrong.

Verify, don't theorize. This was the part I found most reassuring, because it means none of the above has to be taken on faith. Run Node.js with --allow-natives-syntax and use %HaveSameMap(a, b) to confirm two objects share a hidden class, or %DebugPrint(arr) to read off an array's elements kind. Run with --trace-opt --trace-deopt to watch promotions and deopts scroll past, with the reason attached—wrong map is the one you'll see most, and it's worth knowing that's the string V8 prints for a hidden-class mismatch. IC state transitions are a little more work: the old --trace-ic flag no longer exists, and its replacement --log-ic writes to a file rather than to your terminal—V8's own tools/ic-processor then reads that file. For the generated machine code, --print-opt-code dumps it. For the IR, --trace-turbo plus Turbolizer.⁸ The decisions that matter for a hot path are observable, which means "is this really monomorphic?" is a question you can answer rather than argue about.

Benchmark hygiene. Microbenchmarks that look reasonable can measure nothing—Egorov's Performance Through the Spyglass is the canonical demonstration, and his one-line version of it is hard to improve on: optimizers eat microbenchmarks for dinner. The optimizer is allowed to constant-propagate, dead-code-eliminate, hoist invariants out of the timing loop, and unroll. stdlib's benchmark convention defends against this by including explicit lightweight assertions—e.g., a NaN self-inequality check (if ( x !== x ) { b.fail(...) }) inside and after the timing loop. The trick exploits NaN's inequality with itself: the check is false for any ordinary value, so the fail path never runs. But the compiler still has to observe the read of x (which defeats dead-code elimination) and it can't fold the check away.

Where this seems to be heading

The rules—monomorphic call sites, stable hidden classes, typed-array storage, lean loops—have held for a decade. The infrastructure underneath has been rebuilt three or four times and presumably will be again. I'm not going to pretend to know what V8 ships next, but three things look like they're already in motion:

Float16 and Float16Array arrived in browsers recently. The numerical case for half precision is mostly machine-learning-shaped (model weights, intermediate activations) but that case will increasingly intersect numerical-JS code living next to ML pipelines. stdlib has already moved: float16 is a working dtype with a real Float16Array behind it, and it participates in the promotion and safe-cast tables like any other. complex32 is the genuinely forward-looking one—it's named in @stdlib/ndarray/dtypes and in the dtype-kind taxonomy, but no Complex32Array exists yet to back it and its addition is slated as future work.
The Maglev → Turboshaft path keeps compressing the warmup curve. A hot loop reaches optimized machine code earlier on each successive V8 release, and where parts of a call graph used to sit in Ignition, never quite crossing the TurboFan threshold, they now land in Maglev instead. That makes occasional-path code matter slightly more than it used to: polymorphism in a moderately-called function is now something the optimizer has to account for, where before it wasn't looking.
Mutable heap numbers and similar fine-grained representation tricks are the genre of optimization V8 is shipping right now. These are mostly invisible from the source (good code keeps getting faster) but they reward the same disciplines that are already best practice: fewer abstraction layers between the source's intent and a single number in a single register.

Most of this is invisible if the kernels are well-behaved. That's by design. The optimizer's job is to take code that describes a numerical loop dynamically and execute it as if it were a statically-typed one. The shorter the gap between those two, the easier its job.

Which is where I ended up on the aphorisms. Write it like C isn't nostalgia for a language most of stdlib's JavaScript never touches, and don't be clever isn't a general plea for humility. They both describe the shape a speculative optimizer is looking for, written in the imperative because that's the form a convention takes. Fifteen years of compiler engineering went into recognizing that shape at runtime. The list is short because the shape is simple—which is also, I think, what simple is beautiful is doing at the end of the Zen of stdlib.

Acknowledgments

This work was supported in part by the National Science Foundation under Award No. 2449410.

Disclaimer: Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

V8's Ignition announcement gives both figures: baseline-compiled machine code was occupying roughly a third of Chrome's JavaScript heap, and Ignition's bytecode is 25–50% the size of the equivalent baseline machine code. ↩
The launch post puts Crankshaft at "more than ten thousand lines of code per chip architecture," against a few thousand for TurboFan's architecture-specific layer. ↩
Both ratios are the V8 team's own: Maglev compiles roughly an order of magnitude faster than TurboFan and an order of magnitude slower than Sparkplug. ↩
The Turboshaft write-up reports compile time "divided by 2" versus the sea-of-nodes pipeline. ↩
The ~40% heap-memory reduction is reported in V8's pointer-compression write-up. ↩
The engine-by-engine mapping is Mathias Bynens and Benedikt Meurer's, from JavaScript engine fundamentals: Shapes and Inline Caches (14 June 2018). Their list adds the collision warnings the table compresses away: Hidden Classes is confusing with respect to JavaScript classes, Maps with respect to JavaScript Maps, and Types with respect to typeof. ↩
V8's elements-kinds post carries an inline amendment, "Update @ 2025-02-28: There is now an exception to this for Array.prototype.fill specifically," and gives no further detail. Testing on Node v24.19.0 puts the exception slightly wider than the note implies: fill restores packed status from delete-induced holes as well. ↩
Singh's NodeBook has flag tables—informational, behavioral, and how to pass them—which are a far better starting point than the raw --v8-options dump. ↩

Your AI Policy Doesn't Have to Apply to You

Mara Averick — Wed, 12 Aug 2026 14:06:03 +0000

A confession: stdlib doesn't have an AI-use policy.

It isn't for lack of trying. There's an open RFC proposing guidance on AI usage—citations to prior art, disclosure requirements, a carve-out for "good first issue"¹—and a draft PR with the policy text, both of which are from December 2025.² Both are still open. Both are still drafts.

It's not because AI usage is hypothetical here, either. We've had stdlib core contributors participating in METR's randomized trial on AI's effect on experienced open-source developers since 2025. Philipp Burckhardt, one of stdlib's co-maintainers, wrote up his experience on the project blog, including which tools he uses and how his workflow changed.³ More recently, Karan Anand described using the codebase itself as the prompt.

So: we use these tools, we've said so in public, and (beyond some check boxes in our PR template) we still haven't codified what we expect from anyone else. We've gotten stuck, and one of the sticking points has been an obvious one—discomfort with publishing a rule we're not going to hold ourselves to.

This is a real objection. It's also, I've come to think, the wrong one, and we're not the only project stalling out on it. The question isn't whether AI is being used on this project. It's whether there's anything written down that a contributor can read.

Plenty of projects got past this. Melissa Weber Mendonça keeps a running catalog of what's been published;⁴ Kate Holterhoff's RedMonk survey was up to eighty-six policies as of April 2026, dimensionalized by stance and primary concern;⁵ CHAOSS's AI-alignment working group runs a companion list with an incident-and-discussion layer.⁶

Given the scope of the discourse around AI usage in open source, this is a strikingly small corpus—and a young one.⁷ Nobody is late to a settled consensus here. As James Fredley put it, after a tier-by-tier read from the primary documents: "there is no single industry-wide standard yet."⁸

What the policies themselves agree on is narrower than it first looks. Stance splits three ways—permissive, ban, undecided—and the stated concerns split at least three ways again: code quality, licensing liability, and ethics. Where they do line up is on something small and specific: contributors are responsible for understanding what they submit. Sean McLellan's case for the Assisted-by: Git trailer states the reasoning plainly—using Co-authored-by: claims shared authorship, and with it accountability. A tool can't hold up its end of that bargain.⁹ The trailer itself is one lightweight implementation; the claim underneath it is what travels.

Accountability is what the trailer is for; responsibility is what the policies actually ask of you. Part of that is legal clarity—the human is the sole author of the commit, whatever helped them write it. But what responsibility looks like in practice depends on the author's relationship to the project.

Two mechanisms tend to get bundled together here. Disclosure is a record-keeping rule—the Assisted-by: trailer, the AI-assistance section of our own PR template—and what it produces is provenance: what helped write this. Everyone takes part in that one. Gating is a permission rule: who may use these tools, on what, with how much latitude. What follows is an argument about the gate, not the disclosure.

A maintainer who merges a bad change is still there in three months when it breaks. They wrote the module it broke, or reviewed it, and they will be the one bisecting at midnight to find out why the build went red. Responsibility, for them, isn't a claim. It's a structural fact about where they're standing.

An infrequent contributor who submits a bad change usually isn't there. Not out of bad faith—that's simply what infrequent means. Whatever I take responsibility for this means when they sign off on their PR, it can't mean quite the same thing as it does for a maintainer. The position it's said from is different.

So a policy that says you're responsible for what you submit is asking two structurally different things of two structurally different people, while looking like it asks one thing of everyone. That's roughly where our hypocrisy objection came from. It's also, it turns out, where the objection comes apart.

The word for it

There's a word for a rule that behaves this way, and I'm going to use it even though it's unfamiliar, because the precise word does work the familiar ones don't.

A rule can be defeasible: correct as a default, and properly overridden when the situations it applies to genuinely differ. The everyday version is the speed limit is 45, except for the ambulance. The rule holds. The exception is principled. The exception doesn't retroactively invalidate the rule.¹⁰

The open-source policy version goes something like this:

There's a naïve consistency heuristic: don't require of others what you wouldn't do yourself. It's correct for most governance choices. Don't require signed commits if you don't sign yours. Don't require test coverage your codebase doesn't have.

But it's defeasible where the situations genuinely differ, and AI-use policy is the clean case. A maintainer using AI owns the fallout, holds the project's mental model, and can recognize when the output is wrong. A first-time contributor using AI may be offloading understanding to the tool—producing work they can't fully vouch for—and has no accountability chain yet. Those are different situations. Different rules are warranted.

The distinction comes down to what's underneath the rule. Because I own the fallout in a way you don't is principled. Because I said so isn't. The trust ledger is what makes the difference legible, and it's why "just be consistent" is worse advice than it sounds.

The naïve-consistency rule is itself defeasible. That's the whole thing. It's a good default, it does honest work most of the time, and this is one of the situations where the exception is warranted rather than merely convenient.

Ghostty's AI_POLICY.md lays out the usual disclosure-and-human-in-the-loop rules for contributions, and then closes with this:¹¹

These rules apply only to outside contributions to Ghostty.
Maintainers are exempt from these rules and may use AI tools at their discretion; they've proven themselves trustworthy to apply good judgment.

Two sentences. The first says this policy is for you, the contributor, not for me. The second says why. And the why isn't brash authority—it's a claim about accumulated context. They've proven themselves. You can agree with it, or push back on it, or ask what the proving consisted of.

So: you (potential contributor) can weigh and evaluate the claim. Naming the asymmetry on the page—rather than writing a symmetric-sounding rule and then quietly not applying it to yourself—is the move. It's two sentences. It's been shipped, in public. Just like a good CONTRIBUTING.md, the honest accounting is a kindness.

"You're just formalizing hierarchy"

There's a critique here I too feel the pull of, and it might be part of what keeps projects like ours from making the move. You're building a hierarchy where maintainers get one rule and contributors get another.

The hierarchy is already there, and has been the whole time—and it's not just maintainers vs. contributors, there are often tiers of trust (maintainers is just a useful shorthand). A maintainer with three years of context on a codebase reads a stranger's PR differently from how they read their own or one of a long-time contributor. The maintainer/reviewer knows what's load-bearing, what's under active refactor, which review objections are terminal versus fixable. None of that is malicious; most of it isn't even conscious. It's what accumulated context does. Call it a "trust ledger" (a term I'll return to in a subsequent post).

What a written policy does is convert an existing asymmetry from invisible-and-unchallengeable into visible-and-contestable. That's an accountability gain, not a hierarchy invention. Writing it down is what makes it something you can be held to.

If you've been sitting on a policy because the but-I-don't-hold-myself-to-this objection kept stopping you: note it, acknowledge that it does ethical work worth respecting in most contexts, and it doesn't apply here in the way it feels like it does. The situations genuinely differ. Different rules are principled when the difference has a reason you can be held to.

I'm not saying every project should ship one; whether it's right for a given project depends on more than fits in a piece this size. What I am saying is that this particular reason for stalling—the hypocrisy-avoidance reason, the one that stopped us—is dissolvable.

Take it, if it's useful. Ours has been open since December; I'm hoping this is a step towards closing it out.

Mara Averick is a developer advocate at Quansight and contributor experience lead for stdlib.

Acknowledgments

This work was supported in part by the National Science Foundation under Award No. 2449410.

Disclaimer: Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

stdlib-js/stdlib issue #9347, "[RFC]: Add guidance concerning AI usage"—proposing disclosure of AI assistance in pull requests and issues, excluding good first issue work from AI-assisted resolution (per the draft PR's rule 5: "these issues are intended to help newcomers learn about the project and gain experience with the mechanics of contributing"), and ruling out model output posted as comments on GitHub or Zulip. Opened December 24, 2025. ↩
stdlib-js/stdlib pull request #9459—the companion draft PR adding the policy text, opened December 31, 2025; still a draft as of this writing. ↩
Philipp Burckhardt, "Using AI in the development of stdlib," Numerical Bits, July 17, 2025—a reflection on stdlib's participation in METR's "Impact of Early-2025 AI on Experienced Open-Source Developer Productivity" study, in which two stdlib core contributors worked randomized project issues under AI-allowed and AI-disallowed conditions—a snapshot from early 2025; both the models and the surrounding tooling have changed considerably since. ↩
Melissa Weber Mendonça, open-source-ai-contribution-policies—a community-sourced catalog framed simply as "a list of policies by different open source projects about how to engage with AI-generated contributions." Roughly 100 project rows as of August 2026, plus separate sections for ongoing discussions and adjacent references. ↩
Kate Holterhoff, "The Generative AI Policy Landscape in Open Source," RedMonk, February 26, 2026 (with rolling edits through April 12, 2026). The dimensionalized cross-section—stance, primary concern, disclosure requirement, adoption date—of the same underlying corpus Melissa's catalog and CHAOSS's list track from different registers. Companion visualization site. ↩
CHAOSS AI Alignment Working Group, "Awesome LLM Policy," live PR-editable catalog with a nine-part taxonomy—including discussion threads and incident evidence as first-class categories alongside finished policy artifacts. ↩
The adjacent body of work is about as short as the list of trackers. Sviatoslav Sydorenko's EuroPython 2026 reference gist collects the maintainer-side tooling and files both Holterhoff's RedMonk piece and the CHAOSS list under "Surveys of the policy landscape"; the three trackers each reference the other two. ↩
James Fredley, "Assisted-by: How open source projects are drawing the line on AI contributions," All Things Open, May 11, 2026. A tier-by-tier read from the primary documents—QEMU, Gentoo, and NetBSD at the total-ban end; LLVM, Fedora, the Linux Kernel, Apache, OpenInfra, OpenTelemetry, and Rocky Linux across the permissive-with-disclosure middle—arguing that Assisted-by: is settling in as the de facto convention over Co-authored-by:, which "implies legal personhood." Fredley is chair of the Apache Grails PMC. ↩
Sean McLellan, "Assisted-by git trailer: provenance for AI-assisted commits," Barista Labs, June 20, 2026. Key line: "Co-authorship says this entity shares authorship and accountability." Pulled into stdlib's own trailer discussion by Athan Reines' (comment on issue #9347)—not necessarily the line's original point of entry into OSS AI-policy discourse, just where this piece's thread of it traces back to. ↩
The term has a longer life outside software. H. L. A. Hart, "The Ascription of Responsibility and Rights," Proceedings of the Aristotelian Society, New Series 49 (1948–1949): 171–194, is the canonical statement of the legal version—rules that hold unless a specific exception overrides them. John L. Pollock, "Defeasible Reasoning," Cognitive Science 11, no. 4 (1987): 481–518, formalizes the everyday version: how people reason with rough-and-ready rules that new information can defeat, and what it takes for an override to count. ↩
Ghostty, AI_POLICY.md (fetched 2026-08-03). Iterated in public via PR #8289 (initial disclosure rules, August 2025) and PR #10412 (hardened into the standalone policy, January 2026). ↩

Do you WANT contributors?

Mara Averick — Thu, 23 Jul 2026 16:12:00 +0000

My open-source origin story goes something like this: I fixed a typo, tweeted some stuff, tripped, fell, and found myself in the inner circle of a large-scale OSS ecosystem with an active, supportive community! It's trite but true—neither universal nor unique. But "inner circle of a large-scale OSS ecosystem" is where I landed, and it's colored a lot of what I've written since—including an implicit assumption that you (person who is reading this) are trying to build an ecosystem-scale project too.

POSE (Pathways to Enable Open-Source Ecosystems) has it right there in the name. It expressly describes this shape as the first item in the list of activities it's meant to support:

Building and maintaining a distributed community of external contributors who will actively participate in the ongoing development of the open-source product.

However, this isn't the only (or even the most common) experience for open-source maintainers or projects. Most projects run on one to three active maintainers.¹ Solo isn't a failure mode; it's the default.

There's a wide spectrum of how folks define open source: from "it's just a license" to "radically open and participatory." For the rest of this post to land, I need you to accept the license-end as at least legitimate—not right, necessarily, just legitimate. There's no need to re-litigate the decades-long disagreement in order to say that you, as a maintainer, get to decide the bounds of participation in your project.

An open-source project's first few artifacts are click-through: license (checkbox), README (template), .gitignore (whatever your framework spits out). Then you hit CONTRIBUTING.md—the first artifact that actually asks you what you want. Sure, there are best practices and helpful guides for you to follow, but it's where your project starts having opinions instead of defaults. So it's worth pausing and really unpacking what you want yours to look like. It's more than the mechanics of filing issues and submitting pull requests: CONTRIBUTING.md is the foundational framework for the relationship between your project and the unnamed masses who may or may not encounter it.

In fairness, the bare-bones version of contributor guidelines may work just fine for you. Or you and your project may have a version that was working in the past, but no longer feels sufficient.

For years, I had a Venn diagram I used in talks to illustrate what I called the "FOSS happy place":

It wasn't a lie—it reflected my early experience as a contributor to open source (even if my contributions weren't code-shaped). It's still not "wrong," per se. But it is guilty of radical oversimplification—not quite discretizing a continuous variable, but definitely improper dimensionality reduction. Critical features, like time, remuneration, and changing conditions/priorities are nowhere to be seen.

I'm not the only one whose journey was typo fix → full-time job/way of life. Kent C. Dodds (among the best in the game of open-source developer experience, in my opinion) describes a similar origin story in How getting into Open Source has been awesome for me (2020). I mention him for two reasons, and neither is throwing him under the bus: one, it's not just me; two, it's not dev-rel delusion—because (unlike me) he's a lines-of-code, PR-reviews, engineer-shaped maintainer of a widely used open-source project (Testing Library).

A career in open source isn't always a heart-eyes-emoji experience. Evan Czaplicki gave a great (aptly named) talk at Strange Loop 2018: The Hard Parts of Open Source. The challenges he describes seem somewhat inherent to the craft: you can't please everyone, conflicts will arise, things that once motivated you will be deeply draining at times. Anyone who's struggled through a group project in school will recognize the shape. None of that friction is new—LLMs didn't create maintainer burnout. In a 2019 piece by Nadia Eghbal, "The rise of few-maintainer projects", she wrote:

The salient issue for maintainers today is less about growing contributor numbers and more about navigating the flow of developers who are clamoring for their time.

Sounds familiar, right? AI has ratcheted things up. Maintainers are seriously rethinking what their relationship to their projects and users looks like. And here's where I return to CONTRIBUTING.md because this is a place where you get to be explicit about the choices you're making. Even if nobody reads every word (and most people don't read CONTRIBUTING files at all), writing one is how you set your boundaries in the first place. A CONTRIBUTING.md that reads:

No thanks! I'm gonna go it alone.
But feel free to fork and do whatever you like!

may not be what you're used to seeing (in fairness, that sentiment is likely carried through the absence of a CONTRIBUTING file), but it's legitimate. Or, maybe you think it isn't. Maybe it's anathema to open source, BUT it is a move that someone could make.

Am I recommending it? No. But I'm not you. I'm not everyone. And, importantly, it forces you to acknowledge that you get to set your boundaries and expectations. Again, this is an oversimplification. If you're maintaining a mature project with a set governance pattern and change-management process, waking up and burning your contributing process to the ground is likely to have serious fallout. But, that doesn't mean that you can't experiment (especially if the status quo feels like you're headed off a cliff.)

Certain projects have, by design, made the bar for contribution high for legitimate reasons. Debian's already the perfect example of a working gatekeeping mechanism that's high-demand. You need a sponsor, you find a mentor, you meet in person with someone who can vouch for you—as Nadia Eghbal put it, "Debian's process is built on the need for trust."²

But Debian is one shape among several. Athan Reines pitched a taxonomy for this: not "how open is your project" on a slider, but "what shape of project are you actually running?" He described four archetypes: the walled castle, the clique, the university, and the hippie commune.

The walled castle (or black box). You get the code, but the drawbridge stays up. SQLite is the cleanest live example. Their copyright page has a section literally titled "Open-Source, not Open-Contribution," which says:

SQLite is open-source, meaning that you can make as many copies of it as you want and do whatever you want with those copies, without limitation. But SQLite is not open-contribution...the project does not accept patches from random people on the internet.

You can't misread that. It's on their homepage. This archetype fits when the maintainer has a firm boundary they don't want to soften—a totally legitimate choice. It also fits when there's an author who's just done. The question: Do you want contributors? The answer: No.

The clique. You need to know the right people to get the secret password. OpenBSD is the best not-pejoratively-clique example I could find. Their hackathons page says, plainly: "Hackathon attendees come by invitation only. Some new people in the community who show promise are sometimes invited to see if they have what it takes." Linux kernel subsystems run on the same social logic at scale: the kernel docs describe a "chain of trust" where pull requests from unknown developers are received warily by subsystem maintainers until they've earned their way in. This archetype fits when the cost of misplaced trust is high and the mechanism for establishing trust is "does someone I already trust vouch for you."

The university. If you do your homework and score high enough on your exams, we'll admit you. Debian's process, above, is the archetypal case: the sponsor and mentor are part of a longer sequence that includes an application manager, a Philosophy & Procedures exam, a Tasks & Skills exam, and then DAM approval (or not). Their own docs are unusually honest about the deal: "the whole NM process is very strict and thorough. This is not meant to discourage people... but it does explain why the New Member process takes so much time." Kubernetes runs the most numerically explicit ladder I've seen: Member (sponsored by two reviewers from different companies), Reviewer (primary on 5+ PRs, reviewed 20+ substantial ones), Approver (30+ merged, nominated by a subproject owner). If you want the stdlib-adjacent case, pyOpenSci has documented onboarding flows for reviewers and editors: guest-editor probation, editor-in-chief nominations, a peer-review process modeled on academic journals. This archetype fits infrastructure that's load-bearing enough that mistakes are expensive to unwind, and it works if the syllabus is real. (It fails, badly, if the syllabus is a rebrand of "vibes-based homework we won't tell you the rules of.")

The hippie commune. Do you have a pulse? Yes? You're in. freeCodeCamp basically checks for a pulse and hands you a first timers only label. Their whole cultural stance is "let us help you land your first PR." I've been part of projects like this, and it's actually onerous in its own way. But, they're where a lot of folks get started. Without these, the rest of the spectrum loses its future contributors and maintainers. MDN Web Docs runs the same posture on the docs side: their contributing guide is basically "there's a place for you here, even if your grammar isn't perfect." (Wikipedia is the mother of this archetype but isn't code-shaped, so treat that as a cultural reference, not a technical one.) This archetype fits projects where the marginal contribution has low blast radius, and the real bottleneck is reach or discoverability, not integration cost. It also fits projects whose goal is teaching people to contribute, where the code is almost a byproduct of the mentorship.

In reality, there is, of course, a spectrum—and shades of gray as well. A project doesn't necessarily have to operate in a single mode, either. SQLite runs some clique-shaped review practices under its walled-castle surface. Debian's university process has real clique-shaped social realities inside it. Any given project can occupy more than one archetype at once—a codebase that's walled-castle at the core and hippie commune at the docs layer, say. And most projects drift between shapes as they age.

I also want to be clear that you're ALLOWED TO MOVE where your project is at. Is hippie-commune mode failing you in the age of AI slop? Maybe you run an experiment with a more rigorous onboarding (or have folks who have already contributed to the project mentor newcomers through their first PR so that the onus doesn't always fall on the maintainer.)

There is no more a platonic form for a perfect CONTRIBUTING.md than there is for a universally "perfect" job. The fit is between your project and its contributors. What works for one can be exactly wrong for another.

But here's why the taxonomy belongs in a piece about what you actually want: it forces you to say the thing out loud. "I want a hippie commune" is a different maintainer future than "I want a university," and both are different from "I want to keep the code out here but the process in here." You can't dodge the question by writing a CONTRIBUTING.md that just describes issue templates. The people who read it (the ~7 who will) can tell which archetype you're aiming for even when you haven't named it. Might as well spell it out.

There are pros and cons to the types of friction you introduce—selectively inviting who can interact, permanently banning a suspected peddler of AI slop, toggling off the "Issues" section of a repository. But, if the relationship (that between a maintainer and contributors) is evolving in such a way that it feels like it cannot hold, that's its own type of failure. Neither the maintainer nor "the community" are to blame when things end in a silent resignation or a public crashout—but maybe they can be avoided by experimenting with things you hadn't previously considered as being "worth it."

Like my old FOSS-happy-place Venn diagram, the chart below doesn't capture the n-dimensional reality of working in open source. But I'd like to think it's an improvement. On the x-axis you have maintainer/project (dis)comfort. And the y-axis is something akin to ROI (return on investment)—demand from contributors/community/ecosystem.

The catch is that you don't really know where an experiment lands on this chart until you try it—not how much it'll cost you (the x-axis), and not what you'll get back (the y-axis). That doesn't mean you have to try everything. But it's worth paying attention to where things actually fall, rather than where you assumed they would.

Here are some things that we're trying (or considering taking for a spin):

Code review as the alignment step. Ed Yang makes the case that code review is where humans do the alignment work now. As AI takes on more of the implementation, the reviewer's job shifts away from line-by-line mechanics and toward the big-picture questions—does this fit, should it exist, is this the shape we want?
Using AI as a market-research companion, not a PR-generation machine. Instead of AI writes the pull request, it's AI helps you see the landscape. Feed it the parallel projects—for us that's NumPy, SciPy, Math.js, and friends—let it aggregate the patterns everyone else has converged on, and then you decide what fits. Same tool, pointed at what should we build instead of let's crank out code.
Livestreamed PR review. Twitch, Discord, YouTube—pick your poison. Someone watches a maintainer work through a review in real time. The discomfort scales hard depending on who you are (some folks would genuinely rather chew glass than do their job on camera), but it puts other humans in the room at the moment you're deciding something. And it teaches in both directions: people watching learn what makes a good contribution and what being a maintainer actually takes. It's knowledge capture without the curation—which means it might surface insights you never knew people wanted.

None of this is guaranteed to work. Most of what gets written about open-source communities and contributor experience gets written after the fact—after something worked. That means there's a bottom drawer somewhere full of the things people tried that didn't (those posts mostly don't get written.) And even the experiments that did work worked in the specific conditions of that project—its size, its maintainers, its users, its moment. Different projects, different fits. This isn't Wills and Trusts. You can iterate. Your CONTRIBUTING.md can change. Your governance can change. Your mind can change. Whatever you want to do is okay—just own it. And if you're trying something (the thing that's working, or the thing that isn't) come tell us about it. We're figuring it out too.

Sources

Mara Averick is a developer advocate at Quansight and contributor experience lead for stdlib.

Acknowledgments

This work was supported in part by the National Science Foundation under Award No. 2449410.

Disclaimer: Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

Linux Foundation, OpenSSF, and Harvard LISH. Census III of Free and Open Source Software. December 2024. https://www.linuxfoundation.org/hubfs/LF%20Research/lfr_censusiii_120424a.pdf?hsLang=en; GitHub. Octoverse 2025. https://github.blog/news-insights/octoverse/octoverse-a-new-developer-joins-github-every-second-as-ai-leads-typescript-to-1/. ↩
Nadia Eghbal. "The Rise of Few-Maintainer Projects." Increment, 2019. https://increment.com/open-source/the-rise-of-few-maintainer-projects/. ↩

DEV Community: Mara Averick

The 2026 stdlib community survey is open

Acknowledgments

Lessons learned: 100 interviews about numerical JavaScript

What we did, and what the numbers can't say

Four major themes

1. The ecosystem doesn't answer is this right

2. AI is the densest theme, and it doesn't converge

3. Who showed up, and what they came from

4. The most valuable parts don't scale

What we still can't answer

Acknowledgments

Write It Like C: What V8's Optimizing Compilers Explain About the Zen of stdlib

A note on vocabulary

Why a numerical JavaScript lens?

A 15-year ladder

Crankshaft (2010–2017)

Ignition + TurboFan (2016–2017)

Sparkplug (2021)

Maglev (2023)

Turboshaft (2023–2025), not an execution tier

Putting the ladder back together

The representation primitives that make this work

SMI vs. HeapNumber

Pointer compression (V8 8.0, 2019)

Mutable heap numbers (V8, 2025)

Hidden classes and inline caches

Elements kinds

What this means for stdlib-style code

Where this seems to be heading

Further reading

V8 team primary sources

Talks and write-ups by V8 team members and adjacent practitioners

stdlib and stdlib-adjacent

Acknowledgments

Your AI Policy Doesn't Have to Apply to You

The word for it

"You're just formalizing hierarchy"

Acknowledgments

Do you WANT contributors?

Sources

Acknowledgments